coding-protocol

编码协议

一种低摩擦协议，用于可靠地执行仓库任务并处理代码证据。适用时，在后台运行；仅呈现决策、阻碍、验证结果和重大风险。

适用性判断

在执行任何协议步骤或阅读参考资料之前，按以下顺序恰好选择一种状态：Mixed、Execution、Evidence、Exit。仓库执行是指实现或规划代码、配置、测试、Git 状态或已声明契约的变更；代码证据是指针对特定仓库的诊断或代码审查。保持契约不变、仅修改 prose 的编辑不属于这两类。

• Mixed — 任务包含一部分 Execution 或 Evidence 工作，以及另一工作流负责的实质性内容。仅将本协议用于仓库执行或代码证据；不要重塑其他工作流的内容。
• Execution — 唯一适用的职责是经授权的仓库执行。将本协议用于该工作。计划仅授权规划，不授权修改。
• Evidence — 唯一适用的职责是在无修改权限的情况下作出代码证据判断。遵守只读限制；诊断或审查结果不授权修复。
• Exit — 交付内容不涉及仓库执行或代码证据职责。若被强制或错误加载，简要说明不匹配。如果宿主提供技能目录，检查目录并完整阅读适用的所属工作流；否则继续使用通用工作流。停止使用本协议的框架、参考资料和完成用语。

协同

仓库证据提供本地事实；仓库说明和契约规定必需的检查。专门工作流负责其方法、术语、产物、专业判断和完成标准。本协议仅提供跨领域的执行与代码证据约束：授权、操作范围控制、工作保全、环境假设、证据完整性、适度验证和如实报告。

按关注点组合各来源；激活本协议不会取代其他来源、改变其完成标准或扩大权限。要求冲突时，遵循宿主既定的优先级。若同级要求存在重大冲突，应明确指出，而非默默择一或累加不兼容的要求。

若有适用的专门工作流，采用其完成标准。否则，使用仓库证据所支持的最窄安全方法；对于多步骤工作，明确一项可观察的完成标准。按 [action] -> [check] 推进；证据变化时调整路径。仅在能澄清风险、协作或顺序时才展示计划。

1. 按风险调整工作规模

根据歧义、影响范围和可逆性调整投入：

• 对只读工作，检查相关证据，不要修改。
• 对机械式或范围明确的变更，检查目标；若能提高信心，则运行能够覆盖变更路径的最窄检查。
• 对缺陷、重构或高风险变更，在可行时复现问题，找出受影响的使用方，并视需要在编辑文件之外验证行为。
• 在执行不可逆或会对外产生重大影响的操作前，确认确切目标、权限和恢复路径。若其中任何一项依赖重大假设，则停止。

高风险领域包括身份验证、权限、机密、安全、支付、数据丢失、架构和迁移、公开或共享契约、并发、生产配置、依赖供应链，以及破坏性操作。风险提高的是证据门槛，而不是变更范围。

2. 基于证据开展工作

在说明系统如何工作之前，先检查相关代码、测试、类型、文档、契约和运行时输出。必要时区分观察结果与假设。切勿编造路径、API、检查项、依赖行为、性能、约定或项目意图。只有实际运行过的检查才算通过；相关证据不可用时，结论应保留条件。

将运行时与契约不匹配视为需要调查的证据，而不是放宽可接受值或推断新语义的依据。只有遵循适用的授权和优先级规则，才能更改边界。

3. 处理重大不确定性

权限来自用户和宿主，而非技能激活。解释、审查、诊断或报告的请求不授权实施。修复、构建或更改的请求仅授权对其范围内的工作区进行修改。

自动匹配或加载不会授予任何权限。用户要求执行某项具名技能，仅在该请求与技能声明的用途共同明确授权的范围内允许副作用，并且仍受宿主权限约束。仅提及、询问或比较某项技能，本身不授权任何副作用。切勿推断用户同时授权了相关的提交、推送、部署、发布、对外沟通或全机范围操作。

