---
title: "让 Codex 记住项目规矩：AGENTS.md 的分层写法与验收方法"
slug: "codex-agents-md-project-guide"
kind: "runbook"
version: "1.0"
status: "reviewed"
compatibility: "支持 AGENTS.md 的 Codex 环境；现有 Git 项目。具体发现规则以所用客户端官方文档为准。"
risk_level: "low"
requires_approval: false
updated_at: "2026-10-19T00:23:36.076Z"
verified_at: ""
source: "https://blog.atlankj.com/posts/codex-agents-md-project-guide"
---

# 目标

为现有项目建立简短、可验证的 Codex 指令，并说明实际适用范围。

# 前置条件

- 可读取项目目录及适用指令。
- 已明确允许编辑指令文件。
- 可读取现有包管理器、锁文件与验证脚本。
- 文档基于 2026-10-19 核对的官方资料，未在读者项目实测。

# 输入

项目根目录、目标模块、现有 AGENTS.md / AGENTS.override.md、用户给出的长期约定。

# 约束

- 保留原有有效约定，先检查冲突，不覆盖整份现有文件。
- 不虚构目录、脚本或测试通过结果。
- 本任务只编辑项目指令；安装依赖、业务代码修改和外部发布不在范围内。
- 不写入凭据、真实客户数据或个人信息。
- 不将 AGENTS.md 当作操作系统权限隔离机制。

# 操作步骤

1. 确认项目根目录、当前目录和目标模块，读取沿路径适用的指令。
2. 检查同目录 override 文件，报告实际指令来源。
3. 读取项目已有脚本，把可确认的约定整理为三到五条。
4. 在适用目录创建或增量更新 AGENTS.md；详细流程引用已有技能。
5. 检查新增指令是否与原有规则冲突。
6. 在新会话中请求列出加载来源；仅在用户已授权修改业务代码时执行正常修改场景。

# 输出结果

更新的指令内容、适用目录、依据、待确认事项和实际验证记录。

# 验证方法

- 路径和脚本均存在。
- 从目标目录开启的新任务报告预期指令来源。
- 将观察到的结果与预期分开记录。
- 未执行业务场景时明确标记未验证。

# 异常处理

- 发现冲突：展示冲突规则并按现有指令优先级处理，无法判断则询问。
- 指令未加载：检查当前目录、override 与客户端配置，重启会话复核。
- 缺少测试环境：报告限制，不声称测试通过。

# 回滚方式

编辑前保存相关文件的原始内容。回滚时只撤销本次指令变更，保留用户已有修改；没有确认备份时不使用破坏性 Git 恢复命令。

# 参考来源

- https://learn.chatgpt.com/docs/agent-configuration/agents-md
- https://learn.chatgpt.com/docs/build-skills