accelint-onboard-agents

Onboard Agents

通过对话式访谈引导用户，产出一份完整、针对具体项目的 AGENTS.md 或 CLAUDE.md，说明 AI 编码 Agent 应如何在此代码仓库中行事。

关注点分离

本技能产出 Agent 指令栈中的行为层。

仅当某条内容能直接改善 Agent 反复出现的行为时，才将其保留在此处。如果某个细节更适合描述为项目背景、技术栈事实、架构说明、流程手册材料或邻近的参考文档，请使用规范配套文档并链接到它，而不是在此处重复陈述。这些层次之间不得相互重复。

规范配套文档可能包括：用于项目 DNA 的 openspec/config.yml 或 openspec/config.yaml，用于系统结构的 ARCHITECTURE.md，用于外部施加边界的 CONSTRAINTS.md，用于区分已验证事实与开放问题及假设的 EPISTEMIC-MAP.md，以及用于内部术语的 JARGON.md。

使用下面的规则来决定哪些内容留在本文件中，哪些内容属于规范配套文档。

硬性规则：哪些内容不属于此处

如果某材料无法回答"Agent 应如何行事？"，它就不属于 AGENTS.md 或 CLAUDE.md。

当存在合适的规范配套文档时，将该材料移至其中，否则就将其略去。

属于 AGENTS.md	属于规范配套文档
"提交前始终运行 pnpm check"	"包管理器：pnpm"
"使用 Conventional Commits"	"TypeScript 5.x，strict 模式"
"删除文件前先询问"	"单体仓库：Turborepo + PNPM"
"倾向于小而专注的 PR"	"优先使用 type 而非 interface"
"在有帮助时以资深 TS 工程师的身份工作"	"领域：地理空间可视化"
"绝不 force-push 到 main"	"测试：Vitest + @testing-library"
"在修改与部署相关的代码前阅读 ARCHITECTURE.md"	"服务拓扑与部署模型"
"在修改合规敏感流程前查看 CONSTRAINTS.md"	"实际的合规要求或利益相关方约束本身"

最终收录规则

只有在最终 AGENTS.md 或 CLAUDE.md 中能赢得永久位置的内容才应被收录。一个细节只有在满足以下条件时才能赢得该位置：

• 改变 Agent 应有的行事方式
• 适用于反复出现的工作，而非一次性任务
• 防止 Agent 犯下特定于本仓库的错误或做出无依据的假设
• 足够持久，适合作为长期指导
• 足够有价值，值得在每次 Agent 会话中加载

不要仅仅因为 Agent 可能尚不知晓某个细节就将其收录。只有当它描述的是影响 Agent 工作方式的、特定于本仓库的规则或例外时，才收录它。否则，将其略去或链接到包含它的规范文档。

角色或身份设定是可选的。仅当它能改善行为时才使用。不要让角色化语言取代操作性指导。

---

引导 Agent 时绝不要做的事

• 绝不要串行执行代码库发现 — 当需要发现时，针对不同的行为领域使用并行子 Agent。对于配置文件众多且分散在多个目录中的代码库，串行扫描会浪费时间。
• 绝不要在提问前跳过必要的发现 — 在向访谈中添加本可避免的问题之前，先从代码库中推断行为约定。当 commitlint.config.ts 已存在时，再问提交格式问题就是在浪费用户的时间。对于范围较窄的刷新，只做请求所需的限定范围内的发现。
• 绝不要从生成的 AGENTS.md 中省略必需的模板章节 — 如果 ./assets/template.md 中的某个必需章节无法推断或无法回答，保留该章节，并用 `` 标记未解决的字段，而不是省略该章节。只有在 ./assets/template.md 明确允许时，才可省略可选章节。缺失必需的模板章节会以不可预测的方式悄然塑造 Agent 的行为。
• 绝不要在包级文件中重复根级指令 — 如果存在 monorepo 根级 AGENTS.md 或 CLAUDE.md，包文件应引用它，并且只添加包特有的内容。重复的指令会在每次调用 Agent 时膨胀上下文。
• 绝不要仅仅因为冲突的常设规则都被找到就同时保留它们 — 使用来源优先级解决冲突，或者在预览中呈报未解决的问题，而不是将两者都作为权威指导输出。
• 绝不要在未展示预览的情况下写入最终文件 — 用户必须看到带有来源标注的推断值，并在任何文件系统写入之前进行确认。

---

冲突解决与来源优先级

当候选规则在导入、刷新或最终综合过程中发生冲突时，按以下顺序解决：

1. 用户直接确认的答案
2. 已确认的仓库策略或明确记录的仓库行为
3. 基于仓库材料且有证据支持的推断
4. 与更强证据保持一致的现有 AGENTS.md 或 CLAUDE.md 内容
5. 模板默认值或通用技能默认值
6. 当冲突仍未解决时，使用 `` 或明确的开放问题，而不是强行综合

每次都应用这条规则：

• 不要因为冲突的规则都被发现就同时保留它们。
• 不要让默认值优先于更强的仓库证据。
• 如果旧文件内容与当前已确认的证据冲突，不要让它原样保留。
• 当仍存在不确定性时，在预览中呈报，或使用 TODO，而不是发明一条统一的规则。

---

工作流一览

按顺序遵循此工作流。不要跳过步骤。在进入下一步之前完成每个关卡。

步骤 0：开始进度跟踪

