audit-agent-context

审计 Agent 上下文 — 核查 AGENTS.md / CLAUDE.md 是否符合仓库现状

目标

检测并报告 AGENTS.md 和/或 CLAUDE.md 对项目的描述与仓库实际状态之间的差异——绝不自动修正。核查范围包括文件夹结构、命令、技术栈、命名约定、声明的适用范围以及多 Agent 协作规则。该技能会提供分类报告；后续由用户在明确的独立步骤中决定并应用修改。

触发条件

• 用户执行 /audit-agent-context。
• 用户提出类似“检查一下 AGENTS.md 是否仍然准确”“更新 Agent 上下文”“CLAUDE.md 是否已经过时？”等请求。

输入

无必填项。可选提供不同于 cwd 的项目路径（例如，正在审计子项目或工作树时）。

工作流

1. 确定范围。

   • 项目根目录：git rev-parse --show-toplevel（如果失败，则使用 cwd）。
   • 找出所有相关的 AGENTS.md 和 CLAUDE.md：仓库根目录、cwd（如果不同），以及声明为工作目录的子文件夹中嵌套的文件。不要假定每种文件都只有一个——它们可能在多个层级成对出现。

2. 提取可验证的陈述，不改写其内容。重点查找：

   • 提及的路径和文件／文件夹名称（是否存在？是否仍在原处？）。
   • 引用的命令（构建、lint、测试、gentle-ai ...、herdr ... 等）——引用的二进制文件／脚本是否存在或可调用？
   • 否定性陈述（“没有代码”“没有 package.json”“没有测试”）——这些说法现在是否仍然成立？
   • 声明的命名／结构约定（例如 HU-0X-<slug>.md、PLAYBOOK-<ROL>.md）——实际文件是否符合？
   • 声明的适用范围（该 AGENTS.md／CLAUDE.md 覆盖哪些文件夹）与文件在目录树中的实际位置。
   • 多 Agent 协作规则（playbook 路径、技能名称、调用命令）。

3. 根据仓库实际情况核实每项陈述。

   • 使用 Glob／Grep／Read 检查结构和内容；使用 git ls-files／git status 区分已跟踪和未跟踪的文件。
   • 如果仓库包含代码且有可用的 CodeGraph，对于实际架构问题，应优先使用它，而不是进行大范围 grep（这是全局层面现行的结构性问题处理规则）。
   • 对于命令，确认二进制文件／技能是否存在（.claude/skills、.agents/skills、package.json 中的脚本等）——不要仅为“测试”其是否可用而执行可能产生副作用的命令。

4. 为最终报告中的每项陈述分类：

   • ✅ 仍然有效 — 与实际情况一致。
   • ⚠️ 已过时 — 与实际状态矛盾（引用证据：文件中的说法与实际发现）。
   • ❓ 无法自动核实 — 需要人工确认（例如业务决策或未来范围）。
   • 🆕 未记录 — 仓库中存在某项内容（文件夹、约定、技能、playbook），但任何 AGENTS.md／CLAUDE.md 都未提及。

5. 提交报告，按审计文件分组（如果有多个文件）。每项都应包含：引用的原文陈述、找到的证据和分类。最后列出建议的修改，以具体提案的形式撰写（不直接应用），供用户决定是否纳入文件。

不可妥协的规则

• 绝不编辑此 skill 中的 AGENTS.md/CLAUDE.md。 应用修正是后续的显式步骤，不属于本次审计范围。
• 绝不假设未经确认的意图。 如果某项陈述含糊不清，或取决于业务/团队决策，应标记为 ❓，而不是凭猜测解决。
• 如果被审计的项目有自己的领域规则（例如本测试项目中的“待解决问题”或“范围 — 不包括”），此 skill 也必须遵守这些规则：不得臆造范围，也不得悄悄解决冲突。
• 如果在已确定的范围内找不到任何 AGENTS.md 或 CLAUDE.md，应明确报告——不得默默略过。

注意事项

• 此 skill 对仓库仅具有只读权限：不会写入文件，也不会提交更改。
• 步骤 2–4 是通用的，并非针对 test-project 的结构硬编码：可用于审计调用它的任何仓库中的 Agent 上下文。