audit

输出风格（使用简单词语，不用破折号或连字符）

此技能生成的所有内容，无论是文件还是消息，都请使用简单直白的语言。请用 you 称呼读者，语气温和直接，就像与同事交谈一样。请把每个步骤都写成建议，让读者可以选择执行或跳过，切勿写成命令。保留确有意义的技术术语，并用简单的话解释每个术语。切勿用破折号或连字符作标点：不要使用长破折号、短破折号，也不要使用带连字符的复合词。请写 read only，不要写 read-only。请用简单的话表达，或改写句子。其他技能会匹配的代码、文件路径、命令行标志和值，请保留其中的连字符。请使用短句、逗号或括号。清晰胜过巧妙。

此技能的作用

上下文引导工具：编写所有后续技能和 AI 工具都会读取的 AGENTS.md 文件。

• 全新项目（尚无代码）：询问编码规范，根据回答以及范围标题中的构建方案（名称和一句原则，如果 /scope 设置了这些内容）创建根目录 AGENTS.md。需在项目使用选定技术栈完成脚手架搭建后运行（/scope → /architect 决定技术栈 → 搭建脚手架 → /audit）；更早运行还为时过早。
• 存量项目，没有文档（有代码，没有 AGENTS.md）：扫描整个项目，编写根目录 AGENTS.md 和嵌套的 <area>/AGENTS.md 文件，判断哪些内容适用于全局（根目录），哪些内容仅适用于特定区域（嵌套文件）。
• 存量项目，文档不完整：根据整个代码库检查现有根目录和嵌套文档；只补充缺失内容（新的全局事实，以及为尚无文档的区域创建的嵌套文档）；绝不覆盖经过整理的内容。

不创建规范（由 /architect 负责），不在变更后维护文件（由 /sync 负责），也不编写功能范围（由 /scope 负责 docs/scope/）。

上下文文件约定（AGENTS.md 为规范文件）

持久上下文保存在与工具无关的 AGENTS.md 文件中（根目录和嵌套目录均可）；每个 Agent（Codex、Cursor、Claude Code 等）都会读取它。CLAUDE.md 只是一个单行指针，其正文仅通过 Claude Code 的 @ 导入同级的 AGENTS.md（指针正文见 agent-prompt.md）；绝不在这两个文件中重复内容。

• 将知识写入 AGENTS.md。如果文件不存在，就创建它。绝不覆盖现有的 AGENTS.md（它可能由用户或工具编写）；征得许可后谨慎补齐缺失内容。
• 迁移旧版内容：如果 CLAUDE.md 有内容，但不存在 AGENTS.md → 征求许可，将其内容移入新建的 AGENTS.md，并将 CLAUDE.md 替换为指针。绝不悄悄丢弃经过整理的内容。
• 根目录文件应简短且适用于全局；仅在具有实际约定的重要区域创建嵌套的 AGENTS.md（沿用之前适用于 CLAUDE.md 的相同根目录和嵌套规则）。

范围

提供区域路径参数（例如 auth、src/payments）时，会进入 Phase 3。不提供参数时，以下 Pre-flight 信号会将流程导向 Phase 0（情况不明确：询问是新项目还是现有项目）、Phase 1（全新项目：询问规范并创建根目录文件）、Phase 2（已建立的项目，且没有根目录 AGENTS.md：扫描整个代码库），或 Phase 4（根目录存在 AGENTS.md：补齐缺失内容）。如果 CLAUDE.md 有内容，但不存在 AGENTS.md，则先迁移，再按 Phase 4 处理。

执行与征求许可

Phase 1 会通过选择题询问编码规范，然后创建根目录 AGENTS.md。Phase 2 会立即执行，不提问；它会编写根目录文档，以及判断有必要创建的嵌套文档。Phase 3 和 Phase 4 会先执行探索，但在修改现有根目录 AGENTS.md 或迁移旧版 CLAUDE.md 前，会先征求许可；Phase 4 会先报告为尚无文档的区域创建嵌套文档的计划，再在确认后执行。

文件归属

AGENTS.md 文件存放内容：如果根目录中没有该文件，则创建它（阶段 1、2）；如果有必要，则根据判断创建 <area>/AGENTS.md（阶段 2、3、4）。如果文件已存在，则在获得许可后补充缺失内容或提议添加内容；绝不覆盖。CLAUDE.md 文件仅作为指针（根目录和区域），如果缺失则创建。获得许可后，将包含内容的旧版文件迁移到 AGENTS.md。创建嵌套的 AGENTS.md 时，在根目录的 AGENTS.md 的 ## Context files 下恰好添加一行指针：- [<area>/AGENTS.md](<area>/AGENTS.md) (<one-line description>)。绝不为每个子文件夹都添加指针，只在存在不同约定的地方添加。