在任何其他工作流步骤之前执行此操作。

使用你的任务跟踪工具创建一个进度清单。如果没有可用工具，请将下面的清单复制到你的工作状态或回复中。在完成每个步骤或分支交接后更新它。

• 步骤 1：检查 monorepo 根级指令文件
• 步骤 2：检查相关文档
• 步骤 3：检测本地文件状态
• 步骤 4：当检测到模式 2 或模式 3 时，确认如何使用现有文件
• 步骤 5：需要时在模式 2 或模式 3 内选择分支
• 步骤 6：运行选定的模式操作手册
• 步骤 7：如有需要，通过并行发现填补剩余的行为空白
• 步骤 8：运行最终编辑检查
• 步骤 9：展示带完整标签的预览并收集审阅反馈
• 步骤 10：当此路径会写入输出时，写入已确认的文件
• 步骤 11：当文件已写入时，运行写入后质量检查
• 步骤 12：打印完成摘要

重要顺序规则：

• 步骤 1、步骤 2 和 步骤 3 确定本地文件状态并检测模式。
• 步骤 4 和 步骤 5 确认用户意图，并在检测到的模式内选择分支。
• 步骤 6 只执行一个模式操作手册。
• 步骤 7 仅在所需模板字段仍有未解决的行为空白时运行。
• 步骤 8 到 步骤 12 完成预览、写入和审阅流程。

如果某个更窄的分支明确要求你跳过后续步骤，请遵循该分支。否则，保持此顺序。

---

阶段 1 — 检测起始状态

在提出任何访谈问题或进入任何模式特定路径之前，完成阶段 1。

• 不要静默选择模式。
• 始终告诉用户你检测到了哪个模式。
• 在继续之前进行确认。

步骤 1：检查 monorepo 根级指令文件

在评估本地文件之前，确定当前工作目录是否是 monorepo 内的一个包。

如果当前目录之上存在根级 AGENTS.md 或 CLAUDE.md：

1. 完整阅读根级文件。

2. 声明："我在 [path] 发现了根级 AGENTS.md 或 CLAUDE.md。我会将其用作上下文，以避免重复适用于所有包的指令。我在此处生成的文件将适当引用根级文件，而不是重复其内容。"

3. 在生成的文件中，添加一个头部引用：

4. 在访谈期间，每轮开始时，先说明根级文件对该部分已涵盖的内容，然后再提出任何问题：

   "根级 AGENTS.md 或 CLAUDE.md 定义了 [本部分内容的摘要]。

   在生成的文件中发出引用，而不是重复内容。如果用户提出新增或覆盖，请将常规轮次问题限定在缺失或不同的内容范围内。

第 2 步：检查相关文档

在第 1 步之后、本地文件状态检测之前，检查以下规范配套文档，这些文档要么：

• 有助于维护行为层边界，或
• 应归入最终的 ## Related Documentation 部分。

按顺序检查这些配套文档：

1. 检查 openspec/config.yml 或 openspec/config.yaml。
   • 如果任一文件存在，读取它以了解项目的技术栈和模式。
   • 记录其存在，以便写入 ## Related Documentation 部分。
   • 告知："Found openspec/config.yml or openspec/config.yaml — I'll use it to maintain the behavior/project-DNA boundary."
2. 检查 ARCHITECTURE.md。
   • 如果存在，读取它以了解系统结构。
   • 记录其存在，以便写入 ## Related Documentation 部分。
   • 告知："Found ARCHITECTURE.md — I'll use it when behavior guidance depends on system structure."
3. 检查其他规范配套文档，尤其是 CONSTRAINTS.md、EPISTEMIC-MAP.md 和 JARGON.md。
   • 如果存在，仅当该文档可能对行为指导、审批边界或面向 Agent 的术语产生实质性影响时才读取它。
   • 记录所有存在者，以便写入最终的 ## Related Documentation 部分。

在此检查过程中遵循以下限制：

• 不要将此步骤变成宽泛的手册扫描。
• 检测规范配套文档。不要将其完整内容吸收进 AGENTS.md。
• 只读取保持行为文件准确、范围明确且链接完善所需的内容。

第 3 步：检测本地文件状态

前置条件：第 1 步和第 2 步已完成。

检测本地 AGENTS.md 或 CLAUDE.md 的状态。

按顺序运行此检查：

1. 检查当前目录中是否存在本地 AGENTS.md 或 CLAUDE.md。
2. 如果两个文件都不存在，选择 模式 1：创建。
3. 如果本地文件存在，在分类模式之前先读取它。
4. 读取文件后，对它进行且仅进行一次分类：
   • 如果它为空或近乎空白，即少于约 10 行有意义的内容，选择 模式 1：创建，并需确认覆盖。 询问："AGENTS.md exists but appears empty — should I populate it from scratch, or preserve any current content?"
   • 如果它包含来自 ./assets/template.md 的规范模板形态，即两个或更多可识别为基于模板形式的规范章节标题，选择 模式 3：刷新。
   • 如果它包含无法识别形态的真实内容，选择 模式 2：导入。

将 ./assets/template.md 视为识别、刷新和审计行为的规范结构参考。严格使用其中定义的章节标题，对所有必需章节保留模板的规范顺序，并且仅当模板允许时才保留诸如 ## Optional review-specific rules 和 ## Maintenance guidance 之类的可选标题。

使用下面的示意图作为快速分类辅助。上面的有序列表为准。

