agents-md

AGENTS.md 设置与审计

• 是： 配置代码仓库，让正在使用的每种 Agent 工具都读取相同的规则，然后审计、评分、重构并编写 Agent 在会话开始时加载的 AGENTS.md / CLAUDE.md / CLAUDE.local.md 文件。
• 不是： 编写 SKILL.md 文件（请使用 agent-skills-creator）、项目文档或 README（请使用 ghostwriter），也不是挖掘会话历史（如果已安装，请使用外部技能 cadence-advise；此技能会按文件当前状态进行审计）。

AGENTS.md 文件是执行契约，而不是知识库。以下两项测试可以发现一条规则失效的两种情况。

• 冗余内容：“删掉这条规则会让 Agent 犯错吗？”如果不会，就删掉；内容臃肿会让 Agent 忽略真正重要的规则。
• 有害的精确规定：“在此代码仓库中，是否存在任何合理任务会让这条规则不适用？”如果十次任务中有一次不适用，Agent 仍会在那次任务中遵守它，而且无法判断那是例外。说明你想要的结果，让周围的代码决定具体做法。将 NEVER write comments 改为 match the comment density of the file you are editing：更简洁，无需维护例外列表，而且在注释密集的文件中也正确，无需额外说明。

安全、数据丢失、格式约定，以及已观察到此代码仓库中的 Agent 确实会违反的规则，仍值得使用绝对表述。

AGENTS.md 是与工具无关的事实来源。Claude Code 内置的 agents-md 模块可直接支持它。请在根目录和指定范围的子目录中使用 AGENTS.md，不要使用 CLAUDE.md 包装文件或符号链接。当项目的 Claude 指令文件位于从根目录到工作目录的路径上时，默认的 claude-md-or-agents-md 模式会优先使用这些文件；迁移、设置和加载器限制请参阅 references/project-setup.md。移除旧文件前，请保留其中独有的指令。用户级和托管的 Claude 文件与代码仓库迁移相互独立。

选择模式

• 代码仓库没有 Agent 指令，或目标工具尚未接入 -> Setup：由 references/project-setup.md 决定要创建哪些文件，以及每种工具读取哪些文件；然后按照下文“从头编写”填充根目录文件，最后进行审计评分。
• 文件已存在，问题在于质量 -> Audit，见下文。
• 文件已存在，但内容臃肿、过时或评分不佳 -> Refactor，参阅 references/refactor-workflow.md。

参考文件

文件	阅读时机
references/project-setup.md	为 Claude Code、Codex 和 Cursor 配置代码仓库；确定要创建哪些文件，以及每种工具实际会加载哪些文件
references/quick-checklist.md	每次审计时；默认的 12 项快速检查
references/quality-criteria.md	快速审计未通过、文件风险较高或需要完整评分时
references/refactor-workflow.md	文件内容臃肿（根目录文件超过约 150 行）、过时或未达到目标时
references/root-content-guidance.md	确定哪些内容保留在根目录，以及将移出的内容放在哪里才能继续加载
references/repo-evals.md	衡量指令变更是否能让 Agent 在此代码仓库中更快或更准确地完成任务
references/templates.md	从头起草或重建文件

从头编写

这是 Setup 的内容编写步骤；如果代码仓库已完成接入，且仅缺少文件，则是完整任务。跳过审计。从清单（package.json、Makefile、CI 配置）中收集实际命令，从 references/templates.md 中选择一个框架，填入经过验证的命令和已知注意事项，然后依据 references/quick-checklist.md 检查，再交付。

审计工作流

复制此检查清单以跟踪进度：

Audit Progress:
- [ ] Step 1: Discover files
- [ ] Step 2: Select audit mode (quick or full)
- [ ] Step 3: Run audit and score
- [ ] Step 4: Report findings with score table
- [ ] Step 5: Propose minimal diffs
- [ ] Step 6: Validate changes
- [ ] Step 7: Apply and report before/after scores

步骤 1：发现文件

find . \( -name "AGENTS.md" -o -name "AGENTS.override.md" -o -name "CLAUDE.md" -o -name "CLAUDE.local.md" \) -not -path "*/node_modules/*" 2>/dev/null | sort
ls -la CLAUDE.md .claude/rules .cursor/rules 2>/dev/null