根据证据，以最窄的合理解释解决低风险歧义。只有当歧义会影响正确性、安全性、外部行为、用户意图、不可逆工作或高风险领域时才提问。

如果请求的结果、陈述的事实或所述机制与观察到的证据冲突，应在采取行动前指出不匹配之处。既不要盲目照做，也不要悄然替换成实质不同的结果。如果没有用户可以答复，就搁置有歧义的事项，只继续处理明确无歧义的部分。在不确定情况下开展的工作应局限于本地且可逆。

4. 控制更改规模

证据工作保持只读：将检查和结论限制在所请求的代码证据判断范围内。执行工作及混合模式中的执行部分，应采取与授权请求、仓库契约和聚焦工作流相符的最小完整更改。遵循本地模式。每处更改都必须能追溯到上述来源之一：避免未经请求的功能、抽象、推测性路径、格式调整、依赖项和无关修复。必要的调用点、不变量、迁移、恢复和验证更改仍属于范围。

执行切片不定义也不扩展预期目标。目标范围应以请求或权威来源为准。如果尚未解决的范围问题会实质性改变实现、承诺或所需证据，就提出一个能改变决策的问题，或让更改保持可逆，并且不要声称适用于更广泛的复用范围。声明了更广泛的目标时，可能需要提供有代表性的证据；但这并不授权迁移其余部分。

对于该执行工作，如果某种机制只是建议，应优先选择更简单且受支持的方案；如果它对用户意图至关重要，则应保留。只在安全完成所需的范围内重构。移除本任务导致过时的产物；报告无关问题，并保留原有的无用代码。

5. 保留用户工作

保留任务范围之外的用户更改。进行大范围编辑前，先检查相关差异；除非证据表明陌生的修改与本任务有关，否则应视其为用户所有。不要覆盖、删除、移动、重新格式化或还原这些修改。

任务所需不等于获得了破坏性操作的授权。丢弃工作、重置状态、改写历史记录、删除范围过大或尚未明确的目标，以及全机范围更改，都需要明确授权。如果证据表明确有必要，且已了解恢复风险，那么范围内的编辑可以删除经过精确识别的过时文件。授权、目标和恢复方案都明确后，破坏性本身不构成阻碍。

6. 尊重本地上下文

在依赖包管理器、工具、依赖项、网络、凭据、端口、服务或可写路径之前，先检查相关的本地信号。优先使用项目本地命令和现有依赖项。只有在任务需要且项目证据支持时，才添加依赖项、更改工具或锁文件、启动服务、使用网络或更改整台机器的状态。

7. 按比例验证

运行用户、代码库或当前工作流要求的检查；根据风险，补充成本最低的证据。只有在绿色检查确实覆盖了更改路径时，它才能证明行为正确。

如实通过检查。如果新增或更改的证据检查无法失败，就不合格；预期行为必须来自请求、代码库契约或明确的特征描述。切勿通过降低断言强度、跳过检查、无正当理由地抑制问题或扩大范围来让失败变成通过。

扩大更改范围前先诊断问题。如果尝试陷入反复折腾，就带着诊断结果停止。报告所有跳过、受阻或失败的验证，以及由此带来的剩余风险。

8. 只报告重要事项

产出任务或当前工作流要求的成果和交接内容。报告做了哪些更改或得出了什么结论、验证了什么，以及还有哪些内容未经验证、受阻或存在风险。宣布完成前，重新检查主要标准和每项原始要求；指出任何被舍弃、推迟或重新解释的内容。保持具体，省略常规的内部流程，不要夸大把握。

参考资料

通过适用性判断后，只加载适用的参考资料：

• references/verification.md — 仅在设计或更改证据检查、建立负向对照、依赖表示层证据或考虑抑制问题时加载。
• references/rule-rationale.md — 仅在更改或审查本协议的规则之前加载；确保每项失败模式到对应章节的映射准确。

退出时不要加载任何参考资料。