Local `AGENTS.md` or `CLAUDE.md` in current directory?
│
├── No
│   └── MODE 1: Create
│       Full interview from scratch.
│
└── Yes
    ├── Read the file first
    └── Then classify:
        ├── Empty or near-blank (< about 10 meaningful lines)
        │   └── MODE 1: Create
        │       Ask: "AGENTS.md exists but appears empty — should I populate it from scratch, or preserve any current content?"
        ├── Canonical template shape from `./assets/template.md`
        │   └── MODE 3: Refresh
        │       Two or more canonical section headings in recognizably template-based form.
        └── Real content in an unrecognized shape
            └── MODE 2: Import

完成条件：文件状态和检测到的模式均已明确。

---

阶段 2 — 确认操作路径

在开始发现、漂移扫描或任何特定模式的访谈之前，先完成阶段 2。

第 4 步：确认如何使用现有文件

前置条件：第 3 步已完成。

如果第 3 步检测到 模式 2，先询问：

“在我开始之前，这个文件包含的内容并不遵循规范模板。 你希望从头开始，仅将现有文件作为参考 （推荐用于导入），还是基于现有文件继续？”

如果第 3 步检测到 模式 3，先询问：

“在我开始之前，这个文件已经遵循规范模板。 你希望基于现有文件继续 （推荐用于刷新）， 还是从头开始，仅将其作为参考？”

如果用户选择从头开始，立即切换到 模式 1：创建。

• 将现有文件视为只读参考。
• 将现有文件中仍然准确的内容延续下来。
• 不要静默丢弃这些内容。
• 使用模板来控制新文件的顶层结构，而不是用它来决定现有指引是否可以保留。
• 如果现有指引通过了最终纳入规则，但模板中没有对应的专属标题，则将其放入管辖该行为的规范章节。
• 不要仅因为模板未命名该内容，就新增顶层章节或丢弃该指引。
• 从头重新生成结构。
• 然后转到 第 6a 步。

如果用户选择基于现有文件继续：

• 如果第 3 步检测到 模式 2，转到 第 5a 步
• 如果第 3 步检测到 模式 3，转到 第 5b 步

如果第 3 步已选择 模式 1，跳过第 4 步和第 5 步。直接转到 第 6a 步。

完成条件：只要检测到模式 2 或模式 3，从头开始与基于现有文件继续之间的选择就已明确。

第 5a 步：选择模式 2 分支

前置条件：第 4 步从 模式 2 路由到此。

在你修改或合成任何内容之前，先给出以下三个选项：

“这个 AGENTS.md 的现有内容采用了我无法识别的结构。 你希望如何继续？

(a) 重构 — 我会导入你的现有内容，将其映射到本 skill 的模板章节，标记出应归入规范配套文档的任何材料， 运行一次针对性访谈以填补空白， 并生成一个可替换当前文件的合并文件。

(b) 追加 — 我会运行完整访谈，并在你现有内容下方追加一个与模板对齐的 AGENTS.md 块，不修改已有内容。

(c) 试运行 — 我会运行完整访谈，并向你展示我本会 生成的确切内容，且不对文件系统做任何更改。可用它在提交前 评估适配度。”

分支路由：

• 如果用户选择 (a)，转到 第 6b 步。
• 如果用户选择 (b)，转到 第 6c 步。
• 如果用户选择 (c)，转到 第 6d 步。
• 在用户做出选择之前，不要启动任何分支。

完成条件：模式 2 分支已明确。

第 5b 步：选择模式 3 刷新路径

前置条件：第 4 步从 模式 3 路由到此。

只有在模式 3 意图门控满足后，才选择恰好一条刷新路径：

• 针对性刷新 — 当请求已处于本 skill 的边界内且范围明确受限时使用，例如：
  • 修复一处已知矛盾
  • 根据新确认的证据更新一个章节
  • 移除或弱化一条过时规则
  • 在现有章节中新增一项范围狭窄的内容
  • 在周边结构不变的情况下更新一个包装器或转换
• 完整刷新 — 当请求范围较广、文件可能在多处发生偏移，或狭窄更新暴露出需要更广泛审查的矛盾、跨章节依赖或不一致时使用。

分支路由：

• 如果请求符合针对性刷新条件，转到 第 6e 步。
• 否则，转到 第 6f 步。

完成条件：在开始刷新分析之前，模式 3 刷新路径已明确。

---

阶段 3 — 运行所选模式的执行手册

只运行一个第 6 步分支。

基于访谈路径的共享访谈块

仅在阶段 1 和阶段 2 完成后才进行访谈。以对话方式开展。不要一次性抛出所有问题。将问题按自然的主题轮次分组，直接对应 ./assets/template.md 中的规范模板。该模板是章节名称、章节顺序、必需与可选章节、占位符处理以及默认脚手架的权威来源。如果用户描述了某个工作流，应推断相关的行为约束并加以确认，而不是再次询问。问题数量应与请求规模成比例。不要询问强仓库证据已能回答的信息。

只询问属于模板范围的内容。不要凭空发明额外的 AGENTS.md 章节来承载模板未定义的答案。如果某个主题在模板中是可选的，应根据 ./assets/template.md 所允许的内容，确认它是应保留、调整还是省略。在跨轮次整合答案时，将它们映射回 ./assets/template.md 中定义的精确规范章节。

第 1 轮 — 优化目标