另请检查 ~/.claude/CLAUDE.md 和 ~/.codex/AGENTS.md；这两个文件会在每个仓库中加载。ls -la CLAUDE.md 可以告诉你它是符号链接、@AGENTS.md 指针，还是第二份副本；副本本身就是一项发现。对于单体仓库，请纳入工作区级别的文件。独立审查每个层级：根目录存放通用规则，子级文件存放特定目录的规则（参见 references/project-setup.md，了解每种工具会加载哪些文件）。

步骤 2：选择审查模式

• 快速（默认）：检查 references/quick-checklist.md 中的 12 项，目标为 >= 10/12。
• 完整：检查 references/quality-criteria.md 中的 49 项，目标为适用项得分的 >= 91%（A 级）。快速审查未通过、文件是高风险仓库的门槛，或用户要求完整评分时使用。

步骤 3：运行审查并评分

分别为每个根目录文件评分；从分母中排除 N/A 检查项。

步骤 4：报告发现

在进行任何编辑之前，先输出简明报告：

## AGENTS.md Audit Report

| File | Mode | Score | Grade | Key Issues |
|------|------|-------|-------|------------|
| ./AGENTS.md | Quick | 6/10 | Fail | Missing test command, stale path, doc-heavy section |

表格中的每个问题都必须对应到步骤 5 中的差异；不得含糊其辞。

步骤 5：提出最小差异

按优先级排序：