可移植性（任意操作系统、任意 Agent）

• 命令：git 是唯一必需的命令行工具，在所有操作系统上都相同。其他 shell 片段（文件计数、find、[ -f ]）是 POSIX 参考写法，并非可直接执行的脚本；请使用 Agent 提供的跨平台文件工具（搜索/匹配、读取、写入）来列出、计数和检查文件是否存在。
• 随附文件位于此技能的文件夹中：agent-prompt.md、各阶段模式文件（modes/*.md）以及模式预设（patterns/*.md）。将该文件夹解析为绝对路径。进行路由时读取匹配的阶段模式文件，然后在写入时读取 agent-prompt.md 和选中的模式预设。其全大写占位符（PHASE、AREA、ADDITIONAL_STANDARDS、MONOREPO_OR_NO、INSTALLED_SKILLS、DECLINED_TOOLS 等）是你在预检和提问环节中收集的输入；阅读时逐一应用。
• 不支持交互式提问？请以纯文本形式询问任何多选题，并提供相同的选项。

执行

每个阶段都由主线程负责撰写；绝不将 AGENTS.md 的撰写工作交给子 Agent。唯一的子 Agent 是只读的 scout（使用最便宜的模型；Claude Code 中使用 haiku，绝不使用会话模型），仅在大范围扫描时启动；它会返回一份精简概览，供主线程据此撰写。小型脚手架或单个区域无需启动 scout，直接读取即可。写入前，先读取 agent-prompt.md（角色设定、各阶段说明、模板），并在阶段 1 中读取选定的模式预设；然后按照其中的要求撰写。只在写入时读取 agent-prompt.md，不要在 pre-flight 期间读取。

Pre-flight（主线程在执行任何其他操作前完成）

收集多项信号（仅统计文件数会产生误导：脚手架会使数量偏高，不熟悉的语言会使数量为零）：

1. 上下文文件：根目录存在 AGENTS.md → ROOT_EXISTS；仅存在包含内容的 CLAUDE.md → ROOT_LEGACY；两者都不存在 → ROOT_MISSING。
2. 常见生态系统中的源文件数量（扩展名包括 .ts/.tsx/.js/.jsx/.py/.go/.rs/.java/.rb/.swift/.kt/.php/.cs/.dart/.ex/.exs/.scala/.c/.cpp/.h/.lua/.clj），排除 vendored/generated 目录（node_modules、.git、dist、build）和配置文件（*.config.*）。
3. 已有项目的信号：使用 git log --oneline 检查提交历史深度；检查真实清单文件（package.json、pyproject.toml、go.mod、Cargo.toml、composer.json、*.csproj、pubspec.yaml、mix.exs、Gemfile）。
4. Monorepo 信号：工作区标记（pnpm-workspace.yaml、turbo.json、package.json 中的 "workspaces" 字段），或根目录附近存在任何 apps/*/package.json / packages/*/package.json。
5. 工作流设置信号（WORKFLOW_SETUP）：根目录缺少 AGENTS.md，而工作流已经确定了技术栈，即存在包含 ## Proposed stack 小节的 docs/specs/ 架构规范，和/或 docs/scope/ 中有“Stack and architecture”（或类似的基础脚手架）功能。这是预期的绿地开发顺序（/scope → /architect 确定技术栈 → /develop 搭建脚手架 → /audit）：项目刚搭建好脚手架，仍需记录编码规范。触发此信号时，现有清单和源代码脚手架属于脚手架内容，而非已有代码库。

确定阶段。检查顺序很重要：工作流设置信号优先于原始代码数量，因为新搭建的脚手架虽然已有清单和源文件，但仍属于绿地开发。

条件	阶段
将区域路径作为参数提供	阶段 3
ROOT_EXISTS（迁移后为 ROOT_LEGACY）	阶段 4
ROOT_MISSING 且存在 WORKFLOW_SETUP（技术栈规范和/或范围技术栈功能）	阶段 1，即使现在已有清单和脚手架源文件。询问编码规范；根据规范中的技术栈初始化根目录。绝不要把刚搭建好的工作流项目当作棕地项目。
ROOT_MISSING，不存在 WORKFLOW_SETUP、源文件和清单	阶段 1
ROOT_MISSING，不存在 WORKFLOW_SETUP，有代码（源文件 ≥ 10 或存在清单）、提交数 ≥ 2，且显然是真正的功能代码（不只是脚手架）	阶段 2，任何语言均可
ROOT_MISSING，不存在 WORKFLOW_SETUP，有代码但看起来仍是未修改的脚手架，或提交数 ≤ 1，或无法判断是绿地还是棕地	阶段 0，询问

为什么要按这个顺序判断：刚搭建好的脚手架有清单和起始文件，但仍属于绿地项目；仅按代码数量判断会误判为棕地项目，从而跳过规范相关问题。工作流设置信号可以捕捉这种情况，并将其归入绿地项目。真正的棕地项目（阶段 2）意味着有实际功能代码、真实提交历史，且没有正在进行的工作流设置。任何模糊情况都归入阶段 0；绝不要默认将可能是绿地项目的项目当作棕地项目。

Monorepo（MONOREPO=yes）：在根目录以及每个工作区放置一个轻量级存根，按需深入检查。每个工作区（apps/*、packages/*）都是一级区域；其主要文档放在工作区根目录（packages/api/AGENTS.md），绝不要埋在更深的目录中。对整个仓库运行时，不要深入扫描每个工作区；编写仓库根目录的 AGENTS.md（涵盖 Monorepo 范围的工具配置和共享约定），再根据每个工作区的清单创建轻量级存根，不扫描代码，并添加根目录指引。只有在工程师运行 /audit packages/api（阶段 3）或首次在该处构建时，才扫描完整的约定、易错点和关键文件。如果工作区内某个位置需要有自己的文档（packages/ui/src/mdx/），则在工作区根目录的文档之外再添加一份，并从根目录文档链接到它。如果工作区内已有一份文档，但它被放在较深的位置且工作区根目录没有文档，请询问：“packages/ui 在 src/mdx/ 中有一个上下文文件，但根目录没有。要将它移至 packages/ui/AGENTS.md，还是将它保留为新建的 packages/ui/AGENTS.md 下的嵌套文档？”选择移动时：将其移至工作区根目录。选择保留嵌套文档时：创建工作区根目录的 AGENTS.md，并保留深层文档，在根目录文档中链接到它。按照上文约定迁移旧版 CLAUDE.md 内容。编写时应用 MONOREPO=yes 以及工作区列表。

旧版迁移（任何阶段）：遇到 ROOT_LEGACY 时，继续之前先征求许可：“我发现有一个包含项目上下文的 CLAUDE.md，但没有 AGENTS.md。我会将其内容移入新的 AGENTS.md（以便所有工具都能读取），并将 CLAUDE.md 替换为指向它的文件。要继续吗？”用户同意后：将内容原样复制到 AGENTS.md，然后将 CLAUDE.md 替换为指引文件；此时 AGENTS.md 已存在，因此继续按阶段 4（补齐缺漏）处理。用户不同意时：两者都保持不变，不迁移并继续处理。任何嵌套的 <area>/CLAUDE.md 也适用相同规则。

转到选定阶段

阶段 0（模糊情况）在下方内联处理。阶段 1 至 4 只读取对应的模式文件，然后按其中说明操作：

• 阶段 1（绿地项目设置）→ modes/greenfield.md
• 阶段 2（全仓库扫描）→ modes/whole-repo.md
• 阶段 3（区域扫描）→ modes/area.md
• 阶段 4（补齐缺漏）→ modes/gapfill.md

不要读取其他模式文件。绿地项目和全仓库模式还会读取 modes/tool-skills.md，用于检查 Agent Skills / MCP（区域扫描和补齐缺漏时跳过）。

Phase 0：分类（仅当 pre-flight 存在歧义时）

不要猜测。通过 Agent 的交互式选项选择器（Claude Code 中的 AskUserQuestion）询问一次，也可以用纯文本列出相同选项。根据更有力的信号，将一个选项标记为 (recommended)（例如，包含清单但几乎没有历史记录的脚手架，如 tree，更倾向于新项目；实际功能代码和丰富的历史记录更倾向于现有项目）；选择器会在最后添加一个自定义文本输入项：

• question: “我无法判断这是新项目还是现有代码库（<说明原因，例如：‘存在清单，但我看不到任何我认识的语言的源代码’，或‘文件看起来还是未修改的脚手架’）。这是哪一种？”
• header: “项目状态”
• options: 1. New project，“我会询问你的编码规范并初始化上下文。” → Phase 1（读取清单／脚手架以确定技术栈；仍需询问编码规范）。2. Existing codebase，“我会扫描现有内容并记录下来。” → Phase 2。

所有阶段完成后

如果本应写入 AGENTS.md，但实际未写入（文件缺失或为空），请报告失败并重新执行；不要报告未实现的成功。否则，请汇报：发现的内容（2 到 4 条要点）、写入的内容（文件路径），以及提出或跳过的内容（如果发现了现有文件）。

模式预设

参见 patterns/，了解 Phase 1（绿地模式）使用的四种编码风格预设。

编写指南

参见 agent-prompt.md（主线程会在写入时读取；其中包含各阶段说明和 AGENTS.md 模板）。