init-agent-config

初始化 Agent 配置

以 AGENTS 为先的指令层级，基于真实的仓库证据构建。AGENTS.md 是 Agent 工作方式的事实来源。CLAUDE.md 是它的配套文件。REVIEW.md 是可选的评审标准化层。本机评审适配器（Copilot、Devin、Greptile）是可配置的最后阶段输出。

默认兼容 Claude：每个最终确定的 AGENTS.md 都会有一个同级 CLAUDE.md 符号链接。如果目标环境不支持符号链接，则改用单行 @AGENTS.md 包装文件，并在回复中说明这一例外。

适用场景

• “为此仓库设置 CLAUDE.md / AGENTS.md”
• “初始化 Agent 指令” / “引导配置 Agent”
• “编写 REVIEW.md” / “添加评审标准化”
• “将 .cursorrules / Copilot / Gemini 配置迁移到 AGENTS.md”
• “审核现有的 Agent 指令”
• “在 src/ / apps/ / packages/ 下添加文件夹级 AGENTS.md”
• “生成 Copilot / Devin / Greptile 评审适配器”（AGENTS 和 REVIEW 完成后）
• “整理 CLAUDE.md，让 Codex 和 Cursor 也能读取”

不适用场景

• 创建或修改 技能 本身 → 使用 build-skill
• 检查计划中的工作是否已实际完成 → 使用 audit-completion
• 评审特定 PR → 使用 run-review Mode A
• 与指令文件无关的运行时多 Agent 编排 → 使用多 Agent 运行时编排器

文件职责

明确区分，每个文件只负责一件事。

层面	用途	默认状态
AGENTS.md	Agent 应如何工作、代码位于何处、本地边界有哪些	必需
CLAUDE.md	每个最终确定的 AGENTS.md 的兼容性配套文件	必需的符号链接或 @AGENTS.md 包装文件
REVIEW.md	哪些差异应被标记、保护或按照更高标准审查	默认在范围内或有证据支持时生成
文件夹 AGENTS.md	仅记录本地差异，绝不重复根目录内容	根据 Wave 2 证据决定
.github/copilot-instructions.md	Copilot 评审适配器	可配置的最后一步
Devin 评审文件	Devin Bug Catcher 适配器	可配置的最后一步
.greptile/config.json	Greptile 评审适配器	可配置的最后一步

快速区分：

• AGENTS.md = 如何工作
• REVIEW.md = 更改中需要重点审查什么
• 本机适配器 = 对评审上下文进行平台专属转换

不可妥协的要求

每次运行都要阅读以下内容。这些是必须遵守的硬性规范。

