输出风格（平实的语言，不使用破折号或连字符）
本技能产生的所有内容（文件和信息）均使用简单直白的语言书写。以你称呼读者，像同事一样温暖直接，将每一步都作为建议提出，读者可以执行或跳过，切勿使用命令式语气。保留具有实际含义的技术术语，但应用简单语言解释每个术语。绝不使用破折号或连字符作为标点：不使用长破折号、短破折号或连字符组合词。使用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（根目录和嵌套）中；每个代理（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）会触发阶段 3。没有参数时，下面的“前置检查”信号会引导到阶段 0（有歧义：询问是新的还是现有的）、阶段 1（全新项目：询问标准，生成根文档）、阶段 2（已建立的项目，无根 AGENTS.md：全仓库扫描）或阶段 4（根 AGENTS.md 已存在：补充缺失）。遗留的 CLAUDE.md 如果有内容但无 AGENTS.md，则先迁移再按阶段 4 处理。
操作与询问
阶段 1 在创建根 AGENTS.md 之前通过多项选择题询问编码标准。阶段 2 立即行动，不提问；它编写根文档及其认为必要的嵌套文档。阶段 3 和 4 在探索前会行动，但在修改现有的根 AGENTS.md 或迁移遗留的 CLAUDE.md 之前会请求许可；阶段 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) (<一行描述>)。不要为每个子文件夹都创建，仅在有明显约定的地方创建。
可移植性（任何操作系统，任何代理）
- 命令：
git是唯一必需的 CLI，在所有操作系统上相同。其他 shell 片段（文件计数、find、[ -f ]）是 POSIX 参考，不是实际的脚本；使用你代理的跨平台文件工具（搜索/通配、读取、写入）来列出、计数和检查存在性。 - 捆绑文件位于此技能文件夹中：
agent-prompt.md、阶段模式文件（modes/*.md）和模式预设（patterns/*.md）。将文件夹解析为绝对路径。在路由时读取匹配的阶段模式文件，然后在写入时读取agent-prompt.md和选定的模式预设。其全大写占位符（PHASE、AREA、ADDITIONAL_STANDARDS、MONOREPO_OR_NO、INSTALLED_SKILLS、DECLINED_TOOLS 等）是在前置检查和问题环节中收集到的输入；在读取时应用每个占位符。 - 不支持交互式提问？以包含相同选项的纯文本形式询问任何多项选择题。
执行
主线程在每个阶段执行写入；它绝不将 AGENTS.md 的写入工作交给子代理。唯一的子代理是只读的侦察（使用最便宜的模型，Claude Code：haiku，绝不用会话模型），仅在大型扫描时生成；它返回一个紧凑的映射表，供主线程写入时使用。小型脚手架或单一区域不需要侦察；直接读取。在写入前，读取 agent-prompt.md（角色、各阶段指令、模板），并在阶段 1 读取选定的模式预设；然后按照其指示写入。仅在写入时读取 agent-prompt.md，不要在前置检查期间读取。
前置检查（主线程在做任何事之前先执行此操作）
收集几个信号（仅凭文件计数会产生误导：脚手架会夸大它，不熟悉的语言会使其归零）：
- 上下文文件：根 AGENTS.md 存在 →
ROOT_EXISTS；只有 CLAUDE.md 有内容 →ROOT_LEGACY；两者都无 →ROOT_MISSING。 - 跨常见生态系统的源代码计数（扩展名如
.ts/.tsx/.js/.jsx/.py/.go/.rs/.java/.rb/.swift/.kt/.php/.cs/.dart/.ex/.exs/.scala/.c/.cpp/.h/.lua/.clj），排除 vendored/生成的目录（node_modules、.git、dist、build）和配置文件（*.config.*）。 - 已建立的信号：
git log --oneline获取提交历史深度；真正的清单文件（package.json、pyproject.toml、go.mod、Cargo.toml、composer.json、*.csproj、pubspec.yaml、mix.exs、Gemfile）。 - 单仓库信号：工作区标记（
pnpm-workspace.yaml、turbo.json、package.json中的"workspaces"字段）或根目录附近的任何apps/*/package.json/packages/*/package.json。 - 工作流设置信号 (
WORKFLOW_SETUP)：根 AGENTS.md 缺失，但工作流已经决定了技术栈，即存在docs/specs/架构规范（包含## Proposed stack章节），和/或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=yes)：根目录加每个工作区的轻量存根，按需深化。每个工作区（apps/*、packages/*）是一个一级区域；其主要文档位于工作区根目录（packages/api/AGENTS.md），绝不埋得更深。全仓库运行时不会深入扫描每个工作区；写入仓库根 AGENTS.md（单仓库范围的工具、共享约定）加上从每个工作区清单中生成的轻量存根，无需代码扫描，需包含根指针。完整的约定/陷阱/关键文件扫描在工程师运行 /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 以进行代理技能 / MCP 扫描（区域和补充缺失运行时跳过）。
阶段 0：分类（仅当前置检查有歧义时）
不要猜测。通过代理的交互式选项选择器（Claude Code 上的 AskUserQuestion）或使用相同选项的纯文本询问一次。根据较强的信号（带有清单但历史记录少的类似脚手架树结构倾向于新建；真正的功能代码和深厚历史记录倾向于现有）将其中一个选项标记为 (推荐)，并且选择器在最后添加一个自由文本自定义选项：
- 问题：“我无法判断这是一个新项目还是一个现有代码库（<说明原因：例如‘存在清单文件，但我没有看到我能识别的语言的源代码’，或者‘文件看起来像未触碰的脚手架’>）。是哪一个？”
- 标题：“项目状态”
- 选项：1.
新项目，“我将询问你的编码标准并生成上下文。” → 阶段 1（读取清单/脚手架以获取技术栈；仍需询问标准）。 2.现有代码库，“我将扫描现有内容并记录下来。” → 阶段 2。
在所有阶段之后
如果在应该写入 AGENTS.md 时却没有写入（文件缺失或为空），报告失败并重试；不要报告它未产生的结果为成功。否则报告结果：发现了什么（2 到 4 个要点），写入了什么（文件路径），提议或跳过了什么（如果找到了现有文件）。
模式预设
参见 patterns/，了解阶段 1（全新项目模式）中使用的四种编码风格预设。
编写指南
参见 agent-prompt.md（主线程在写入时读取它；其包含各阶段指令和 AGENTS.md 模板）。