completion-gate

completion-gate

连接“我觉得能用了”和“它已完成”的关卡。

范围边界——以下事项按顺序组合，而非相互竞争：

• 判断某件事是否算完成 → 在这里。
• 如何将检查委派给子 Agent（阈值、提示词结构） → 由你自己的委派规则决定，无论它们存放在哪里。
• 提交的具体操作（暂存、机密信息扫描、提交说明措辞） → 完全由你的提交工作流技能负责。本技能只规定提交前 必须完成什么。
• 全面代码审查的具体操作（多维度检查、严重性标签、实际检查清单） → 完全由你的代码审查技能负责——本集合不附带这类技能（例如，会派生全新上下文的内置 /code-review，或仅向其提供差异内容的审查 Agent）。下方的 Code 行规定了未安装此类技能时该怎么做。
• 对跨越信任边界的代码进行安全审查 → 完全由你的安全技能负责——本集合不附带这类技能（例如，编写代码时使用 security-and-hardening；每次代码变更后对待处理差异执行内置的 /security-review；变更跨越信任边界时进行有针对性的 security-audit，并在首次部署到生产环境前进行完整审计）。 下方的安全行规定了未安装此类技能时该怎么做。
• 更深入的维护者交接检查（补充 ADR，核对 README/CONTEXT.md 是否符合实际情况，记录生产环境事实和部署路径） → 由 handover 技能负责。仅在通过本关卡后运行，不得用它代替本关卡；收尾步骤 6 会运行该技能。

核心规则

1. [绝不违反] 你可以运行检查；但不能由你自己决定自己的工作是否通过。 将两者分开：

   • 确定性的机械检查 —— 测试套件的退出代码、差异、代码检查工具、构建结果、脚本输出。由你自己运行。结果不取决于你的判断，而交给子 Agent 通常只会导致检查出错（工作目录错误、缺少环境）。
   • 任何需要判断的事项 —— “这份文档是否清晰？”、“这个设计是否成立？”、“这个测试是否真的在测试正确的东西？”、“这个发现是否属实？”——交给未获知你推理过程的全新上下文：只提供产物和验收标准，绝不提供你对工作的辩护。读过你论证的审查者，审查的是你的论证。你自己在这里给出的答案价值很低；你已经相信自己是对的，这正是你那样写的原因。

   这条规则要杜绝的陷阱是：运行测试套件，看到结果全绿，就认定任务完成了。全绿只表示你选定的断言通过了。它们是否是正确的断言，需要判断，因此不该由你来决定。某项变更需要多少独立判断，应与其风险成正比——下方的 Code 行会划定界限。这条规则规定的是由谁设定标准，而不是每项变更需要多少审查：你不能暗中降低自己工作的标准。这种比例原则只适用于代码。Docs 行和收尾时的回读没有规模豁免——即使只改了规则文件中的一行，也仍须回读，因为这里的失误不会显现。

2. [绝不违反] 对于破坏性操作、信任边界决策或无人值守自动化，不能在下方的判断检查运行之前，就在是非确认问题中推荐其中一个答案。 起草问题之前就要检查产物类型表，而不是等用户提出异议后再检查。如果变更属于必须审慎判断的事项，先获取独立的第二意见，然后再问“已审查，可以提交了吗？”——绝不能问“提交这个？（推荐）”。 ⚠️ 曾独立观察到两次：模型将有风险的变更提议为已完成、待批准，而审查之所以发生，只是因为用户提出了异议，并非模型主动提出。

3. [绝不违反] 描述结果的完成措辞不得早于该结果出现。 已运行 / 通过 / 已验证 / 已确认 / 已通过——当作关于你自己交付物的声明使用时，绝不能在相应检查实际返回结果之前写入文件或消息。先写**“待验证”**，等有了实际输出再填写。 不存在“马上就会运行”这种例外：过早写下这些话，就会留下读者会相信的事实；即使检查后来通过，这些话在那之前仍然是错误的。 （本规则约束的是声明。它不涉及包含这些词的普通内容——测试夹具、报告模板、assert status == "PASS"，或转述他人已验证的内容。）

