agent-config

适用场景

创建、更新或审查编码 Agent 每次会话都会加载的指令文件。AGENTS.md 是默认输出：它是 Claude Code（v2.1.277+）、Codex、Cursor、Copilot 等工具都会读取的开放标准。只有在用户明确要求时，才将 CLAUDE.md 作为输出，也就是说，用户要求编写或编辑 CLAUDE.md（“创建一个 CLAUDE.md”“向 CLAUDE.md 添加 X”）。将其称为来源不算（“将我们的 CLAUDE.md 迁移到 AGENTS.md”），磁盘上已存在 CLAUDE.md 也不算。跳过 README 和贡献者文档、技能（skill-creator），以及 .claude/agents/ 下的子 Agent 文件。

核心原则

这些文件是上下文，而非强制配置。它们会在每次会话中加载，但 Agent 仍可能偏离其中的指令。

• 将 Agent 无法推断的简短、始终适用的信息写入文件。
• 多步骤流程应写入技能。绝不能发生的情况应通过 PreToolUse 钩子和权限来约束。工作验证应通过测试或 CI完成。
• 精简胜过面面俱到。 Agent 会运行文件中列出的每条命令，并遵守每条规则，因此每增加一行，都会让每项任务多花费步骤和 Token。实测表明，重复描述仓库内容的 LLM 生成文件会多消耗约 20% 的成本，却没有提升成功率。本技能本身就是一个用于编写此类文件的 LLM，因此对于新内容，步骤 3 中的删减环节是必做项。

由哪一层负责某条指令：references/knowledge-routing.md。加载规则和来源：references/official-standards.md。

前置条件

• 对于任何会写入内容的操作，需要一个已设置 origin 的 Git 仓库。audit 只需要读取权限。
• 工具：git，以及对目标路径的写入权限。

模式选择器

$ARGUMENTS

• audit：用户说 audit、“审查”或“检查”。只读。
• write：其他情况（create、update、指定变更，或指定路径，如 packages/api/AGENTS.md）。

所有模式都会先执行步骤 1。步骤 1 完成后，如果用户指定了对现有文件的具体变更，write 操作就是定向编辑；否则就是完整审查。write 操作继续执行步骤 2–4；audit 则跳转到审查。

编辑前同步仓库（必做）

write 操作进行任何更改前，都必须与远程同步。audit 跳过此步骤。git fetch 是只读的试运行。

branch="$(git rev-parse --abbrev-ref HEAD)"
git fetch origin                       # dry-run: read-only preview
git status                             # validate clean tree
git pull --rebase origin "$branch"     # only once the tree is clean

如果工作树有未提交的更改，先用 git stash push -u -m "pre-sync-backup" 备份，再进行同步，然后运行 git stash pop。如果发生以下任一情况，请停止并询问用户是否确认跳过同步：当前目录不是 Git 仓库、缺少 origin、HEAD 处于分离状态、分支没有上游、拉取或变基失败，或恢复暂存失败。如果用户未授权跳过同步，则不写入任何内容，并以 BLOCKED 作为最终报告。覆盖现有 Agent 文件前，必须先读取文件并展示差异。

步骤 1：确定目标文件（所有模式）

1. 输出文件是仓库根目录中的 AGENTS.md，或用户指定的路径。只有在用户明确要求时才使用 CLAUDE.md（参见“何时使用”）。

2. 检查遮蔽情况。 默认情况下，只有当启动目录或其任一上级目录中不存在 CLAUDE.md、.claude/CLAUDE.md 或 CLAUDE.local.md 时，Claude Code 才会读取 AGENTS.md；~/.claude/CLAUDE.md 不计入。只有当某个子目录中不存在自身的 CLAUDE 文件时，该目录中的 AGENTS.md 才会加载。任何符合条件的文件都会遮蔽 AGENTS.md。从仓库根目录开始，列出根目录上级目录中的 CLAUDE 文件，以及仓库内的 CLAUDE 文件：

   root="$(git rev-parse --show-toplevel 2>/dev/null || pwd)"; d="$(dirname "$root")"
   while :; do for f in CLAUDE.md .claude/CLAUDE.md CLAUDE.local.md; do p="$d/$f"
     { [ -e "$p" ] || [ -L "$p" ]; } && [ "$p" != "$HOME/.claude/CLAUDE.md" ] && echo "ABOVE-REPO $(ls -l "$p")"
   done; [ "$d" = / ] && break; d="$(dirname "$d")"; done
   find "$root" \( -name node_modules -o -name .git \) -prune -o \( -name CLAUDE.md -o -name CLAUDE.local.md -o -name AGENTS.md \) -print |
     while read -r p; do ls -l "$p"; grep -qE '^@(\.\.?/)*AGENTS\.md' "$p" 2>/dev/null && echo "  -> imports AGENTS.md" || true; done
   

