plan-first-development

规划

概述

一种以规划为先的开发方法论：在开始实现之前，80% 以上的时间都用于规划。规划所需的 token 比实现所需的 token 更便宜，而且相比庞大的代码库，大模型在详细且符合上下文窗口的计划上推理得更好。

适用场景： 启动新项目、添加主要功能、将复杂工作拆分为多个阶段、在上下文清空后恢复工作、管理跨多个会话的实现，以及协调多个 Agent 在同一代码库上协作。

不适用场景： 快速修复 bug、仅涉及一个文件的更改、需求尚不明确的探索性原型开发，以及更改显而易见的简单重构。

快速参考

规划阶段	说明
1. 初始计划	编写目标、意图、工作流和技术栈
2. 迭代完善	进行 4-5 轮审查，直到建议趋于稳定
3. 多模型融合	获取相互竞争的计划，整合各方优点
4. 转换为任务	创建自包含且具有依赖关系结构的任务
5. 润色任务	进行 6+ 轮跨模型审查

阶段类型	范围	最大文件数	时长
基础设施	脚手架、构建配置、部署	3-5	1-3 小时
数据库	迁移、架构、种子数据	2-4	2-4 小时
API	路由、中间件、验证	3-6	3-6 小时
UI	组件、表单、状态、样式	4-8	4-8 小时
集成	第三方服务、Webhook	2-4	3-5 小时
测试	端到端测试、集成测试	不定	3-6 小时

模式	用途	要点
何时规划与构建	根据复杂度信号制定决策树	让规划深度与任务复杂度相匹配
风险评估	概率 × 影响矩阵	优先关注高风险事项

会话生命周期	操作
开始	阅读 SESSION.md，检查“下一步操作”，然后继续
工作	实现、验证、调试（重复进行）
检查点	按结构化格式提交 Git，更新 SESSION.md 哈希
收尾	更新 SESSION.md，创建 Git 检查点，设置明确的“下一步操作”
恢复	阅读 SESSION.md 和规划文档，从“下一步操作”继续

文档	生成时机
实施阶段	始终生成——每个项目的核心计划文档
会话跟踪	始终生成——进度导航中心
数据库架构	3 张及以上表
API 端点	5 个及以上端点
架构概览	多个服务或复杂的系统边界
关键工作流	复杂的设置步骤、顺序敏感的工作流

好计划	优秀计划
描述要构建什么	解释为什么要构建它
列出功能	详细说明用户工作流和交互
提及技术栈	权衡利弊，论证技术选择
包含任务	包含带依赖关系和理由的任务
约 500 行	完善后约 3,500 行以上

常见错误

错误	正确做法
规划尚未完成就开始实施	将 80% 以上的时间用于规划；完成所有轮次的细化后再编写代码
后续行动写得含糊，例如“继续处理 API”	写清楚具体事项：“在 src/routes/tasks.ts:47 实现 PATCH /api/tasks/:id”
会话跟踪文档超过 200 行	将已完成的阶段压缩为摘要；详情请参阅规划文档
创建包含 10 个以上文件的阶段	自动拆分为每个包含 5-8 个文件的子阶段，确保每个子阶段适合在一次 2-4 小时的会话中完成
只进行一轮计划审查	迭代 4-5 轮，直至建议不再增加；结合多个模型获取新视角
将代码复制到会话文档中	引用文件路径和行号，而不是粘贴代码
在会话文档中重复规划文档的内容	使用锚点链接到相关章节；会话文档用于导航
阶段没有验证标准	每个阶段都需要具体、可测试的完成标准（状态码、用户流程、约束条件）
计划尚未完成就先编写骨架代码	一份周全的计划胜过逐步编写骨架代码
未对未知技术进行原型验证就开始规划	对不熟悉的框架先做技术验证，再制定计划
对简单任务过度规划	规划深度应与复杂程度相匹配；琐碎工作可跳过规划
未尽早验证假设	首先针对风险最高的假设进行技术验证

委派

• 探索现有代码库，了解架构决策：使用 Explore Agent，在规划前调研文件结构、模式和依赖项
• 执行阶段实施并进行验证：使用 Task Agent 实施各个阶段、运行验证标准并创建检查点提交
• 设计架构并拆分阶段：使用 Plan Agent 创建实施阶段，并确定依赖顺序和关卡标准

参考资料

• 规划流程与迭代细化
• 会话管理与上下文跟踪
• 基于阶段的实施规划
• 审查工作流与多模型融合
• 决策跟踪与条件文档
• 规划文档模板