添加约定

添加一条约定——但只有在评估它是否应该存在以及属于哪里之后。此技能是一个守护者，也是一个路由器，而不是一个记录员。

步骤 0 — 前置条件和上下文

确认仓库已初始化。
完整阅读 CONVENTIONS.md 和 AGENTS.md，以便检测与现有规则的重叠并判断适配性。

步骤 0.5 — 评估（先运行）

运行共享的评估协议；分类（步骤 1）和路由（步骤 2）的问题在此之下提出：

首先复用已提供的答案。 将请求或本次会话中已提供的适用选择（包括深度）视为已回答。对它们进行总结，不要再次询问；默认值永远不会取代明确的选择。如果每个关键选择都已提供，则继续。仅询问缺失或冲突的关键选择。仅凭仓库偏好不是当前答案或执行授权。
未解决选择项的深度选择器。 如果未提供深度且仍有选择余地，请询问本次评估应深入到什么程度：快速 — 每个选择都采用其推荐的默认值；仅询问没有可推导默认值（自由文本要点）的问题；引导 — 仅询问以下标记为高影响力的问题，加上自由文本要点；完整 — 以下每个问题。如果仓库的 CONVENTIONS.md 记录了 Assessment depth:，请在询问时将其预选为推荐选项；记录在案的深度绝不会被静默应用。否则，当请求在几乎没有上下文的情况下到达时，推荐完整，当请求已完全指定时，推荐快速。在任何一个问题下，操作员可以回答“从这里开始使用默认值”或“更深入”；立即响应此切换。
一次只问一个问题，每个问题附带一个推荐选项和一行理由；等待每个答案。
使用结构化选择（单选或多选）。如果主机支持结构化的单选/多选问题工具，请使用它并标记推荐选项；否则，以纯文本形式列出选项 A/B/C 并命名推荐选项。仅在无法使用可枚举集合（例如确切的措辞）时使用自由文本。
操作员决定。 在未得到答案之前绝不继续下一个问题，并且在未提供上下文时绝不猜测范围。

问题（跳过请求中已回答的）：

值得编录吗？ — 是（重复出现的、稳定的、可测试的）或否（一次性的、重复的、易变的、模糊的）。推荐：根据步骤 1 的分类；此问题决定后续流程。 (高影响力 — 在引导模式下询问。)
归属地 — AGENTS.md 硬规则 / CONVENTIONS.md 指南 / GLOSSARY.md 术语 / 实际上是一个决策（移交至 new-adr 技能）。推荐：根据规则的性质（参见步骤 2）。 (高影响力 — 在引导模式下询问：错误的归属地意味着移动的麻烦。)
在验证关卡中强制执行？ — 是 / 否。推荐：否，除非该规则是可机械检查的。
措辞 — 自由文本（规则陈述本身；在任何深度下都会询问）。

步骤 1 — 评估：这值得编录吗？

应用分类。在以下情况下，推荐不添加：

已存在约定（显式或隐式）覆盖了它——应指向该约定，而不是重复添加。
这是一次性决策，而不是重复出现的决策——将其编录会增加噪音。
它很可能会变动——不成熟的规则会变成过时的累赘。
它过于模糊，无法按原样进行测试或操作。

在以下情况下，推荐添加：它是一个重复出现的决策，其模糊性会导致返工，它很稳定，并且可以表述为一个无需进一步解释的智能体即可遵循的规则。在执行任何操作之前，请说明您的建议和理由。

步骤 2 — 路由：它属于哪里？

决定归属地，并解释选择：

智能体必须遵守的硬规则 → 添加到 AGENTS.md 的 §Hard rules 部分的一个条目，具体内容放入 CONVENTIONS.md。适用于不可协商的约束。
编写/流程指南 → CONVENTIONS.md 中的一个章节。适用于“我们做事的方式”，提供信息但不作为关卡。
共享术语/定义 → GLOSSARY.md（如果不存在则创建——添加第一个术语即可启用词汇表层；将其放置在记录的制品根目录下）。阅读仓库的 CONVENTIONS.md 中的 §Glossary 并检查其实际声明的规则；规范结构是一个可选的 H1 标题和可选的介绍性散文，然后恰好一个两列的 Markdown 表格，其表头为 Term | Definition。每个术语占一行。切勿将术语记录为标题、项目符号或段落，也切勿添加第二个表格或不同的列形。一个声明旧版或不相关词汇表约定的 §Glossary 并不是采用此表格：请使用规范形状，并提供审核技能的单独同意的规则和文件迁移，而不是复制旧形状。缺失 GLOSSARY.md 仍是一种有效状态；此技能仅因实际添加了一个术语才创建它。
它实际上是一个决策，而不是一个约定（架构、产品或技术选择，带有替代方案和后果）→ 这是一个 ADR。停止并提供 new-adr 技能；不要将一个决策埋藏在 CONVENTIONS 中。

