项目级 Agent 指令文件（AGENTS.md / CLAUDE.md 同类）

这是一种什么做法

在仓库根目录放一份由项目维护者写、给 coding agent 阅读的说明文件，用来告诉 Agent：怎样安装、运行、测试、提交代码；项目目录结构是什么；有哪些代码规范、测试要求和禁止事项。目的是让新会话不必从零猜测项目规则。

AGENTS.md、CLAUDE.md 是不同 coding agent 各自约定的文件名，但作用高度一致：把"项目级规则"以可读文件的形式固定下来，跨会话生效。

适合哪些情况

• 已经维护一个真实代码仓库，希望 coding agent 每次进入都能从同一份规则出发，而不是临时推断。
• 项目有自己的构建、测试、提交流程，Agent 默认行为可能破坏这些流程。
• 多人协作，团队希望 Agent 的行为可被评审、可被修改。

典型字段（综合 HaiJun 复盘与 Claude Code 橙皮书等实践）

• 命令：安装、运行、测试、构建、提交的脚本与典型调用方式。
• 目录结构：哪些目录是源码、测试、配置、文档。
• 代码规范：语言版本、风格、lint/format 工具。
• 测试要求：哪些测试必须通过、覆盖范围、是否需要数据库/Mock。
• 禁止事项：不允许的命令（如禁止 --no-verify 跳过检查、禁止直接 force push、禁止删除数据）。
• 上下文指向：相关文档、ADR、需求文档的入口。

与现有 Wiki 的关系

• 与 CLAUDE.md 项目级指令文件（Claude Code 项目宪法） 互相引用：CLAUDE.md 是 Claude Code 自有约定，AGENTS.md 是更厂商中立的命名；本方法页是更高层的抽象，二者应作为同类方法的不同实现互相参考。
• 程序员HaiJun 在 Codex CLI 上使用 AGENTS.md 完成 8 个月长期复盘。
• 见 我用了 8 个月 Codex CLI，总结出这套 AI 编程工作流。

限制与检查点

• 文件本身的质量决定 Agent 的行为质量：写错或写漏的规则会被稳定放大。
• 不同 agent 对文件名的识别范围不同（根目录、子目录、.github/ 等），使用前应核对当前版本文档。
• 不要把 AGENTS.md 与 CLAUDE.md 当成相同配置文件——命名、字段语义和优先级可能因 agent 不同而不同。

相关任务

• 把 Codex CLI 接入现有真实项目：把 Codex CLI 接入现有项目时，建立项目说明文件是其中一步。
• diff 审查 + 第二轮 Agent 或人工复核：项目说明文件定义"禁止事项"后，再用 diff 审查确认 Agent 是否遵守。