3. 对找到的每个 CLAUDE 文件进行分类。每个文件都要单独处理：

文件	操作
仓库根目录上级目录中的文件（例如 ~/CLAUDE.md）	绝不编辑。 提醒用户它会阻止其下所有仓库中的 AGENTS.md 生效，并建议将其内容移至 ~/.claude/CLAUDE.md，该文件不计入
CLAUDE.local.md	绝不编辑。 提醒用户它会导致 Claude 不读取其所属目录的 AGENTS.md。建议将 @AGENTS.md 作为首行，或使用 /config → 项目指令 → claude-md-and-agents-md。该设置仅对当前用户生效，且会被项目设置忽略
指向 AGENTS.md 的符号链接	无需处理。写入链接目标文件，因为 Edit 和 Write 不允许通过符号链接写入
已导入 AGENTS.md	保留该文件，只保留其中仅适用于 Claude 的行
仓库内未导入 AGENTS.md 的文件	迁移：将共享规则移至 AGENTS.md，并精简该文件，仅保留导入语句及仅适用于 Claude 的行。导入路径相对于文件所在目录，因此 .claude/CLAUDE.md 使用 @../AGENTS.md

4. 选择分支：
   • wrapper：用户要求创建两个文件。
   • claude-only：用户明确要求创建 CLAUDE.md，且不存在 AGENTS.md。
   • wrapper：用户明确要求创建 CLAUDE.md，且 AGENTS.md 已存在。将 CLAUDE.md 写为导入语句加上仅适用于 Claude 的行；只有在用户要求时才修改 AGENTS.md。
   • migrate：仓库内有任何 CLAUDE 文件需要迁移。
   • agents-only：其他所有情况。

仅适用于 Claude 的行：涉及 Claude Code 功能的内容，例如 plan mode、/commands、skills、hooks、subagents 或 MCP 工具。若 CLAUDE 文件已存在或用户要求创建，则将这些内容保留在该文件中。否则，将其放入 .claude/rules/<topic>.md，该文件会与 AGENTS.md 一起加载，且不会遮蔽它。绝不要仅为保存这些内容而创建 CLAUDE.md。

用户反馈 AGENTS.md 未加载且遮蔽检查无异常时：在重写任何内容之前，检查环境：claude --version（v2.1.277+）、/config 中的项目指令值，以及 agents-md 插件是否已启用（official-standards.md → Claude Code）。

完成标准：展示输出路径、所选分支、每个 CLAUDE 文件的处理方式，以及遮蔽检查的原始输出。

步骤 2：分析项目（全面检查）

仅收集 Agent 否则可能判断错误的信息：