• Agent 在此仓库中应优化哪些持久性优先事项？ （示例：遵循仓库工作流而非猜测，优先进行小范围改动，使工作可追溯，与现有模式保持一致。）
• 是否存在会实质性影响 Agent 行为的仓库特定优先事项？
• Agent 应强调简洁、速度、安全性、可审查性，还是其他长期优先事项？

第 2 轮 — 沟通方式

• Agent 应如何沟通？ （示例：简洁、说明性、对话式、自适应）
• Agent 应解释其推理过程，还是直接行动？
• 进行更改时，是否存在超出模板已有内容的必需报告预期？ （示例：展示 diff、展示完整文件、行内注释、单独的解释块？）
• Agent 应如何处理信息缺失或不确定性？ （示例：陈述假设并谨慎推进、始终先询问、仅对影响范围的变更的不确定性进行询问？）

第 3 轮 — 工作方式

• 进行更改之前，Agent 必须先阅读、确认或陈述什么？
• 进行更改时，是否存在超出模板默认值的长期工作流预期？
• 完成任务之前，哪些验证、范围检查或安全检查必须始终执行？
• 如果仓库使用 OpenSpec 或其他规范驱动工作流，仅将其行为作为长期 Agent 工作流指南记录在此，并链接到规范文档以获取更深入的流程细节。

第 4 轮 — 仓库特定命令和入口点

• Agent 在设置、构建、测试、lint/format 和任务运行方面应优先使用哪些命令？
• 是否存在容易出错的路径约定、包管理器规则或命令调用模式？
• 是否有某些命令 Agent 应避免使用，而改用特定的仓库入口点？

第 5 轮 — 决策启发式

• Agent 何时应询问，何时应自主推进？ 好的提示：「删除文件」、「更改公共 API」、「修改迁移」、「添加新依赖」。
• 如果任务中途范围扩大，默认操作是什么？
• 如果证据不完整或有多种有效实现，Agent 应自行选择、询问，还是呈现权衡？

第 6 轮 — 审批和安全边界

• 哪些操作因有风险、成本高、难以逆转或影响共享系统而需要审批后才能继续？
• 必须始终保留哪些硬性安全边界？ 示例：绝不提交密钥，schema 或迁移更改前先询问，未经批准不得对生产环境操作。
• 是否存在应在此记录的沙箱、远程环境、发布或外部依赖的信息边界？

第 7 轮 — 完成工作的质量标准

• 工作被视为完成之前需要哪些检查？
• Agent 应回报哪些证据？
• 是否存在此仓库特有的审查或交接预期？ 第 8 轮 — 可选的审查专用规则、相关文档与维护指南
• 该仓库是否使用 AGENTS.md 来指导代码审查行为，且其力度足以保留 ## Optional review-specific rules，还是应当省略这个可选章节？
• 如果 ## Related Documentation 中应出现的规范文档确实存在，那么应该是哪些？
• 是否有仓库专用的维护指南需要添加到 ## Maintenance guidance 下，还是应原样保留模板默认内容？

基于访谈路径的共享智能默认值块

仅在你已经检查过更强证据之后，才使用智能默认值来减少可避免的访谈负担。

智能默认值是一种确认提示，而不是既定策略。仅在以下情况下使用：

• 相关模板字段仍需要一个答案
• 直接的用户输入尚未回答该问题
• 仓库证据尚未回答该问题
• 该默认值能帮助用户比从头询问更快地确认一种可能的约定

不要使用智能默认值来引入新策略、扩大范围，或将生态系统的假设带入生成的文件中。

应用以下规则：

1. 更强的证据优先。 如果直接的用户输入、仓库证据、规范模板，或仍然一致的现有指南已经回答了该字段，就不要为该字段提供默认值。
2. 将默认值作为提示提供，而非结论。 将默认值表述为需要确认、否决或完善的内容。不要将其呈现为已采纳的策略。
3. 让默认值与证据相称。 优先使用窄范围的提示，一次只测试一种可能的约定。不要将一个仓库信号扩展成宽泛的工作流组合。
4. 让示例仅作说明之用。 下面的示例提示展示的是常见模式。它们并非详尽无遗的清单，也不是每次运行都必须出现。
5. 在用户或仓库证伪某个默认值后，不要保留它。 用更强的答案替换它，或者如果该字段仍无法确认，则留空 ``。

示例提示模式

仅当这些模式与已收集的仓库证据相符时才使用它们。

如果仓库似乎使用 PNPM monorepo：

• “我发现了 PNPM 工作区的迹象。在生成的指南中，我是否应区别对待工作区根级与包级依赖变更？”
• “当包的选择很重要时，你是否希望 Agent 优先使用工作区感知的任务命令？”

如果仓库似乎使用 GitHub Actions 进行 CI：

• “我发现了 GitHub Actions 工作流。生成的指南是否应要求 Agent 在认为工作完成之前报告或等待特定的 CI 检查？”
• “是否有必需的状态检查或 PR 门禁应出现在该文件中？”

如果仓库似乎使用 Conventional Commits：

• “我发现了提交约定的信号。该文件是否应告诉 Agent 使用 Conventional Commits，是否有仓库专用的类型或破坏性变更规则需要注明？”
• “scope 的使用方式或 footer 约定是否重要到需要明确说明？”

如果仓库似乎使用 OpenSpec 或其他规范驱动的工作流：

