bootstrap-agents-md

初始化 AGENTS.md

创建最精简的根目录指令集，为能力出色的编码 Agent 提供它们无法可靠自行推断的项目信息。严格遵守硬性约定；如果当前仓库中的证据足以指导实现和呈现方式，就留给 Agent 自行决定。

输出约定

除非用户要求采用更广泛的指令层级，否则请在仓库根目录生成以下文件：

• AGENTS.md：高信号的仓库事实、边界和验证要求，值得占用持久上下文空间。
• CLAUDE.md：内容必须恰好为 @AGENTS.md，后跟一个换行符。

替换现有根目录指令文件时，应编写连贯的新文件，而不是在原文后追加内容。保留有依据的意图，不必沿用旧文件的结构。

如果精确命令、相对仓库根目录的路径、工具或依赖项名称、版本及 URL 的字面形式会影响 Agent 行为，且仓库证据表明它们稳定，则可将其写入 AGENTS.md。不要包含秘密、机器本地绝对路径、复制的会话历史、易变的清单，以及称职的 Agent 可以轻松从仓库中查明的细节。

1. 确定范围并了解基线

1. 根据工作区证据确定仓库根目录。
2. 记录工作树状态，并保留无关更改。
3. 将现有根目录 AGENTS.md 和 CLAUDE.md 作为证据阅读。记录必须保留、修改或删除的重要意图。
4. 查找嵌套指令文件，并遵守其更窄的适用范围。只有当用户将这些文件纳入要求时，才修改它们。

只有在存在多个可能的根目录或指令所有者，且它们会导致实质不同的结果时，才暂停并请求澄清。

**完成条件：**对目标根目录、授权修改的文件、现有重要意图、嵌套优先级和无关工作都有充分了解，无须猜测即可开始编写。

2. 适度检查项目

检查能够揭示非显而易见根目录指引的证据：项目用途、持久的架构或领域术语、公开边界、测试、已配置的检查、交付或迁移风险、外部影响，以及重复出现的本地惯例。识别生成文件、供应商代码、缓存、二进制文件和含秘密的区域，避免不必要地读取其内容。

根据仓库和任务规模调整检查范围。优先参考重复出现的代码、测试、自动化配置和维护中的设计记录，而非孤立示例。解决会影响拟保留规则的矛盾；对于无需写入持久上下文且依据不确定的说法，应予省略。

目标是为最终指引收集充分证据，而不是清点每个文件或永久记录编写过程。

**完成条件：**每条拟定的项目专属规则都有证据支持，继续检查也不太可能实质性改变根目录指引。

3. 决定哪些内容值得纳入持久上下文

只有当规则适用于整个项目、不显而易见、会改变行为、有依据且足够持久，值得始终加载并引起关注时，才应保留。如果用户明确要求某条规则，或观察到的失败表明能力足够强的模型仍需要额外引导，也可以纳入该规则。

根据后果调整具体程度：

指引	处理方式
硬性约束	当正确性、安全性、兼容性或测试框架要求时，明确说明具体语法、适用范围或禁止事项。对可能造成重大代价的失败，应配套说明安全做法。
项目启发式	说明项目特有的原因和预期结果。让 Agent 根据当前证据选择实现机制。
开放选择	除非仓库或用户有约束，否则由 Agent 自行决定标题、顺序、实现设计、测试形式、抽象方式和文档篇幅。

从最精简的规则集开始。只有在形式必须精确，或清晰表述仍无法消除已出现的歧义时，才添加示例；普通措辞和排版的示例可能会意外变成模板。

排除一般的胜任 Agent 建议、重复强调紧迫性、工具已强制执行的风格偏好、临时流程、推测性架构和重复的源材料。如果仓库可以通过机制强制执行某项保证，就将其交由自动化实现。

除非项目证据或用户明确有意设定边界，否则应将子系统、依赖项或工作流的缺失视为当前状态，而非永久禁令。

完成条件： 每条保留的指令都有关键且充分的理由；每项省略的选择要么可从仓库中获知，要么是有意留给 Agent 判断。

4. 围绕项目起草，而非套用模板

选择最便于使用本仓库指引的结构。小型项目可能只需要几条规则。复杂服务可能值得单独说明领域不变量、运维风险、验证要求或指令优先级。章节名称、顺序和数量都是产出选择，而非发布要求。

文字应介于空泛口号和僵化的实现脚本之间。说明项目事实、其重要性以及应保留的结果。如果抽象表述会降低指令的可操作性，就使用具体细节；如果细节对根目录上下文而言过于易变，则指向更具体的来源。

完成条件： 草稿简洁、针对项目、前后一致，并将不值得限定的决定留给 Agent。

5. 编写并验证这对文件

1. 按用户授权，将根目录下的 AGENTS.md 写为干净的替换文件，或新建该文件。
2. 将 CLAUDE.md 写成精确的导入行，并在末尾添加换行符。
3. 重新阅读两个文件，并检查差异，确认没有无关改动。
4. 如果有 Python 可用，运行 scripts/validate_agents_md.py。将其结构检查和审查提示视为辅助工具，而非语义质量的证明。
5. 根据仓库证据核实每条保留的断言，检查是否与嵌套指引冲突，并删除任何只是重复能力足够强的模型默认行为的内容。

如果无法保持这对文件内容一致，请报告部分完成的状态，并在安全的情况下恢复一致性。不要仅凭验证器就宣称语义审查通过。

完成条件： 两个文件相互一致，结构验证通过，语义审查未发现无依据或相互冲突的根目录规则。

6. 报告重要决定

总结检查过的证据来源、保留的关键信息、改动的文件、执行的验证，以及尚未解决的不确定性或风险。如果此前已有指令，应按重要类别说明哪些内容予以保留、改述、删除或转交给更具体的所有者，并解释原因。

只有在用户要求，或先前的指令事关安全、存在争议或复杂到难以按重要类别审查时，才提供详尽的逐行替换记录。

维护参考

维护此技能、重新核查 CLAUDE.md 导入约定或修订其上下文设计理由时，请阅读 references/source-notes.md。不要将研究历史写入生成的项目指引。

如果某项工具链约定失效，或指引与项目证据冲突，请检查已安装的工具链，以及相关的现行官方文档或可信的一手来源。证据不可用时，请标明未知；不要仅仅因为旧措辞曾经得到验证，就继续保留它。

如果某条规则已不再提供有用指引，请提出对规范技能进行修正或删除的建议，并注明受影响的段落、来源／版本或反例，以及用于确认原意仍得到保留的检查。不要擅自编辑已安装的副本或发布更改。生成的项目指引可以指向其实际权威来源，无需附加新的研究流程。