4. 开始之前先说明验证方法。 如果你无法在动手之前写下“这是证明它有效的命令或观察结果”，说明你还不理解任务。先去收集信息，不要开始操作。

按产物类型划分的验证标准

工件	有效的验证方式
代码	运行测试或亲自实际执行代码。仅仅编译不算。然后，如果测试是新写的，或更改涉及下方判断性问题一行中的任何内容，就交给在全新上下文中运行的代码审查（见范围边界）——同一上下文中的审查清单是编写辅助工具，不是这项检查：那等于给自己的工作打分（核心规则 1）；如果没有安装任何此类工具，至少让一个全新上下文判断这些测试是否覆盖了任务的实际要求。修正拼写错误无需审查；新模块的首套测试则需要。⚠️ 对抗性第二意见属于判断性问题一行的检查，不是这一项；而且它只审查你交给它的范围。观察到的情况：某个类经历了十五轮对抗性审查，却被当作对 14 个文件的差异进行代码审查；随后，对同一差异进行的全新上下文审查在五分钟内，就发现了该类之外的两条实际崩溃路径。
跨越信任边界的代码安全审查	使用你的安全技能（见范围边界）。如果没有可供你自行运行的安全技能，至少必须把差异交给全新上下文，并询问它代码会从程序控制范围之外获取什么，以及这可能导致代码执行什么操作或暴露什么内容。这只是替代方案，并非审查：将其输出粘贴到交付消息第 2 部分下，不要称其为安全审查或审查通过；并在第 3 部分将安全审查列为未完成。如果也没有全新上下文，就按下方的降级处理，并注明未执行安全审查这道关卡。代码一行仅规定测试和代码审查的分流；它本身不作任何安全判断。
文档、规则、配置	将文件交给全新上下文，让它仅依据该文件回答问题——而且问题必须针对你更改涉及的段落，否则这道关卡就是走过场。回答错误说明文件有问题，而不是读者有问题。如果更改是将个人信息（PII：姓名、地址、家庭或工作地点坐标）替换为占位符，则必须问一个固定问题：文件、文件头或变更日志中，是否有任何内容表明该值是真实的或已被替换？ 如果答案为是，就是一项发现——占位符不会说明其来源。用于此项的机械扫描在你的提交工作流技能中，不在这里。
困难的判断性问题（架构权衡、隐蔽的 Bug、信任边界设计、数据迁移、技术选型）	获取独立的对抗性第二意见。如果意见不一致，就分析分歧——不要挑选自己原本更认同的答案。
破坏性或不可逆操作	不在此技能范围内。 操作前确认影响范围，操作后核对实际影响，并遵循你所执行的任何高风险流程。只有当该操作同时属于困难的判断性问题，或你无法确定是否属于时，才额外进行对抗性审查。

如果某种工件类型有自己的编写标准——例如你的 Python 标准、技能编写技能、API 设计技能、测试的 TDD 技能（例如 test-driven-development），或同一上下文中的审查清单（例如 code-review-and-quality）——这些标准的规则就属于本表对此类工件的验证内容，而不是除此之外的另一项检查。逐条依据这些规则判断差异。所有读者都会得出相同结论的规则（缺少类型提示、要求使用日志记录却用了 print）由你自行处理；有能力的读者可能意见不一的规则（此测试是否覆盖了正确内容、抽象是否恰当）属于判断性问题，无论你认为它们的结论如何；任何你无法自信分类的规则也一样。如果声称某个文件没有此类标准，或其标准已运行且此后工作未变，这和其他情况一样都算一项发现：说明你查阅了哪些地方。如果任何地方都未安装此类标准，该类型对应的一行已经说明该怎么做。 选择真正胜任的最便宜审查者——让便宜的模型机械地通读一遍，也胜过让昂贵的模型什么都不做。你可以节省验证的单价，但绝不能省掉验证本身。

