复合工程规划

它解决什么问题

复杂功能经常死在中途：目标写成“优化体验”或“研究一下”，验收只能靠感觉；实现开始后上下文被压缩，阶段边界、关键决策和测试状态散落在对话里；要么每个小改动都铺一版重型计划，要么凭直觉硬写，最后在集成阶段发现切片对不上。compound-eng-planning 把这类工作拉回可验证的规划轨道：先筛目标，再按复杂度选择计划深度，并在实现期间维护可读的进度状态。

技能如何工作

核心原则是前置思考：规划 token 比实现 token 便宜，复杂度决定投入规模。进入路径选择前先跑 Goal Quality Gate，用五个问题确认完成物、证据和阈值，避免在弱目标上做计划或跳过计划。然后按规模分档：

• Skip planning：原子提交、没有约束后续实现的设计选择、范围自明、不需要上游产物溯源时直接执行。
• Flat list：3–5 个文件改动、边界清晰且无需调研时，用编号清单或 progress.md，不建 .plan/ 脚手架。
• Full plan：跨模块、存在 Key Technical Decisions、或需要阶段分解时，生成结构化计划。

init-plan.sh 会生成 .plan/task_plan.md、findings.md 和 progress.md，并把 .plan/ 加入 .gitignore。这些文件只作为实现期间的临时工作状态，不提交；正式计划文档放在 docs/plans/。计划质量规则要求任务里没有 TBD、TODO、“适当处理”这类占位语，必须带具体文件路径、命令、代码模式和预期结果；函数名、变量名和路径要保持类型一致，避免同一件事在不同任务里叫法漂移。

阶段按上下文安全来切分：单阶段最多触碰 5–8 个文件，最多依赖两个其他阶段，单项任务约两小时内完成。任务按用户可见能力做纵向切片，每完成 2–3 个任务就做轻量 checkpoint，跑测试、点接口或渲染组件确认已建部分真的连在一起。实现细节由执行者决定并写清理由；影响用户看到什么、能做什么的选择才交给用户确认。

适用边界与注意点

它不适合把每个机械改动都包装成重型流程。README 第 47 行改错别字、全局重命名、单纯升级依赖且无破坏性变更，都属于可跳过场景。看起来像原子操作但藏着设计选择的工作要警惕，例如“给这个端点加缓存”会牵出 TTL、失效策略、缓存键和后端选择，应当写计划。

对已有代码的项目，计划前要先发现测试现状，沿用现有测试模式而不是引入新框架；绿野项目没有测试时可跳过这步。多阶段实现要在上下文压缩后从 .plan/progress.md 恢复，提交过的任务在计划里记录 commit SHA；实现偏离计划时要在对应任务下写明 Deviation，否则调用方无法判断执行是否失真。计划只交付规格要求的东西，不顺手加“锦上添花”，范围扩展要单独标记并获批。