直接答案
AGENTS.md 和 CLAUDE.md 都能把仓库约定带入编码会话，但加载规则与周边配置不同。高质量指令文件应简短、可执行，并把测试命令和边界写成可验证规则。
这篇内容解决什么问题
帮助同时维护两种编码代理指令文件的团队避免重复和规则漂移。
共同目标：把口头约定变成仓库上下文
两类文件都适合记录人类维护者希望代理长期遵守的信息，例如仓库结构、构建命令、测试入口、代码风格和禁止修改的区域。它们不应该复制整份 README，也不应该存放密钥。
判断一条规则是否值得写入的标准很简单：它是否会在多个任务中重复出现，并且能否通过命令、路径或审查结果验证。一次性需求应保留在当前提示词中。
AGENTS.md 侧重可分层的仓库约定
Codex 会按工作目录和仓库层级发现 AGENTS.md。根目录文件适合全局约定，子目录文件适合语言、服务或包级规则。维护者应明确每条命令从哪个目录执行，并避免在深层文件重复上层全部内容。
对于 monorepo，可以在根文件保留通用安全和提交规则，再在前端、后端或基础设施目录放置各自的构建与测试要求。
CLAUDE.md 结合项目记忆与导入机制
Claude Code 支持不同作用域的 CLAUDE.md，并允许通过导入组织较大的指令集。团队共享内容与个人偏好应分开：仓库文件进入版本控制，本地或用户级文件保留机器和个人习惯。
导入能减少重复，但也会增加依赖链。每个被导入文件都应有明确所有者，并在目录调整时进行校验，避免静默失效。
同时支持两款工具时的仓库布局
团队可以让两个入口文件共享事实来源，而不是维护两份逐字相同的长文。README 或 docs/engineering.md 记录稳定的人类文档，AGENTS.md 与 CLAUDE.md 只保留各自加载机制所需的规则和指向。
repository/
├── AGENTS.md
├── CLAUDE.md
├── docs/
│ └── engineering.md
├── frontend/
│ └── AGENTS.md
└── backend/
└── AGENTS.md
一份可维护的指令清单
优先写命令和边界，再写风格偏好。含糊的“保持高质量”无法验收，而“修改前运行 pnpm typecheck，修改后运行 pnpm build”可以直接执行。
- 仓库用途与关键目录，不超过一个短段落。
- 安装、开发、类型检查、测试和构建命令。
- 允许修改与禁止修改的文件范围。
- 依赖、数据库、部署等需要人工确认的断点。
- 最终答复必须报告的验证结果与残余风险。
把指令文件纳入代码审查
任何影响构建、权限或发布流程的指令变更都应像代码一样评审。至少每季度核对命令是否仍存在，并在 CI 中执行关键命令，防止文档与实际脚本分离。
当代理频繁违反某条规则时，先检查规则是否冲突、位置是否正确和描述是否可执行；不要只通过不断追加更长文字来解决。
官方来源与核验范围
本文以公开官方文档为事实依据；命令和配置可能随客户端版本变化，执行前请同时核对对应来源。
查看技术核验方法