cfdaily
6.6 KiB
name, description
| name | description |
|---|---|
| proven-practices | 从成功任务中提炼的最佳实践：编码模式、评审策略、调研方法、工具使用方式。 在开始复杂任务时触发，作为"怎么做好"的参考。 |
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）