• “我发现了规范驱动工作流的迹象。该工作流的哪些部分是应归入 AGENTS.md 的持久 Agent 行为，哪些部分应留在规范的项目文档中？”
• “对于非平凡的变更，Agent 是否应在实现之前先从文档化的规范工作流开始？”

完成条件：可能的约定已被确认、否决或被更强的证据替换，且没有任何未确认的默认值被带入既定指南中。

步骤 6a：运行模式 1 — 创建

当面对一个全新的仓库、用户希望填充的空文件或近乎空白的文件，或用户明确选择 从头开始 时，使用此分支。

按顺序运行此分支：

1. 运行 基于访谈路径的共享访谈块。
2. 运行 基于访谈路径的共享智能默认值块。
3. 如果仍有未解决的必需模板字段，请转到 步骤 7。
4. 否则，请转到 步骤 8。

完成条件：访谈答案及任何已确认的智能默认值已准备好用于填补空缺的发现流程，或草稿已准备好进行最终编辑润色。

步骤 6b：运行模式 2 — 重构

仅当文件包含本技能未生成的真实内容且用户选择了 (a) 重构 时，才使用此分支。

按顺序运行此分支：

1. 完整读取该文件。
2. 将每个现有章节映射到 ./assets/template.md 中的规范模板章节。
3. 保留模板的章节顺序，仅保留模板明确允许的可选章节，例如 ## Optional review-specific rules。
4. 标记任何违反关注点分离边界的内容，例如技术栈事实、技术版本、领域描述、约束、假设或内部术语。将这些材料移至相应的规范配套文档。
   • 对于每处违规，请询问：“这里描述了 [X] —— 这应属于规范配套文档，而非 AGENTS.md 或 CLAUDE.md。我是否应将其移至相应文档并在此处留下引用？”
5. 仅针对未覆盖的缺口（即 ./assets/template.md 中尚无现有覆盖的规范模板章节或必需模板字段）运行 基于访谈路径的共享访谈块。
6. 应用来源优先级规则，并在预览前移除重复、冲突或相邻文档材料。
7. 如果步骤 6 之后必需模板字段仍无答案，请转到 步骤 7。
8. 否则，请转到 步骤 8。
9. 在 步骤 9 中，写入前展示合并预览。沿用内容标记为 # from existing file；新内容标记为 # new。

完成条件：合并草稿已准备好进行最终编辑润色，或任何剩余缺口已转至步骤 7。

步骤 6c：运行模式 2 — 追加

仅当文件包含本技能未生成的真实内容且用户选择了 (b) 追加 时，才使用此分支。

按顺序运行此分支：

1. 运行 基于访谈路径的共享访谈块。
2. 运行 基于访谈路径的共享智能默认值块。
3. 如果仍有未解决的必需模板字段，请转到 步骤 7。
4. 否则，请转到 步骤 8。
5. 在 步骤 10 中，将生成的对齐模板的块追加到 --- 分隔线和注释下方：``。

即使在追加模式下，也不要在预览中未呈现冲突的情况下添加有冲突的常设指导。

完成条件：追加草稿已准备好进行最终编辑润色，或任何剩余缺口已转至步骤 7。

步骤 6d：运行模式 2 — 试运行

仅当文件包含本技能未生成的真实内容且用户选择了 (c) 试运行 时，才使用此分支。

按顺序运行此分支：

1. 运行 基于访谈路径的共享访谈块。
2. 运行 基于访谈路径的共享智能默认值块。
3. 如果仍有未解决的必需模板字段，请转到 步骤 7。
4. 否则，请转到 步骤 8。
5. 在 步骤 9 中，在带标签的预览后停止。
6. 在对话中展示输出并明确说明：“未更改任何文件。”
7. 如果用户满意，提供以 (a) 重构 或 (b) 追加 重新运行的选项。
8. 跳过 步骤 10 和 步骤 11。在步骤 9 之后直接转到 步骤 12。

完成条件：试运行草稿已准备好进行最终编辑润色，或任何剩余缺口已转至步骤 7。

步骤 6e：运行模式 3 — 定向刷新

仅当文件符合技能预期的形态、用户选择基于现有文件继续工作，且请求是一次范围明确、目标章节或问题已知的更新时，才使用此分支。

按顺序执行此分支：

1. 先检查受影响的章节。
2. 只做该范围明确的更新所需的限定范围发现。
3. 只提问解决该更新所需的问题。
4. 避免完整访谈和完整重新生成，除非缺失的上下文要求如此。
5. 保留文件其余部分，除非这一范围狭窄的更新暴露出更广泛的矛盾或漂移。
6. 对受影响的内容以及任何直接依赖的章节应用来源优先级和最终编辑审校。
7. 如果更新暴露出更广泛的矛盾或漂移，在继续之前转到 步骤 6f。
8. 如果该范围明确的更新仍留下未解决的必填模板字段，转到 步骤 7。
9. 否则，转到 步骤 8。

完成条件：定向刷新草稿已准备好进行最终编辑审校、工作已升级至步骤 6f，或任何剩余的必填缺口已转至步骤 7。

步骤 6f：运行模式 3 — 完整刷新

仅当文件符合技能预期的形态、用户选择基于现有文件继续工作，且定向刷新不充分时，才使用此分支。

按顺序执行此分支：

