编写代码、构建功能、修复缺陷或重构时…

适用于任何需要实现或修改代码，并将实现、验证、提交和交接保持在可证据化范围内的开发任务。

适用场景

解决思路

1. 交付所请求的行为，并用代码路径及其输出被消费的位置的证据来支撑。
2. 为变更选择最小有用的反馈循环；当不确定性、集成范围或后果增加时，提高验证程度。
3. 用户指令优先于本技能指南；延续已有授权并在范围内完成工作。
4. 对日常可逆选择，如有用，用明确假设直接解决。
5. 仅当缺失信息会实质改变结果，或适用边界要求时再询问；技能工作流本身不创建新的审批门槛。
6. 编辑前检查仓库状态，并阅读被触及文件上已有的 diff。
7. 将 checkout 视为共享空间；保留非自己创建的工作，并尊重已声明所有权。
8. 沿实际调用者和消费者追踪行为。
9. 定位最近的相关模式、测试和真实 gate 命令。
10. 当问题涉及代码结构时按语法搜索；对名称和散文用文本搜索。
11. 阅读到足以理解变更为止；不要设定最少文件阅读数，也不要倾倒大范围上下文。
12. 通过已配置的记忆工作流回忆不显然的既有决策。
13. 对易变的 API、依赖和部署声明，用当前一手证据或已安装版本重新核对。
14. 当任务需要时加载专门工具指南，而不是猜测不熟悉的 flags。
15. 区分诊断与实现；「为什么发生？」先要求确认原因。
16. 修复获得授权后，定义一个能区分故障行为与预期行为的检查。
17. 清晰、低影响编辑：进行编辑，并使用相关结构或行为检查。
18. 有可观察失败的 bug：复现它，隔离原因，然后验证修正。
19. 跨边界的新行为：实现一个有代表性的端到端切片及其测试。
20. 共享接口或 schema 变更：在改契约前追踪消费者和兼容性。
21. 大型不确定变更：使用 `plan` 处理依赖和验收标准。
22. 有有用集成路径的独立工作：使用已授权委派并明确所有权。
23. 保持实现与其验证在一起。
24. 当更早的测试能指导设计时，不要把所有测试推迟到功能完成后。
25. 不要仅为满足仪式，为可逆文本编辑创建测试。
26. 在连贯的行为或契约边界处拆分工作；文件数和编辑次数不是通用的节奏规则。
27. 在更多工作建立在可能是错误的前提上之前，运行能暴露下一个可能失败的最便宜检查。
28. 遵循局部模式，除非有具体问题证明偏离合理；解释原因，而不是泛泛偏好另一种风格。
29. 新模式或配置出现时，把每个都绑定到请求的行为或已证明的变化。
30. 同一决策在多个调用者中重复时，给该决策一个合适的负责人。
31. wrapper 只转发调用时，在移除前检查它是否强制 API、策略或测试边界。
32. cast 隐藏不兼容数据时，在实际边界修复或验证契约。
33. fallback 隐藏错误时，保留失败原因并显式处理预期恢复。
34. 兼容代码增长时，在保留或删除前检查已发布消费者和 rollout 要求。
35. 复杂度持续增加时，在添加另一个特殊情况前重新检查所有权和数据流。
36. 当抽象强制真实边界时，它可以在第二个调用者之前就有价值；当更短实现掩盖错误行为或兼容性时，它可能更差；判断概念和契约，而不只看行数。
37. 将编辑保持在请求范围内；移除自己的变更产生的 imports、过时 labels 和 dead branches。
38. 需要时把无关发现路由到项目的 sidequest 或 issue 工作流；不要静默吸收进实现。
39. 出现规模问题时，识别争用资源；在根源修复隔离、索引、批处理、所有权或容量。
40. 临时降低并发可帮助受控诊断或已授权事件缓解；它不得悄悄变成永久方案。
41. 从实际仓库和受影响行为中选择检查：类型/静态分析能确定选定的类型和结构属性，但不执行运行时行为。
42. 聚焦行为测试能证明预期用例走过变更路径，但 mocks 可能绕过集成。
43. 包或集成检查能证明受影响组件之间的契约成立，但可能遗漏打包或部署差异。
44. 构建/打包验证能证明产物可被生产，但不证明它能被安装或使用。
45. 消费者检查能证明产物服务预期消费者，但受限于所观察环境和用例。
46. 内循环使用有范围的检查，并在相关 commit 或交付边界前运行所需的仓库 gates。
47. 当共享依赖、失败或残余风险证明合理时，扩大测试。
48. 一旦适当检查通过，继续到完成，而不是反复运行无关套件。
49. 保留命令退出码和原始失败日志；管道到 `tail` 可能隐藏失败命令，除非处理管道状态。
50. 在捕获后总结冗长日志。
51. 不要强加任意超时，也不要跨其他 agents 的工作运行 autofix。
52. 在依赖过滤运行前，先发现实际测试框架的选择语义。
53. 有用的 receipt 要写明命令、修订版或工作树状态、相关环境、退出状态，以及实际运行了什么。
54. 过滤后选中零个预期测试，不能验证变更。
55. 输入匹配时缓存结果可以是合法的；要披露它们，而不是描述为新鲜执行。
56. 仅凭 wall-clock 时长既不能证明工作，也不能证明 gate 有缺陷。
57. 在消费边界检查：生成的配置要检查组合输出中的目标不变量。
58. 包要安装并调用构建出的 distribution，且不依赖未声明的同级依赖。
59. UI 要在真实界面中演练变更后的交互，可用时使用 `agent-browser`。
60. CLI 要调用相关命令，包括受影响的错误/默认路径。
61. 数据库迁移要应用到有代表性的 schema/data，并检查兼容性或回滚要求。
62. 服务要确认正在运行的 revision，并演练变更后的请求路径。
63. 检查不变量，而不仅是「命令成功」；语法有效的 selector 可能匹配不到，包可能构建成功却漏掉 importer 需要的文件，合并后的修复可能让部署产物未变。
64. 生产 apply 或其他有外部后果的检查仍需要适用授权；完成所有可得本地证据，并报告剩余限制，不要暗示 live check 已通过。
65. 新 detectors 和 guards 需要正反证据：诱发它们应捕获的失败，并验证正常行为仍被接受。
66. 性能变更需要基线、有代表性的工作负载和相关资源测量。
67. 对无法观察的表面，给人类一个可区分问题的程序和预期结果；不要编造截图或硬件结论。
68. 再次编辑前先分类失败：环境故障、陈旧产物、调用错误、共享输出竞争和运行时缺陷需要不同响应。
69. 保留原始错误，并识别第一个失败依赖，而不是修复每个下游症状。
70. 当修复失败时，说明结果推翻了什么，并选择能区分剩余解释的检查。
71. 没有新证据地重复变体，无论尝试次数多少，都是重述问题的信号。
72. 避免用相邻重构替代诊断。
73. base 上的失败可以表明症状早于变更；trace 中缺少变更文件名则不能。
74. 成功重跑不能确立无害的 flakiness。
75. 在归因失败前，比较相同命令、输入、revision 和环境。
76. CI 和事件处理的详细流程见 `references/recovery.md`。
77. 遵循项目的 commit 政策。
78. 在期望 atomic commits 时，提交已验证的逻辑块，而不是累积无关工作。
79. 让行为变更与理解它所需的测试在一起。
80. 当机械移动能让 review 更清晰并保留有效中间状态时，单独拆分它们。
81. staging 前检查 status 和 diff。
82. 暂存明确的自己拥有的路径或 hunks，检查已暂存 patch，避免包含他人的 index 变更。
83. 遵循当前项目消息和归属规则；用 `git` 处理共享 index、worktrees、rebases 或冲突恢复。
84. push、merge、release 权限来自用户和项目契约，而不是本技能。
85. 在 commit 或集成检查点，将总 diff 与任务比较；绿色测试可能与不必要的范围共存。
86. review 发现需要已证明的机制和影响；把 blockers 与可选改进分类，而不是把每个建议当作新需求。
87. 非平凡变更在项目要求时获取独立对抗性验证；有重大风险且合理时也应如此。
88. 可用且适用时使用 `cross-model-review`；不同模型能暴露盲点，但不能消除相关错误。
89. 用证据验证中心发现，并把结论绑定到被 review 的状态。
90. 将未完成的 review 报告为未完成。
91. 在 handoff 或 compaction 时，保留原始结果、用户修正、变更路径、revision、已运行检查、未解决问题和下一步。
92. 恢复时在继续前重新检查当前状态；另一个 agent 可能已改变工作树。
93. 当能防止重新发现时，把持久原因和修复记录到已配置记忆。
94. 报告改了什么、为什么、什么证明它，以及任何重要的未验证边界。
95. 继续已授权的必要工作，直到该结果被处理。
96. 注意 Astra guidance 指出的风险：小任务过度测试，以及冲突指令造成不必要阻塞；用比例化检查和用户优先来应对。
97. 评估工作流有效性或解读 benchmark 声明时，阅读 `references/benchmarks.md`。
98. 处理 CI triage、间歇性失败和事件恢复时，阅读 `references/recovery.md`。
99. 不要把这些 references 当作通用编辑比例或模型无关性能保证。
100. 不要在任意编辑次数后才验证；应在依赖新的不确定契约前验证。
101. 不要为小变更运行每个套件；运行必需且相关的 gates，并基于证据扩展。
102. 不要接受没有覆盖说明的绿色徽章；检查实际运行了什么以及它支撑什么断言。
103. 不要因空 grep 就称问题为既有问题；比较受控执行并追踪因果。
104. 不要因为兼容代码看起来旧就删除它；检查消费者和 rollout 义务。
105. 不要为每个日常选择请求许可；延续已有授权执行。
106. 不要把 reviewer 批准当作消费者证明；在输出被使用的地方测试变更行为。

适用边界 · 注意事项

• 不要把它当作固定顺序、编辑预算、强制研究阶段或 agent 配额。
• 不要借此修改相邻代码、绕过审批或声称未运行的检查已通过。
• 不要用它替代对实际实现及其消费者的理解。