• 命令：从清单文件和 CI 配置（package.json 脚本、pyproject.toml、Makefile、.github/workflows/*）中收集安装、开发、测试全部内容和单项内容、lint 及类型检查命令，并注明 CI 使用的标志。
• 固定版本：包管理器和运行时版本；在错误猜测会导致失败的地方注明（pnpm，而非 npm）。
• 边界：生成内容、供应内容和机密文件路径，以及需要先由人工确认的操作。
• 现有规则：Agent 文件、.cursor/rules/、.cursorrules 和 .github/copilot-instructions.md 中的规则。保留仍然适用的内容，并让这些文件保持原位。

完成标准：你要写入的每条命令都必须来自文件。如果没有清单文件或 CI 配置定义某条命令，就不要写入，并询问用户；绝不要猜测。

第 3 步：起草

对于定向编辑，执行所请求的更改；如果缺少令牌效率区块，则添加该区块，除此之外不做任何更改。对于常规工作流、编码规范或单元测试规则的请求，使用 references/optional-blocks.md 中对应的区块即可满足要求。在报告中列出其他可删减的内容，但不要应用这些删减。对于完整检查，先阅读 references/agents-md-writing.md。其中包含模板、写作规则及其依据。然后：

1. **填写模板。**Commands、Constraints（Never 和 Ask first）以及 Done when 为必填项。只有在 Project、Layout、Conventions 和 Read when needed 中包含 Agent 无法推断的事实时，才添加这些部分。
2. 删减检查。 删除所有未通过删除测试的行：“删掉这行会导致某个具体错误吗？” 同时删除所有概述、目录树、依赖项列表或对 README 的复述。保留文件中已有的可选区块。将仅适用于 Claude 的行移至步骤 1 指定的位置。
3. 仅在用户提出要求时，才添加 references/optional-blocks.md 中的可选区块（工作流编排、编码规范、单元测试）。
4. 最后追加令牌效率区块（见下文）。

完成标准：所有剩余行都是命令、固定约束、限制条件或指引。

第 4 步：编写并验证

• 先展示，再写入。 对于新文件，展示草稿；对于现有文件，展示差异。用户批准后再写入；如果用户已明确要求应用更改，则立即写入。如果用户拒绝，则不写入任何内容，并以最终报告 BLOCKED 结束。
• 验证。 如果检查失败，修复文件并重新运行该检查一次。如果仍然失败，则以 Result: FAIL 结束步骤 4，并指出未通过的检查：
  • 每个文件的 wc -l 结果均小于 200。
  • grep -c '^## Token Efficiency' 在权威文件中返回 1，在其他所有文件中返回 0。
  • 每个包装文件的首行都是 AGENTS.md 导入语句。
  • 重新运行 shadow 检查后，没有发现仓库内有 CLAUDE 文件遮蔽 AGENTS.md。
• 报告如何确认已加载。 在 Claude Code v2.1.280+ 中，/memory 会列出 AGENTS.md。在 Codex 中，运行 codex --ask-for-approval never "Summarize the current instructions."。无法读取 AGENTS.md 的客户端需要一个只包含 @AGENTS.md 的单行 CLAUDE.md：Claude Code v2.1.277 之前的版本，以及 v2.1.281 之前的部分 Bedrock 或关闭遥测的会话。可以提出创建该文件，但不要在未获要求时创建。

审计（只读）

1. 一并阅读以下内容，因为只有跨文件检查才能发现遮蔽和偏差：
   • AGENTS.md
   • shadow 检查发现的每个文件
   • 任何 AGENTS.override.md
   • .claude/settings.json 和 .claude/settings.local.json，检查其中的钩子
2. 逐项检查 references/agents-md-checklist.md，并为每项报告 pass、fail 或 N/A，同时附上一行理由。其加载部分会检查未导入 AGENTS.md 的 CLAUDE 文件遮蔽、要求 Claude“读取 AGENTS.md”的文字、输出 AGENTS.md 的 SessionStart 钩子，以及 Codex 实际读取的 AGENTS.override.md。
3. 交叉检查 references/anti-patterns.md。
4. 确定归属并强制执行。 对每条未通过的规则，依据 references/knowledge-routing.md 指明应放置的位置。机器可以检查的规则必须设置检查门槛，并删除相应说明文字。
5. 不做任何修改；git status 必须保持不变。在审计报告的 Result: 行给出总体结论（PASS、PARTIAL 或 FAIL）。建议使用 /memory 查看已加载的内容，并使用 /doctor prompt-audit（v2.1.283+）进行第二轮检查。

Token 效率区块（始终注入）

从 references/token-efficiency-block.md 追加围栏代码块，并将其作为事实来源文件的最后一个部分。事实来源是根目录中的 AGENTS.md，或者仅限 claude 的分支中的 CLAUDE.md。切勿将该区块添加到包装文件、嵌套的包文件或 .claude/rules/ 文件中：这些文件会与根文件一同加载，添加第二份会导致内容重复。它是唯一一种无需请求便添加的通用建议：这些是 Agent 如何使用其上下文窗口的常驻规则。不可妥协：每次写入运行中，只要事实来源缺少该区块，就必须添加，包括定向编辑，并在报告中说明。唯一例外是包装分支：不要仅为添加该区块而编辑已存在的 AGENTS.md；应报告该区块缺失。

步骤完成报告

每个步骤结束后，输出：

◆ [Step Name] ([step N of M])
··································································
  [Check 1]:          √ pass
  [Check 2]:          × fail — [reason]
  [Criteria]:         √ N/M met
  ____________________________
  Result:             PASS | FAIL | PARTIAL

通过使用 √，失败使用 ×。根据每个步骤调整检查名称。

最终报告

每次运行结束时（包括提前停止的情况），都以 references/final-report.md 中的最终报告收尾：先写 Result:（COMPLETE、PARTIAL 或 BLOCKED），然后依次写 Evidence:、Uncertainty: 和 Decision:。该参考文件定义了各状态，并包含读者检查项。

验收标准

• 显示分支、每个 CLAUDE 文件的处理操作以及 shadow-check 输出。
• 未明确要求 CLAUDE.md 时，不得新建 CLAUDE.md。
• 运行后，仓库中的每个 CLAUDE 文件都必须导入 AGENTS.md，或是指向它的符号链接。仓库上级目录中的文件和 CLAUDE.local.md 均不得编辑，并须向用户提示这些文件。
• 已同步仓库，或用户明确授权跳过同步。
• Token 效率区块在事实来源中恰好出现一次，除非包装分支报告该区块缺失。
• 事实来源文件少于 200 行，并通过 references/agents-md-checklist.md 的第 1–3 和第 5–7 节检查。包装文件和规则文件通过第 1–3 和第 6 节检查。
• AGENTS.md 和 CLAUDE 文件中不得出现重复规则。
• 新内容不得包含 references/anti-patterns.md 中列出的反模式。
• 写入文件的写入运行必须以 Result: PASS 结束步骤 4。审计运行须报告所有检查项，为每个失败的行提供处理建议，保持 git status 不变，并给出总体结论。
• 每次运行都必须以最终报告结束，并通过 references/final-report.md 中的读者检查。若未收到用户反馈，则人类对报告的理解情况仍未得到确认。

预期输出

分支	运行后的文件
agents-only	AGENTS.md：命令、约束、完成条件、任何可选部分，然后是 ## Token Efficiency
migrate / wrapper	如上所述的 AGENTS.md，以及每个精简为 @AGENTS.md 导入语句和仅适用于 Claude 的行的 CLAUDE 文件
claude-only	包含完整内容和 token 区块的 CLAUDE.md
audit	不写入文件；提供包含处理建议和 Result: PASS、PARTIAL 或 FAIL 结论的检查清单报告

每个分支最后都要输出最终报告。示例文件见 references/agents-md-writing.md，示例审计报告见 references/agents-md-checklist.md，示例最终报告见 references/final-report.md。

边缘情况

• 单体仓库：优先为每个包分别设置一个 AGENTS.md，而不是不断扩充根目录文件。Codex 和大多数 Agent 会优先采用距离最近的文件。Claude 会按需读取根目录文件和各子目录中的文件，而 CLAUDE 文件会覆盖其所在目录中的 AGENTS.md。询问要编辑哪个范围。
• 用文字要求 Claude 读取 AGENTS.md，或包含其粘贴副本的 CLAUDE 文件（来自 /init 或 /import）：它缺少导入，因此请迁移。
• 要求创建 AGENTS.override.md 或 AGENTS.local.md：Codex 会读取 AGENTS.override.md，而不是该目录中的 AGENTS.md；Claude 则两个文件都不会读取。创建之前请说明这一点。
• 个人文件（~/.claude/CLAUDE.md、~/.codex/AGENTS.md）：仅进行审查并提出建议。绝不要在仓库范围的运行中重写个人文件。
• 多步骤流程：不要内联。建议使用技能，并留下一行指向它的说明。
• 超过 200 行的草稿：在写入之前，按路径限定规则范围、将流程提取为技能，或提供外部链接。