What Makes a Good AGENTS.md

AGENTS.md / CLAUDE.md 是在对话开始前就预加载的指令文件。它不应成为项目知识库，而应成为 Agent 的工作合同。

What it is

• 系统提示：每个模型都有来自产品方的 system prompt
• 你的文件：AGENTS.md 会被追加进去
• 结果：模型在你对话前就已加载 system prompt + 你的指令

CLAUDE.md vs AGENTS.md

可以 symlink：把 AGENTS.md 链接到 CLAUDE.md，只维护一份，所有 Agent 自动识别。或让 CLAUDE.md 仅包含一行 import：@AGENTS.md。

Why it matters

AGENTS.md 的质量直接影响 Agent 的合规率和任务成功率。但写法已从"信息密度"转向"行为约束"——不是告诉 Agent 项目是什么，而是告诉它该如何行动、何时停止、如何证明完成。

Key points

1. 长度上限：200 行是天花板

Codex 的 project_doc_max_bytes 默认 32 KiB，且是从全局到项目根目录到当前目录拼接加载，写太多前置规则会挤掉最接近任务的本地规则。Claude Code 官方建议控制在 200 行以内，且 CLAUDE.md 会完整加载，越长越降低遵循率。

2. 必须包含 Do-NOT 和 Stop-and-Ask 列表

不是告诉 Agent 用什么，而是告诉它不能引入什么、不能独自决定什么。每条禁令应附带 Reason 和 Revisit 条件——让 Agent 知道规则为何存在、何时可以重新考虑。

3. 规则必须是 Agent 能在 5 秒内判断是否遵守的

"写干净代码"对 Agent 毫无意义。"Server components by default; add 'use client' only for state"才是可执行的。

4. 行为规则比项目描述更重要

Agent 的失控往往发生在行为层而非知识层。核心行为约束示例：

• Restate the goal in one line before coding; if unclear, ask
• Make the smallest change that satisfies the task
• Do not refactor nearby code unless asked
• Surface tradeoffs instead of silently picking one
• No new abstraction unless used in 3+ places

5. AGENTS.md 是路由器，不是图书馆

大型文档应拆分到 docs/ 或 .agent/PLANS.md，AGENTS.md 只保留一行指针："when you need X, go read Y"。

6. 敏感目录应有本地文件

src/auth/AGENTS.md、src/billing/AGENTS.md 等本地文件只携带该目录的风险规则，不是根文件的副本。Codex 中近者优先覆盖（AGENTS.override.md > AGENTS.md），Claude Code 中后加载的 carry more weight。

7. 意图写在文件中， enforcement 交给 hooks / rules / sandbox

AGENTS.md 是 "please remember"，真正阻断危险动作需要 PreToolUse hook、permission profile、sandbox_mode 和 CI。越危险和不可逆的动作，越应下沉到系统层。

8. 三类文件必须分离

• personal style: ~/.codex/AGENTS.md 或 ~/.claude/CLAUDE.md
• team convention: /AGENTS.md
• machine perms: .codex/config.toml 或 .claude/settings.json

9. 长期记忆必须是可审计的

MEMORY.md 记录 durable learnings，但只在 Git 中管理。自动记忆只是 backup，mandatory rules belong in the file。

10. Definition of Done 必须可验证

Before finishing:
1. run pnpm typecheck
2. run pnpm lint
3. run tests for changed files
4. report: files changed, what and why, verification run with results
5. report: verification NOT run, with the reason
6. report: remaining risks or follow-ups

Open questions

• 200 行上限是否同样适用于复杂 monorepo 的根部 AGENTS.md？
• 当 Agent 能自动发现项目结构时，Stack 段落是否还有必要保留？
• 条件块（<important if="...">）在 Codex 和 Claude Code 中的遵循率是否有差异？

Related

• claude-code/pawelhuryn-claude-decision-engine — CLAUDE.md 作为决策引擎
• claude-code/lessons-building-skills — Claude Code Skills 实践
• claude-code/overview — Claude Code 概述
• harness-engineering/overview — Harness Engineering 概述