1. 提取外部发现。

   • 检查调用提示词中是否包含 findings: 列表。
   • 从提示词中解析 findings: 部分，即一组项目符号形式的事实陈述。
   • 每条发现都以已知为真的事实表述，绝不表述为指令。
   • 示例："config.yaml 的 Anti-Patterns 部分说要避免轮询，但两个已归档的变更出于所述理由选择了轮询"
   • 存储这些发现，以便后续合并。

2. 运行漂移检测。 扫描代码库，查找自文件上次更新以来的变更。

   将以下信号作为常见示例，而非详尽列表。

   信号	查看位置
   新增包	package.json、工作区 package.json 文件
   CI 检查变更	.github/workflows/ — 新增必需门禁？
   Husky 钩子修改	.husky/ — 新增 pre-commit 步骤？
   新增迁移目录	migrations/、prisma/migrations/、alembic/
   新增版本管理工具	.changeset/、.releaserc*
   OpenSpec 新增或移除	openspec/ 目录是否存在
   新增受保护分支	.github/branch-protection*、README

3. 暴露未解决的 TODO。 找出上次运行留下的所有 `` 标记，并将其作为定向问题暴露出来。

4. 在提问之前先合并并公布发现。 合并来自步骤 6f.1 的外部发现、来自步骤 6f.2 的漂移发现，以及来自步骤 6f.3 的 TODO。

   向用户展示合并后的列表：

   "I found [N] external findings, [M] sections that may have drifted, and [P] unresolved TODOs. I'll only ask about those — the rest looks current."

   如果存在外部发现，注明其来源，例如 "from completed OpenSpec change"。

5. 运行刷新访谈，然后先预览变更的章节。 仅在步骤 6f.4 完成后：

   • 针对合并后的发现集合运行定向刷新访谈
   • 应用来源优先级
   • 删减重复内容和低价值的沿用文本
   • 先展示仅包含变更章节的 diff 风格预览
   • 不要在首次刷新预览中重新输出未变更的章节
   • 在任何写入之前，仍须按照步骤 9 的要求生成完整的带标签预览

6. 如果刷新仍留下未解决的必填模板字段，转到 步骤 7。

7. 否则，转到 步骤 8。

完成条件：变更章节草稿已准备好进行最终编辑审校，任何剩余的必填缺口已转至步骤 7，且完整的带标签预览仍待步骤 9 处理。

---

阶段 4 — 通过并行发现填补剩余的行为缺口

步骤 7：通过并行发现填补剩余的行为空白

仅在一个步骤 6 分支完成后运行步骤 7，且仅针对仍存在未解决行为空白的规范模板章节或必填模板字段。如果所选的步骤 6 分支已有足够确认的信息，请跳过步骤 7，直接进入 步骤 8。

审计 ./assets/template.md 中每个仍无答案的规范模板章节和必填模板字段，包括 ## Quality bar for finished work、## Related Documentation 和 ## Maintenance guidance（如适用）。对于每个空白，在再次询问或留下 `` 之前，尝试通过并行子 Agent 直接从代码库中推导行为意图。带有明确 TODO 的行为文件是可执行的。缺少必填模板章节的文件会以不可预测的方式悄悄塑造 Agent 行为。

发现用于填补行为空白。它不会最大化输出范围。必要时广泛收集，但只保留通过最终纳入规则的发现。

并行生成发现子 Agent。不要串行扫描。每个 Agent 专注于一个行为领域并返回结构化发现。等待所有 Agent 完成。然后在步骤 8 之前合并结果。

同时生成这些 Agent：

Agent A — 版本控制与提交约定

• 提交约定：commitlint.config.*、最近的 git log --oneline、.gitmessage、.releaserc*
• 版本管理工作流：.changeset/、CHANGELOG.md、standard-version、conventional-changelog
• 强制推送保护：.github/branch-protection*、README 中提及的分支策略
• 返回：含类型与示例的提交信息格式、版本管理命令、分支保护规则

Agent B — CI/CD 与 pre-commit 工作流

• PR 工作流：.github/PULL_REQUEST_TEMPLATE.md、.github/workflows/（CI 门禁名称、必需检查）
• pre-commit 检查：.husky/、.lefthook.yml、package.json#scripts（lint、typecheck、test）
• 返回：PR 约定（大小、标签、模板）、含命令的 pre-commit 检查清单、CI 必需检查

Agent C — 测试与代码质量

• 测试运行器：vitest.config.*、jest.config.*、pytest.ini、pyproject.toml [tool.pytest]、Playwright、Cypress
• 包管理器：package-lock.json、yarn.lock、pnpm-lock.yaml、bun.lockb
• TypeScript 项目：是否存在 tsconfig.json、tsconfig.json#paths 或 vite.config 中的路径别名
• Vitest 配置：vitest.config.ts — 检查 clearMocks、mockReset、restoreMocks 标志
• 测试文件类型检查：CI 工作流、package.json scripts — 检查 tsc --noEmit 是否在测试文件上运行
• 返回：测试框架、包管理器、TS 特定防护措施（如适用）、vitest 清理配置

Agent D — 安全与迁移

• 迁移文件：是否存在 migrations/、prisma/migrations/、alembic/
• 密钥处理：.env.example、.gitignore 模式、是否存在 dotenv 或 vault 工具
• 返回：迁移防护措施（如存在迁移）、密钥处理实践

Agent E — OpenSpec 与规范驱动工作流