如果某个约定是分类/流程规则（例如，如何处理新进来的工作），则优先放在 CONVENTIONS.md 中，只有在不可协商的部分才在 AGENTS.md 中添加硬规则条目。

步骤 3 — 起草并确认

为其所属文件起草确切的措辞。保持简洁、可测试，并使用仓库的语言。显示差异对比（diff）。在写入之前确认。

步骤 4 — 写入并提交

应用编辑。如果某个约定升级为硬规则，请确保 AGENTS.md 和 CONVENTIONS.md 保持一致。使用约定式提交（docs: ...）；如果未涉及 ADR，则无需 Rationale: 页脚，但如果仓库的约定要求在约定更改时添加，则添加一个。

添加或扩展词汇表。 使用下面定义的规范结构和声明的规则检查；每次运行之间的形状不得发生偏移。

规则的来源。 如果 CONVENTIONS.md 没有 §Glossary 部分（早于此规则的旧仓库，或在规则被记录之前启用的层），则回退到上述产品默认的规范形状：可选的 # Glossary 标题和介绍性散文，然后一个 Term | Definition 表格。不要为该仓库发明不同的形状，也不要静默编辑不相关的约定。
读取声明的规则。 当 §Glossary 存在时，读取它实际声明的内容。如果它描述了规范的 Term | Definition 两列表格，则遵循它，并且仅在显式请求时才更改它。如果它声明了不同的或旧的词汇表约定（项目符号、散文、另一种列形），则该仓库尚未采用此表格：不要复制旧形状，也不要静默重写规则。使用规范形状添加术语，并提供审核技能的迁移，该迁移将规则和文件一起作为一个单独同意的差异对比（diff）处理。
记录约定。 当 §Glossary 缺失时，提供——作为其自身已确认的编辑，独立于要添加的术语——在 CONVENTIONS.md 中记录一个 ## Glossary 部分，说明实际使用的形状。显示该差异对比（diff）并且仅当用户接受时才写入；切勿重写或重新排序 CONVENTIONS.md 的其他部分以腾出空间，如果用户拒绝，则保持词汇表规范但 CONVENTIONS.md 保持不变。
创建文件。 写入可选的 # Glossary 标题和仓库所需的任何简短介绍性散文，然后写入单个的两列表格，表头为 Term | Definition，并将新术语作为其第一行。不要发明占位符术语。
扩展现有文件。 逐字节保留标题、介绍性散文、条目顺序和每个现有行。将新术语作为一行追加；切勿重建、重新排序或重新格式化文件，也切勿引入第二个表格。
锚点。 如果新术语的行可以通过传入链接已使用的标题锚点访问，则将该锚点保留在该行上，而不是删除目标；如果无法保留锚点，则停止并标记，而不是猜测。
保留含义。 保持术语的拼写、别名、链接和内联代码与提供时的完全一致。将字面管道符转义为 \|。如果定义确实跨多行，则将其保留在一个单元格中，使用 <br> 进行硬换行，而不是溢出到额外的行中。
重复项和歧义。 如果术语已存在，则显示现有定义和提议的定义，并询问是更新还是保留现有行。切勿静默合并、替换或为相同术语添加第二行，也切勿猜测定义。
非规范文件。 如果现有的 GLOSSARY.md 是项目符号、散文、标题或混合形状，则不要追加竞争行，也不要将重写文件作为添加术语的副作用。暴露非规范结构并提供审核技能的同意迁移；仅当用户接受具体的差异对比（diff）时才应用它。被拒绝的迁移会保留用户保留的文件。

命名执行的规则和传播；列出未更新的仓库。

结项报告

每次运行结束时，包括被阻止、失败和停止的运行，都应以标题为 状态概览 的部分结束，该部分包含以下三个标签：

本次运行： 仅列出实际尝试过的操作及其结果；引用每个验证关卡的确切输出和退出代码，包括超时或中断。
总体： 已实现、部分已验证、已验证、被阻止、失败或未知。通过子步骤并不代表总体通过；不完整或缺失的证据永远不会变成成功。
剩余工作： 每个剩余的操作、未解决的发现、验证、清理或所需的输入。仅当整个任务经核实完成时，才填写“无”；切勿因为预算耗尽而遗漏工作。

EvolveHQ/docflow

docflow 是什么？

在你喜欢的 AI 中提问

文档