1. 起草任何内容前先检查仓库。 不要先套用模板。
2. 优先编写 AGENTS.md。 配套文件（CLAUDE.md、GEMINI.md、.cursor/rules/*）应在 AGENTS 层级建立后再处理。
3. 每个最终确定的 AGENTS.md 都要有同级 CLAUDE.md。 默认使用符号链接；仅在不支持符号链接时使用 @AGENTS.md 包装文件（并说明原因）。
4. 在完成 AGENTS 和 CLAUDE 后再决定是否需要 REVIEW.md。 运行评审标准化任务时默认生成；如果发现过程揭示了仓库特有的风险，也应生成；否则记录跳过的原因。
5. 本机评审适配器必须是最后一步。 AGENTS、CLAUDE 和 REVIEW 全部完成前，不要询问 Copilot / Devin / Greptile。
6. 按波次发现。 Wave 1（广泛了解架构）→ Wave 2（深入检查文件夹）→ 编写。不要因为 Wave 1 已发现技术栈就跳过 Wave 2。
7. 文件夹规则。 将每个有意义的一级 src/*、apps/*、packages/*、services/* 文件夹视为本地 AGENTS.md 候选项。只有 Wave 2 证明本地差异为空时才跳过。
8. 根据实际文件验证命令和路径。 绝不臆造。无法确认时标记 [unverified]。
9. 补充现有配置，不要盲目替换。 除非仓库证据表明规则已过时，否则保留 Always、Ask、Never、WARNING、CRITICAL、DO NOT 规则。
10. 优先采用高信号指令，而非铺陈说明。 如果某一行无法避免错误，就删掉它。
11. 存在现有文件时，先生成审核报告再进行编辑，除非用户明确表示可以跳过。

防跑偏护栏

跑偏情况	修正措施
尚未完成探索就根据模板编写	执行 Wave 1 + Wave 2；只有在文件计划确定后才加载模板
Wave 1 找到技术栈后跳过 Wave 2	在编写文件夹文件之前，必须执行 Wave 2
编写者依据不完整的发现开始编写	分派编写者之前，合并两轮发现
子级 AGENTS.md 重复根目录规则	保持子级文件精简——仅记录本地差异
REVIEW.md 变成 AGENTS.md 的另一份副本	操作指南与差异审查关注点不同——应分别处理
CLAUDE.md 膨胀成第二个事实来源	建立指向 AGENTS.md 的符号链接；仅 Claude 专属行为放在 .claude/ 中
通用内容被困在 CLAUDE.md 或 GEMINI.md 中	将其提升到 AGENTS.md
将原生适配器生成为默认交付物	适配器仅作为可配置的最后步骤输出
将共享默认配置写入 AGENTS.override.md 或 CLAUDE.local.md	这些属于覆盖/个人配置层——不能用于共享默认配置
现有配置基本正确，你却仍然重写了它	切换到审计/精简模式

脚本

相对于此技能目录解析脚本路径。

脚本	使用时机	是否会修改内容
scripts/audit-agents-md.sh	第 1 步：审计现有指令载体、行数、配套文件状态、原生适配器和重复来源风险。参见 scripts/audit-agents-md.sh.md。	否
scripts/scaffold-agents-md.sh	完成探索和文件规划后，生成一个精简的根目录/文件夹 AGENTS.md 或 REVIEW.md 骨架。参见 scripts/scaffold-agents-md.sh.md。	仅在显式指定 --write 时

工作流

1. 确定请求范围

深入阅读之前先对请求进行分类。

请求类型	输出约定
新建配置	根目录 + 基于证据的文件夹 AGENTS.md 层级、同级 CLAUDE.md 配套文件、审查上下文决策/输出，然后询问是否需要适配器
审计	先提供质量报告，再针对不稳定文件、配套文件状态和审查上下文缺口进行定向编辑
迁移	将共享规则提取到 AGENTS.md，移出 Agent 原生行为，保留关键警告，修复配套文件，并决定审查上下文
扩展	添加缺失的文件夹文件或入口点，不重写稳定的根目录文件；仅在新范围需要时调整审查上下文

盘点现有指令载体：

• AGENTS.md、嵌套的 AGENTS.md、AGENTS.override.md
• REVIEW.md、嵌套的 REVIEW.md
• CLAUDE.md、.claude/、GEMINI.md、.gemini/
• .cursor/rules/、.cursorrules、.windsurfrules
• .github/copilot-instructions.md
• .greptile/、greptile.json
• README.md、CONTRIBUTING.md、架构文档

编辑任何内容之前，先运行 scripts/audit-agents-md.sh（或同等的只读检查）。

2. 在本地构建文件夹映射

分派探索者之前，先查看文件系统。

• 使用 tree -d . 或 tree -dL 2 . 映射顶层文件夹和 src 文件夹。
• 标出候选指令边界：仓库根目录、每个 src/*、每个应用/软件包/服务根目录，以及具有独立工作流的文档/标准子树。
• 决定哪些文件夹需要专门的探索覆盖。
• 暂不起草。此步骤旨在便于妥善分配 Wave 2。

3. Wave 1 — 广泛架构

目标：识别架构形态、命令来源、关键工作流、主要边界，以及现有指令债务。

• Agent：根据仓库规模和独立问题的数量，安排 2 到 10 名探索者。
• 必需输出：整个仓库的命令来源、顶层架构图、现有指令冲突、适合放置本地 AGENTS.md 的候选文件夹、适合放置作用域限定的 REVIEW.md 的候选文件夹，以及需要在 Wave 2 解决的风险和未知事项。
• 提示词框架：references/discovery-prompts.md 中的 Wave 1 部分。派发前，填入仓库路径、目录树快照和现有指令相关位置。
• 探索者提示词：500–2500 个词。

等待收到所有 Wave 1 发现结果。继续之前，先比较其中的重叠、矛盾和缺漏。

4. Wave 2 — 文件夹专项深入探索

仅在 Wave 1 汇总完成后启动。

• 任务分配：根据 tree -dL 2 . 和 Wave 1 结果进行。为每位探索者分配一个文件夹或一个紧密相关的文件夹组。默认覆盖范围：src/ 下每个有意义的一级子文件夹。
• 必需输出：文件夹内的命令或工作流、本地架构和入口点、约定和风险、针对该文件夹的 AGENTS.md 的明确建议、该文件夹是否需要作用域限定的审查指南的明确建议，以及除默认的 CLAUDE.md 符号链接外是否需要额外的原生文件。
• 提示词框架：references/discovery-prompts.md 中的 Wave 2 部分。

等待收到所有 Wave 2 发现结果。写入前，汇总重叠内容并解决矛盾。

5. 写入前先综合规划 AGENTS 层级

将发现结果转化为文件计划：

• 根目录的 AGENTS.md 记录全仓库命令、架构、共享约定和顶层边界。
• 每个文件夹的 AGENTS.md 只记录该子树本地适用的内容。
• 子级文件可默认父级文件已提供全局规则。
• 如果某个文件夹只需要少量本地补充，就保持该文件简短，不要将内容并回根目录文件。
• 每个计划文件都要先用一句话说明其用途。
• 只有在计划确定后才使用 scripts/scaffold-agents-md.sh；不得用它来臆造结构。

6. 改写现有文件前先输出审计报告

如果仓库已有 Agent 指令，编辑前先输出审计报告。

使用 references/audit-and-migration.md。输出结构：

1. ## Agent Instructions Quality Report
2. 汇总数量和平均分
3. 逐文件评分并提供具体依据
4. 建议的更改
5. 仅在报告输出后应用编辑——除非用户明确豁免此要求

7. 起草 AGENTS.md 文件

按自上而下的顺序进行。使用 references/agents-md-format.md 中的 WHAT / WHY / HOW 筛选法。

• 使用直接指令和可衡量的边界。
• 保持根目录和子级文件精简。
• 只有在至少有 3 条仓库特定事实可支撑时才创建章节。
• 起草时自问：“如果缺少这一行，在此文件夹中编辑代码的人会犯错吗？” 如果不会，就删掉。

8. 创建配套入口点

AGENTS 层级稳定后：

• 创建同级的 CLAUDE.md，将其设为对应 AGENTS.md 的符号链接。
• 如果无法创建符号链接，则使用单行包装文件：@AGENTS.md。
• Claude 专属行为放在 .claude/ 中，绝不要把 CLAUDE.md 扩展成第二个事实来源。
• 让 Gemini、Copilot、Aider、Cursor 或其他原生配置入口指向 AGENTS 源文件，除非它们确实需要仅适用于 Agent 的行为。

完整支持矩阵和各 Agent 规则请参阅 references/agent-entrypoints.md。

9. 写作者 Agent 环节（可选）

两轮发现结果汇总后，如果文件计划涉及范围较广，可派发写作者。

• 写作者各自负责互不重叠的文件夹。
• 写作者提示词可以比探索者提示词长，但不得超过 5000 个词。
• 每份写作者提示词都要包含：目标文件路径、父子级边界、Wave 1 摘要、Wave 2 文件夹简报、已验证的命令，以及问题 “在此文件夹工作的代码编写者需要了解什么？”
• 提示词框架：references/discovery-prompts.md 中的写作者部分。

10. 生成评审上下文层

编写完 AGENTS 后，判断同样的证据是否足以支持创建 REVIEW.md。

• 默认在根目录创建 REVIEW.md，用于评审标准化工作，或在调研中发现值得记录的仓库特有风险时。
• 仅当某个子树存在独特的评审风险，且这些内容会使根目录文件臃肿或与其矛盾时，才使用作用域限定的 REVIEW.md。
• 将 AGENTS.md 用作操作指南，将 REVIEW.md 用作差异审查指南。
• 如果起草评审规则时发现缺少工作边界，请更新相关的 AGENTS.md。
• 如果有意跳过 REVIEW.md，请在最终回复中说明原因。

有关用途、例外情况、章节顺序、作用域限定评审规则和适配器关系，请参阅 references/review-context.md。

11. 最终确定前进行验证

• 根目录和文件夹中的 AGENTS.md 均已在计划要求的位置创建。
• 每个新建的 CLAUDE.md 都指向正确的同级 AGENTS.md，或已将备用包装文件记录为例外。
• 根目录的 REVIEW.md 已创建并反映实际风险领域，或已记录跳过原因。
• 仅在仓库确实需要时才存在作用域限定的 REVIEW.md 文件。
• 已验证命令和路径。
• 子级 AGENTS.md 文件没有不必要地重述根目录规则。
• REVIEW.md 中的规则具体且可供评审，不是对 linter 规则的重复。
• 配套文件没有成为第二个事实来源。
• 未解决的未知项已在回复中明确指出，而不是藏在文件里。

12. 最后一个可选步骤 — 原生评审适配器

只有通过第 11 步后，才提出一个简短问题：

AGENTS.md 层级已完成，REVIEW.md 的决策也已记录。此仓库还需要生成哪些原生评审适配器：Copilot、Devin、Greptile，还是都不需要？

• 如果用户回答 none，则停止。
• 如果用户指定平台，则在此技能中生成相应的原生适配器文件。
• 如果用户回答 all，请先确认仓库确实在使用这些平台，再编写文件。
• 将平台原生评审文件视为已完成的评审上下文的转译版本，而不是单独的事实来源。

适配器默认设置：

• Copilot -> .github/copilot-instructions.md，以及作用域限定的 .github/instructions/*.instructions.md；文件大小不得超过平台限制，并注明基分支行为。
• Devin -> 将 REVIEW.md 保留为主要评审入口；仅在需要时添加作用域限定的 REVIEW.md；编码行为沿用已完成的 AGENTS.md 层级。
• Greptile -> .greptile/config.json，以及可选的 rules.md 和 files.json；将 scope 保持为数组，将 ignorePatterns 保持为换行分隔的字符串，并注明源分支行为。

参考资料路由

只阅读能推进当前决策所需的最少参考资料。

需求	参考资料
Wave 1、Wave 2 或编写器提示词框架	references/discovery-prompts.md
REVIEW.md 的用途、例外情况、根目录／作用域划分、适配器关系	references/review-context.md
AGENTS 编写、文件夹作用域、WHAT／WHY／HOW、偏离预期行为目录	references/agents-md-format.md
配套入口、本原生评审适配器、设置注意事项、跨 Agent 接口	references/agent-entrypoints.md
现有文件审计、报告格式、迁移	references/audit-and-migration.md
根目录和文件夹文件的起始模板	references/project-templates.md

快速入门索引

情况	从这里开始	然后阅读
新仓库，没有 Agent 文件	references/project-templates.md	references/agents-md-format.md
现有仓库只有 CLAUDE.md	references/audit-and-migration.md	references/agent-entrypoints.md
单体仓库或大型 src/ 目录树	references/agents-md-format.md	references/project-templates.md、references/agent-entrypoints.md
多 Agent 团队（Codex + Cursor + Claude + Gemini）	references/agent-entrypoints.md	references/agents-md-format.md
编写文件夹级指令	references/agents-md-format.md	references/project-templates.md
现有配置冗杂或重复	references/audit-and-migration.md	references/agents-md-format.md
已完成 AGENTS+REVIEW，用户需要 Copilot/Devin/Greptile 适配器	references/agent-entrypoints.md	继续使用此技能并生成它们

从一两个参考文档开始。只有任务确实需要时才扩展阅读。

最终输出要求

生成或修改文件时，请返回：

1. 创建或修改的指令层级
2. 用于确定层级的仓库依据
3. 若存在现有文件，编辑前的审计报告
4. 审查上下文输出，或明确说明未生成的原因
5. 每个最终版 AGENTS.md 的配套入口文件状态
6. 达到的验证级别
7. 在生成的文件之外指出尚未解决的未知事项