• OpenSpec 信号：openspec/ 目录、openspec/config.yml、openspec/config.yaml，以及任何 opsx:* 或 openspec-* 技能引用
• 相关工作流证据：仅当伴随文档定义了与规范驱动工作相关的持久 Agent 工作流预期时
• 返回：是否正在使用规范驱动工作流、哪些部分应归入持久 Agent 行为指导，以及 Agent 应在何时调用该工作流

所有 Agent 完成后： 将其发现合并为统一的发现映射。 将每个模板字段标记为 # inferred from [source]，如果未知则留空。发现后仍为空的字段将成为生成文件中的显式 `` 标记，可选模板章节只有在模板明确允许删除时才应省略。

带来源注释的预览： 合并发现结果后，展示一个预览，并在推断值后面附带行尾注释：

- Always run `pnpm check` before committing   # inferred from .husky/pre-commit
- Use Conventional Commits (`feat:`, `fix:`)  # inferred from commitlint.config.ts

如果某个字段无法推断——例如决策启发式、沟通风格或角色定义——请用 `` 标记，而不是省略该部分。

完成条件：剩余的行为缺口要么已根据仓库证据解决，要么在 Step 8 之前留作明确的 TODO。

---

Stage 5 — 预览、写入与质量检查

在所选路径的所有先前必需步骤完成之前，不要进入 Stage 5。

Step 8：在预览前运行强制性最终编辑审查

在用户审阅之前清理已汇总的草稿。

• 对跨部分重叠的指导内容去重。
• 使用来源优先级规则解决矛盾。
• 移除不直接约束 Agent 行为的相邻文档或手册式材料。
• 降级脆弱的细节，除非这些细节有据可依、能够塑造行为且持久有效。
• 将支撑不足的细节替换为持久规则、规范链接，或在置信度过低时替换为 ``。
• 优先选择更简短、更精炼、更聚焦行为的最终草稿，而非更宽泛但更嘈杂的版本。

完成条件：草稿已清理完毕，可供预览。

Step 9：展示带标签的预览并收集审阅反馈

在写入任何内容之前，展示清理后的 AGENTS.md 或 CLAUDE.md 的完整带标签预览。

• 推断值附带其来源注释。
• 对于 Step 6b，沿用的内容标记为 # from existing file；新增内容标记为 # new。
• 未解决的模板字段附带 ``。
• ./assets/template.md 中要求的模板部分按模板顺序保留。
• 可选部分仅在仍对仓库有用且 ./assets/template.md 允许时保留。
• 对于刷新流程，你可以先展示变更的部分，但在任何写入之前仍需提供完整的带标签预览。

这为用户提供了完整的置信度图。

Gate — 在任何写入之前收集审阅反馈

询问：“这样看起来对吗？在我写入文件之前，有没有需要更正或扩充的部分？”

在非交互或无头环境中，仍要生成完整的带标签预览，并明确说明无法在会话内收集人工确认。如果文件未经人工确认，不要声称已经人工确认。

在此 Gate 得到满足或上下文明确为非交互之前，不要写入文件。

完成条件：审阅 Gate 已满足，或上下文明确为非交互。

Step 10：写入已确认的文件

仅对会写入输出的分支运行此步骤。对于 Step 6d 跳过此步骤。

只有在审阅 Gate 满足之后，才写入正在接入的目标目录中的 AGENTS.md 或 CLAUDE.md，并去除推断来源注释。

这些注释仅供审阅使用，不得出现在最终文件中。

对于 ## Related Documentation 部分，仅为仓库中存在且对 Agent 行为有实质帮助的文件添加链接。在添加每个候选文件的链接之前先检查该文件。根据实际仓库文件调整或移除模板中的示例项目符号（ARCHITECTURE.md、CONSTRAINTS.md、openspec/config.yaml、JARGON.md 以及任何其他规范文档占位符）。如果 openspec/config.yml 或 openspec/config.yaml 不存在，则不要包含这两个路径中的任何一个。

完成条件：已写入确认的文件，且不含仅供审阅的注释。

第 11 步：运行 AGENTS.md 或 CLAUDE.md 质量检查

仅在第 10 步写入文件后运行此步骤。对于 第 6d 步跳过此步骤。

写入完成后，根据 ./references/rubric.md 评估生成的文件。

将评分标准用作结构化的写后审查，而不是礼节性的提及。审查生成的 AGENTS.md 或 CLAUDE.md。如果生成的文件是 CLAUDE.md，则对其应用与仓库的 Agent 指令文件相同的评分标准。仅在需要验证范围或引用时，查阅同目录或根级别的 Agent 指令包装文件以及直接链接的相关文档。

按以下顺序运行审查：

1. 确认审查产物。
2. 仅收集公平评分所需的证据。
3. 按 0-5 分制对每个评分标准类别进行评分。
4. 使用此公式应用类别权重：(raw score / 5) × category weight。
5. 添加审查说明和不计分的有效性检查。

为用户生成一份简洁的审查结果，包括：

• 被审查的文件路径
• 满分 100 的总加权得分
• 使用以下等级对应的字母评级：
  • A = 90-100
  • B = 75-89
  • C = 60-74
  • D = 40-59
  • F = 0-39
• 2-4 条简要优点
• 最弱的评分标准类别及其原始得分
• 风险最高的弱点（如有）
• 一段简短的不计分有效性说明，涵盖该文件在实践中是否可能改变 Agent 行为

