auto-sync: 2026-05-27 00:11:21

skills/proven-practices.md

@@ -0,0 +1,103 @@
+---
+name: proven-practices
+description: >-
+  从成功任务中提炼的最佳实践：编码模式、评审策略、调研方法、工具使用方式。
+  在开始复杂任务时触发，作为"怎么做好"的参考。
+---
+
+# Proven Practices（验证有效的最佳实践）
+
+> 来源：从三国团队 200 次成功任务中蒸馏（庞统 158 条 + 司马懿 42 条）
+
+## 适用场景
+
+- 开始复杂任务（L2/L3）时，快速回顾成功做法
+- 新将军入职参考
+- 自查当前工作是否符合最佳实践
+
+## 模式清单
+
+### 模式 1：先读后写 — 编码前通读相关代码（severity: high）
+
+**场景**：编码任务（新功能、重构、bug 修复）
+**最佳做法**：动手写代码前，先用 `read` 通读所有相关文件（包括上下游模块），确认理解完整后再动手。庞统在写设计文档前读完全部代码后说"Now I have a complete understanding of the codebase"；司马懿评审 bug 修复时先读安装目录和开发目录两份代码确认一致。
+**成功因素**：避免"改了这里忘了那里"，一次改对不需要返工。
+**关键细节**：不要只读目标文件，也读 import 它的模块和被它 import 的模块。
+
+### 模式 2：写完即验 — 产出必须运行验证（severity: high）
+
+**场景**：产出代码或脚本的编码任务
+**最佳做法**：写完代码后立即用 `exec` 运行验证，确认输出正确后再提交。庞统写 `find_max.py` 后立即运行确认 `max=9.81` 正确；写 Hello World 后确认输出 `Hello, World!`。
+**成功因素**：运行验证是最低成本的质量保证，比提交后被驳回再改快 10 倍。
+**关键细节**：验证时检查边界情况（空输入、极端值），不只是 happy path。
+
+### 模式 3：结构化评审 — 逐项检查表（severity: high）
+
+**场景**：代码评审、产出审核
+**最佳做法**：按固定评审维度逐项检查，用表格输出结论。司马懿的评审标准：功能正确性 → 边界处理 → 异常处理 → 代码风格 → 数据文件 → 运行验证。每项 ✅/❌ 明确标注。
+**成功因素**：结构化检查防止遗漏，表格格式让结论一目了然。
+**关键细节**：区分"必须修改"（Critical）和"建议"（Non-blocking），后者不阻断流程。驳回时明确说明修改方向。
+
+### 模式 4：交叉核实 — 不信任产出声明（severity: high）
+
+**场景**：审核他人的产出报告、验证他人声明的完成状态
+**最佳做法**：不直接采信报告中的声明，逐项调 API 交叉核实。司马懿审核庞统的 verify 报告时，"逐项调 API 交叉核实——项目状态、父子关系、状态流转、Stages结构、产出文件、审查记录——全部与实际数据一致，无虚假声明"。
+**成功因素**：审核的核心价值就是"不信声明信证据"，避免虚假完成蒙混过关。
+**关键细节**：核实范围包括状态一致性、数据准确性、产出完整性，不只是"有没有"还要"对不对"。
+
+### 模式 5：状态机敬畏 — 先查状态再操作（severity: high）
+
+**场景**：黑板任务流转、状态机相关操作
+**最佳做法**：操作前先查当前状态，根据状态决定下一步操作，不假设状态。庞统遇到 `review` 状态无法转 `working`，立即调整为直接在 review 下完成操作；发现任务已是 `done` 则不再重复操作。
+**成功因素**：状态机是硬约束，违反它只会浪费 API 调用。先查状态再操作，一次做对。
+**关键细节**：遇到非法转换不要硬试，理解状态机规则后选择合法路径。
+
+### 模式 6：调研深挖 — 搜索 + 原文 + 结构化输出（severity: medium）
+
+**场景**：技术调研、竞品分析、方案研究
+**最佳做法**：`web_search` 获取概览 → `web_fetch` 深挖关键文章 → 结构化报告输出。庞统做 AI Agent 架构调研时搜索了多框架对比，尝试 fetch 原文（即使被阻止也用搜索结果补充），最终输出带章节的调研报告。
+**成功因素**：搜索提供广度，fetch 提供深度，结构化输出让调研结果可被团队消费。
+**关键细节**：即使部分 fetch 失败，也不要卡住——用已有信息组织报告，注明数据来源。
+
+### 模式 7：简洁产出 — 最小化交付物（severity: medium）
+
+**场景**：所有任务的产出编写
+**最佳做法**：产出只包含任务要求的内容，不做额外扩展。庞统的 `hello_world.py` 只有一行 `print("Hello, World!")`，不加大框架；`find_max.py` 只做手动遍历找最大值，不实现排序。
+**成功因素**：简洁 = 少 bug = 快通过评审。不必要的抽象和功能只会增加评审负担和出错概率。
+**关键细节**：产出报告用表格列出文件和说明，让审核者快速定位。
+
+### 模式 8：续杯幂等 — 被中断后先查再续（severity: medium）
+
+**场景**：任务被中断后恢复（续杯提醒）
+**最佳做法**：收到续杯提醒后，先查任务当前状态和已有产出，判断是否已完成或需要继续。司马懿收到续杯后检查发现"任务已是 review 状态，产出已写入，上轮评审已完成，无需重复操作"。
+**成功因素**：幂等性保证——即使多次续杯也不会重复执行或破坏已有结果。
+**关键细节**：续杯不是重新开始，是"检查 → 继续/跳过"。已完成的工作不要重做。
+
+### 模式 9：计划驱动 — 复杂任务用 update_plan 跟踪（severity: medium）
+
+**场景**：超过 15 步的复杂任务（调研、多文件编码、集成测试）
+**最佳做法**：用 `update_plan` 拆分步骤，每完成一步更新状态。庞统在 27 步的技术调研中用 plan 跟踪进度，21 步的聚合测试中也用 plan 管理。
+**成功因素**：长任务中 plan 防止遗漏步骤，也方便中断后恢复时知道做到哪里了。
+**关键细节**：plan 步骤要粒度适中——太粗等于没 plan，太细浪费 token。每步应该是一个有明确产出的动作。
+
+## 检查清单（快速参考）
+
+编码前：
+- [ ] 相关代码都读过了吗？（模式 1）
+- [ ] 需要修改的范围确认了吗？
+
+编码后：
+- [ ] 运行验证了吗？边界情况测了吗？（模式 2）
+- [ ] 产出是最小必要集合吗？（模式 7）
+
+评审时：
+- [ ] 按结构化检查表逐项审查了吗？（模式 3）
+- [ ] 核实了实际数据，不只是看声明？（模式 4）
+
+任务流转：
+- [ ] 操作前查了当前状态吗？（模式 5）
+- [ ] 续杯时先查再续，不重复已完成工作？（模式 8）
+
+复杂任务：
+- [ ] 用 plan 跟踪进度了吗？（模式 9）
+- [ ] 调研时搜索 + 原文 + 结构化报告？（模式 6）