没有子 Agent 时

有些环境根本无法启动 Agent；有些运行还处于非交互模式（CI、无头环境、定时运行），没有人可以授权例外。这两种情况都不能让你自行认证。

无论其他条件如何、是否具备其他能力：尽可能亲自运行所有确定性的机械检查。这部分始终不取决于是否有审查者。

然后寻找独立判断：

1. 人类就是一个全新的上下文。 如果有人在场，就把产物和验收标准交给他们，询问你原本会向审查者提出什么问题——或者申请一次性豁免，并记录你已获批准。“没有子 Agent”不等于“没有独立读者”，混淆二者会让交互式会话自我说服，进而自行认证。
2. 只有在确实无人可问时——才降级：将输出标记为**“未经验证的草稿”**，并准确说明哪个判断级关卡未执行，以及原因。 如果其他规则要求“询问用户”，但此时没有用户，就采取同样的处理方式，而不是假装问题已经得到回答后继续操作。

降级交付是诚实的，但仍不算通过。

交付消息：三个必备部分

1. 完成了什么——用读者能理解的方式说明改动。
2. 如何验证，以及原始结果——粘贴实际输出。结果摘要不等于结果本身。
3. 未完成什么——跳过的步骤、未经验证的部分、已知缺口、任何延期事项。即使没人询问，也要说明。

失败计数（针对你亲自执行的工作）

以下情况算作失败：验证未通过、违反验收标准、同一工具错误再次出现，或用户纠正了你。

尝试次数	允许执行的操作
第 1 次	原样记录确切的错误文本。找出与预期相比唯一的差异。只更改一个变量，然后重试。
第 2 次	停止尝试不同变体。写下你尝试过的操作和证据。改用其他方法，或升级到更强大的模型。
第 3 次	现在禁止再走同一条路线。选择其一：回滚、从头重新规划，或将失败记录交给用户（没有用户 → 按上述方式降级）。

⚠️ 连续两次出现“我改了，但没有任何变化”，说明你编辑的并不是实际运行的内容。 第三次编辑前，先证明代码路径确实正在执行。这一问题在实践中已被反复记录，并非理论上的担忧：这是代价最高、最容易陷入的循环，而且身处其中时总会觉得只是运气不好。

会话结束收尾（按此顺序执行）