使用该结果来驱动面向用户的完成行为：

• 如果评级为 A，告诉用户你已对生成的 AGENTS.md 或 CLAUDE.md 进行评分，并发现质量很强。
• 如果评级为 B，以简单说明告诉用户你已对生成的 AGENTS.md 或 CLAUDE.md 进行评分，并发现质量合格。
• 如果评级低于 B，警告用户该文件低于期望的质量标准，并提供与最弱评分标准类别相关的具体补救建议。保持补救指导可操作、简洁且按优先级排序。同时提出可以修改文件以解决影响最大的问题。

不要夸大确定性。如果部分得分取决于不完整的仓库证据，请简要说明。

完成条件：用户同时拥有生成的文件和写后质量评估。

第 12 步：打印完成摘要

仅在适用的前一步骤完成后运行此步骤。

在写入和质量检查完成后，打印一份简要摘要，说明生成了什么、哪些是推断的与直接回答的、哪些 `` 部分仍需要人工输入，以及质量检查结果。

对于 第 6d 步，打印相同的简要摘要，但不包括写入和质量检查结果，并明确说明未写入状态。

完成条件：用户拥有最终的完成摘要。

---

AGENTS.md 模板

阅读并使用规范模板：./assets/template.md

将该文件视为 AGENTS.md 结构的唯一事实来源，包括确切的章节名称、章节顺序、必需与可选章节、占位符处理以及默认脚手架。在生成、导入、重构、追加、审计或刷新 AGENTS.md 时，将所有结构敏感的行为映射回该模板，而不是本技能中的示例、检查清单或嵌入的章节列表。

在生成或刷新 AGENTS.md 时，严格遵循模板，从已确认的答案或仓库证据中填充占位符，将未解决的占位符替换为 ``，保留必需的模板章节，并仅在模板明确允许时省略可选章节。保持最终文件精简且以行为为重点，而不是逐字复制说明性文本，除非已确认或强烈推断。

---

质量检查清单

在你认为引导流程完成之前，请验证生成的文件：

• 保留行为层与项目 DNA 的分离，并将非行为层材料重定向到相应的规范配套文档，例如 openspec/config.yml、openspec/config.yaml、ARCHITECTURE.md、CONSTRAINTS.md、EPISTEMIC-MAP.md 或 JARGON.md
• 覆盖 ./assets/template.md 中每一个必需的模板章节，且遵循模板中的顺序，对仍然未知的事实使用 ``
• 引用根级 Agent 指南，而不是在 monorepo 包文件中重复它
• 仅包含仓库中确实存在的相关文档链接
• 使用来源优先级解决矛盾，而不是保留相互冲突的现行规则
• 在各章节之间去重重叠的指导内容
• 移除低价值、不稳定、手册风格或相邻文档类材料，这些材料不会实质性地引导 Agent 行为
• 保持各章节精简并聚焦于行为层，而不是为了表面完整性而堆砌内容
• 将模板示例和默认值视为说明性脚手架，而非自动生效的策略
• 仅在可选模板章节仍然适合仓库且模板允许时，才保留这些章节
• 在任何文件系统写入之前展示完整预览，并从最终文件中移除推断性注释
• 在写入后对照 ./references/rubric.md 进行审查，并将由此产生的质量说明或整改指导呈现给用户

---

交互原则

• 并行发现。 当需要发现时，同时启动子 Agent。不要逐个扫描配置文件。
• 对话式，而非审问式。 将相关问题合并到同一轮对话中。使用通俗易懂的说明性语言，而不是罗列问题的清单。
• 推断并确认。"你提到了 Husky —— 我假设 pre-commit 钩子会运行 pnpm check；你能确认吗？"比从头开始提问更好。
• 示例减少歧义。 当询问决策启发式时，提供具体场景，以便用户进行模式匹配。
• 迭代式。 允许用户在最终写入之前修改答案。
• 写入前预览。 始终展示完整生成的 AGENTS.md 或 CLAUDE.md，并在触碰文件系统之前获得明确确认。
• 先推断再询问，先询问再省略。 带有明确 TODO 的文件是可操作的。缺少章节的文件会以不可预测的方式悄然影响 Agent 行为。
• 适度性很重要。 使用仍然能产生可靠结果的最轻量工作流。让范围较窄的刷新保持范围较窄，除非它们暴露出更广泛的偏差。
• 不要跨越层边界。 如果用户在此访谈过程中主动提供非行为层材料，请予以确认，并指出它属于相应的规范配套文档，而不是 AGENTS.md 或 CLAUDE.md。将项目 DNA 通过 accelint-onboard-openspec 导向 openspec/config.yml 或 openspec/config.yaml，将系统结构通过 accelint-architecture-doc 导向 ARCHITECTURE.md，将内部术语通过 jargon-extractor 导向 JARGON.md，将假设和风险通过 epistemic-mapper 导向 EPISTEMIC-MAP.md，将外部边界通过 constraints-extractor 导向 CONSTRAINTS.md。
• Monorepo：引用，而非重复。 如果存在根级 AGENTS.md 或 CLAUDE.md，包级文件应引用它，并仅添加该包特有的内容。跨根文件和包文件重复的指令会在每次 Agent 调用时膨胀上下文，因此保持包文件为增量式，而非冗余式。
• 先综合，再预览。 用户应审查清理后的最终草稿，而不是原始汇编的笔记。