1. 修复失效或过时的命令；关注 bug，而非风格。
2. 删除通用、重复或过时的指导、对执行框架已有行为的复述，以及由自动记忆负责维护的事实。
3. 将每项项目技能（.claude/skills/、.agents/skills/、skills/）与根目录文件进行比较。如果两者陈述了相同事实或流程，只保留一份（流程保留在技能中，每项任务都需要的信息保留在根目录文件中），并在另一处留下一行指针。
4. 将一概禁止改写为其所要保护的结果；只有通过有害精准性测试时，才保留绝对禁令。
5. 将少于约 30% 的任务需要的细节移至按需加载的位置：相关目录中的嵌套 AGENTS.md、路径限定的 .claude/rules/*.md，或技能（而不是 @import；参见 Gotchas）。
6. 仅在 Agent 会忽略的关键规则上添加强调（“IMPORTANT:”“YOU MUST”），每次一行。

对于审查请求，提出差异。改进、重构或编写文件的请求已授权进行这些编辑；请直接应用并报告理由。

步骤 6：验证更改

1. 在环境允许的情况下，对核心命令（dev、test、build、lint/typecheck）进行冒烟测试；否则确认清单中存在对应脚本，并注明限制。
2. 检查每个链接路径和 @import 路径是否有效。在 Claude Code 会话中，/context 会列出实际加载的记忆文件；若某文件不在列表中，就说明它未加载，不论目录结构看起来如何。
3. 确认各层级（主目录、根目录、子目录）之间没有矛盾规则；也要检查规则是否与已安装的技能（.claude/skills/、.agents/skills/、~/.claude/skills/）或执行框架默认设置冲突。如果有意重叠，文件必须说明以哪一方为准，让 Agent 知道优先级，而不是每次任务都自行判断。
4. 发现问题：先修订，再重新验证。绝不可因为“看起来没问题”就继续。

步骤 7：应用并报告

应用已批准的编辑，使用相同清单重新评分，并报告修改前后的分数和行数。每个后续 PR 最多新增一条注意事项，且仅限于曾阻止或修复实际错误的情况。

将漂移检查设为门禁

第 6 步只能证明文件当时有效；下一次重命名就会再次破坏它，却无人察觉。如果仓库有检查脚本，就添加一项检查：当指令文件（每个 AGENTS.md、任何审查评分标准、每个项目的 SKILL.md）提及仓库中已不存在的内容时，检查应失败：

1. 每个 <package-manager> run <script> 都要指向根清单中的脚本；如果在工作区中，则要指向 --filter 所指定的内容。
2. 每个相对 Markdown 链接都能解析。
3. 每个反引号括起的路径都指向一个已跟踪或未被忽略的文件或目录，路径基于根目录或指令文件所在目录。
4. 每个反引号括起的 camelCase 或 PascalCase 标识符都出现在源代码中。

标识符检查只能证明它存在，不能证明它可见：即使文档中提到的中间件已设为私有，或已移至另一个 API 之后，检查仍会通过。请在脚本头部说明这一点，避免有人把通过检查理解为更多保证。如果仓库保留了带有设置补丁的评估任务（references/repo-evals.md），同一门禁还要检查每个补丁是否仍能应用于 HEAD。在推送前检查或 CI 检查中运行它，不要只把它当作建议。

易踩的坑

• 项目中的 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 可能会在整个项目范围内阻止默认回退到 AGENTS.md。仅删除根目录的包装文件可能无法解决加载问题。检查内置 mod 和 /config 中的项目指令，然后确认实际加载的文件。
• @import 会移动文本，但不会降低开销，而且只有 Claude Code 能识别。导入的文件会在启动时展开到上下文中（一个 400 行的文件拆成五个导入后，仍会加载 400 行）；Codex 和 Cursor 会把该行视为纯文本；代码行内片段或围栏中的导入永远不会加载；导入链最多四层；而 AGENTS.md 中的外部导入需要 mod 无法发起的批准。每种失败都不会发出提示，因此每个工具都必须遵守的规则应写在文件中。
• 不同工具加载嵌套文件的方式并不相同。Claude Code 在读取子目录中的文件时会加载该目录的文件；Codex 只会拼接从仓库根目录到启动目录路径上的文件。若规则只写在 packages/api/AGENTS.md 中，那么从根目录启动的 Codex 会话，以及从未打开该子树的任何 Claude Code 任务都看不到它。通用规则应放在根目录。
• Codex 拼接的指令文件总量达到 project_doc_max_bytes 后（默认为 32 KiB）便会停止添加，且优先加载根目录文件。臃肿的根目录文件会悄无声息地挤掉其下所有嵌套文件。
• ~/.claude/CLAUDE.md 或 ~/.codex/AGENTS.md 中的项目专用命令会在每个仓库中加载，因此一个项目里的 pnpm dev 会在其他所有地方变成噪声或错误命令。
• 已提交的 AGENTS.override.md 会在 Codex 中替代该目录下的 AGENTS.md，因此意外加入的文件会悄无声息地替换规则集，而大家编辑的 AGENTS.md 看起来却仍然正确。
• 审查 CLAUDE.local.md 时，只需检查其中是否有失效命令，以及是否与共享文件矛盾；它是被 git 忽略的个人配置，只存在于创建它的工作树中。
• 不要在精简内容时删掉强调标记（IMPORTANT、YOU MUST）；这些标记之所以存在，是因为普通措辞曾经被忽略过。当许多行都带有这些标记时，就没有任何一行显眼，因此新增规则被忽略时，应只强调那一行，而不是再次通篇修改文件。
• 内容自动记忆（用户偏好、个人反馈、不断变化的项目状态）会因旧的 # 快捷键习惯而累积到 CLAUDE.md 中。它会在每次会话加载，不属于仓库知识，而且由于代码库中没有任何内容能与之矛盾，便会悄无声息地偏离实际情况。应将其精简到记忆文件或 CLAUDE.local.md 中。
• 快速评分通过并不能证明命令能运行；过时的命令会藏在清单通过的表象之下。第 6 步的冒烟测试不可省略。
• 如果针对性的差异就能通过检查，就不要重写整个文件；整体重写会毁掉经过实践检验的措辞，并加重审查负担。

相关技能

• agent-skills-creator：编写和改进 SKILL.md 文件（格式和规则不同）。
• 已安装时可使用外部 cadence-advise 技能：根据观察到的会话历史提出 AGENTS.md/CLAUDE.md 编辑建议；与本技能以文件为先的审查形成互补。
• ghostwriter：面向人的文档；应将 AGENTS.md 中适合放入文档的内容移至此处。
• codebase-architecture（Harden 模式）：Agent 工作所涉及的仓库其余部分。可由代码检查工具强制执行的规则，应以退出码的形式归入该处，而非作为本文中的说明；该技能负责管理本文所索引的文档树。
• Claude Code 的 /doctor 检查：针对已纳入版本控制的 CLAUDE.md 提出精简建议，删去 Claude 可从代码库推断出的内容，并将始终加载的流程迁移到技能和嵌套文件中。它是互补的自动化分流工具；不会运行命令，因此绝不能替代第 6 步。

仅用于维护：evals/evals.json 包含此技能变更的回归场景；用户执行任务时不会加载该文件。