1. 首先，确认本轮产出的每一项内容——代码、文档、规则、配置——都确实通过了上表中对应的检查。 对于代码：自行运行测试；如果测试是新增的，或这次更改需要判断取舍，则进行代码审查分诊；如果涉及信任边界，则使用安全技能；如果这些都无法运行，则使用安全行的替代检查。对于文档、规则和配置：按照 Docs 行进行回读，不设篇幅豁免（Core Rule 1）。文档描述的是已验证的行为，而不是预期中的行为：在这项检查通过之前就编写文档，意味着步骤 2 记录的内容可能仍然有问题。
2. 先更新实质性文档。 检查差异，并针对仓库跟踪的每份文档询问：“这份文档是否描述了我的更改刚刚使之失效的行为或决策？” 如果是，就更新它。如果不确定，列出候选文档并询问——绝不默默跳过。不要重新转述代码中已有的内容。
3. 证明步骤 2 确实执行了。 如果编辑了任何文档，将更改后的文件和预期更改的摘要交给一位全新的读者，并询问该文件现在是否体现了这些更改。它必须回答“是”，并引用相关段落。如果做不到，就返回步骤 2 并真正完成编辑——不得继续。两次仍无法回答 → 停止并询问（没有用户可问 → 降级处理）。 这项检查的范围刻意窄于开放式回读：开放式回读询问“这份文件是否正确地说明了内容？”，这项检查只询问“编辑是否落实了？”。告诉读者你的意图会引导第一个问题，但这正是第二个问题——因此，答案必须是引用，而不能只是“是”。步骤 2 中编辑的文档，除了这项检查外，还必须通过 Docs 行的开放式回读；请在步骤 4 前执行。 ⚠️ 没有这项检查，步骤 2 就会沦为声称已更新、实际却从未更新——这是实践中观察到的情况，并非假设。
4. 明确说明是否还需要进行上述判断取舍行中的对抗性第二意见，或者对故障模式为静默失效的规则/配置文件进行第二意见检查。 每次步骤 3 完成时，无论检查通过还是需要升级处理，都要说明建议——执行还是跳过——并给出理由。是否执行可按风险酌情决定；跳过是需要记录的选择，不能默默成为默认做法。无论如何，步骤 5–6 都照常进行——此步骤只阻止一件事：在你决定执行的第二意见尚未返回之前，不得声称这次更改“已验证 / PASS”。
5. 然后更新仓库的后续事项列表：新会话会通过它了解接下来要做什么的那份优先级列表。首先，逐文件列出整个会话更改的内容，不要凭记忆回想： git status --short（新建的跟踪器工单通常会显示为未跟踪）， git diff --stat <last commit before this session>..HEAD，以及从远程跟踪器查询本会话新建的工单。 找到该列表：查看仓库的 CLAUDE.md / AGENTS.md 将“接下来做什么”的问题指向哪里，或是否由其自身承载。没有指向位置 → 采用已有的 docs/TODO.md 或 TODO.md；有两个候选 → 询问应采用哪一个。 然后：本会话关闭的事项从列表中移除，本会话新建的事项加入列表，本会话推进的事项改写为下一步行动。没有新建、关闭或推进任何事项 → 此步骤不写入任何内容。如果本会话新建或推进了事项，但仍处于未完成状态，且任何地方都没有列表 → 创建 docs/TODO.md，并以一个不排序的条目收尾，指向仓库中其他尚未关闭的跟踪器工单（可通过其文件夹、标签或列表命令找到）。对采用或创建的列表，应在仓库已加载的 CLAUDE.md / AGENTS.md 中添加一行指向它的说明；如果两者都没有，则在交付消息第 3 部分中列出缺少指向说明的情况。 每个未完成事项各占一条，并按优先级排序。每条新增或改写的内容都应说明事项是什么、为何排在此优先级、下一项具体行动，以及应先阅读的路径。 同一功能的工单共用一条，指向其文件夹或标签。详细内容保留在各自的文档中（ADR、规范、工单、主题列表等），列表条目只需指向该文档——这也是此步骤必须安排在实际文档更新之后的原因：若先写列表，它指向的内容可能已不存在。 完成条件：本会话新建的每项内容，以及本会话新建或重新排序后仍未关闭的每张跟踪器工单，都有对应条目；本会话推进的每项内容都有当前的下一步行动；本会话关闭的每项内容都已从列表中移除；列表顺序与优先级一致；列表及新增的任何指向说明都通过了 Docs 行的回读。 ⚠️ 此步骤的检查范围与步骤 2 不同：步骤 2 询问“本轮差异是否使文档失效”，步骤 5 询问“整个会话累积的工作是否偏离后续事项列表”。本轮无需在步骤 2 更新内容，并不意味着可以跳过步骤 5——实践中，跨步骤复用步骤 2 的结论导致后续事项列表过时。
6. 然后自行运行 handover，每次都要运行，不要询问用户。它的步骤 1 会判断是否有待交接事项：候选列表为空时，应以回复中的一行 handover-skip: <reason> 结束。 完成条件：在起草任何提交之前，回复中已包含 handover 的报告或该跳过说明。 ⚠️ 实践中曾观察到，当此步骤仍需询问用户时，完成步骤 5 后会不假思索地直接开始提交，从而完全漏掉提问——这正是上述完成条件要求在回复中包含报告或跳过说明的原因。