先给编码助手一张仓库地图
第一次让 Codex 修改项目时，你可能会发现：它读得懂代码，却不知道业务逻辑该放哪里、哪些文件不能直接修改，以及改完之后该运行什么检查。这些信息往往藏在老同事的经验里，不会自动出现在代码中。
AGENTS.md 就是写给编码助手的项目说明。把它放在仓库里，可以让助手在处理任务时读取约定，减少猜测。它不是项目代码，也不是权限控制工具，更不能保证助手永远不犯错；它的作用，是把你反复解释的规则变成可维护的文字。
第一份指令文件先放在仓库根目录
从最简单的做法开始：在仓库根目录创建名为 AGENTS.md 的纯文本文件。文件名保持这个拼写，内容可以直接使用中文，不需要特殊配置格式。
第一版不用写成完整手册。先回答四个问题：项目做什么、主要目录放什么、修改后怎样验证、哪些操作需要先确认。目录说明必须对应真实路径，不要照搬别人的项目结构。
用目录职责告诉助手去哪里改
不要只列出文件夹名称，还要解释职责和边界。例如，页面目录负责界面展示，业务目录负责业务规则，测试目录保存自动化测试。若仓库没有这样的分层，就按照现有结构写，不必为了说明文件重新整理项目。
下面这些句子可以作为起点，再替换成你仓库的实际情况：
- 页面相关代码放在页面目录，公共组件优先复用，不要重复创建相同功能。
- 业务规则集中在业务目录，界面文件中不要加入新的数据访问逻辑。
- 测试与对应功能保持相邻，新增行为时补充对应测试。
- 自动生成的文件不要直接编辑，应修改生成来源并重新生成。
路径越明确，说明越有用。正式写入文件时，请使用真实目录名，而不是只保留“页面目录”这样的泛称。
把验证步骤写成可执行的约定
“修改后记得测试”仍然太模糊。应写清在哪里执行、使用仓库中的哪条命令，以及成功的判断依据。命令请从项目脚本或现有开发文档中核实，不要让助手自行猜测。
例如，可以要求先运行受影响模块的测试，再执行项目已有的静态检查。如果检查依赖尚未配置的数据库或外部服务，也要注明前置条件，并要求助手如实报告未执行的检查，不能把“没有运行”说成“已经通过”。
子目录规则只补充局部差异
当仓库包含多个应用或组件时，可以在相应子目录再放一份同名指令文件。根目录写通用约定，子目录写局部要求；助手处理该范围内的文件时，会结合适用的指令，更深层的规则用于处理局部差异。
例如，根目录要求新增功能配套测试，某个界面子目录再补充交互验证要求。不必在每个目录复制整份规则，否则一处更新、另一处遗漏，很容易产生冲突。也不要把这个文件当成覆盖系统指令或当前任务要求的最高权限。
用一次小修改验收这张地图
写完后，先让助手完成一个范围明确的小任务，并请它说明参考了哪些目录规则、修改了哪些文件、运行了哪些检查。对照结果，你就能发现说明是否含糊，或者测试步骤是否缺少条件。
不要把密钥、访问令牌或生产凭据写进指令文件。对于删除数据、修改数据库结构等高风险动作，应明确要求先确认，同时继续依靠权限管理和人工审查兜底。
如果你准备通过 SwiftRelay 接入编码助手，可以注册账户，再按实际使用量付费体验；它支持 Codex 等工具。接入服务解决的是模型调用，仓库指令文件解决的是项目认路，两者不能互相替代。
第一圈的目标不是写出最长的说明，而是让下一次修改少一点猜测。目录调整、测试命令变化或团队约定更新时，把这份文件和代码一起维护，它才会一直有用。