cruldra/phased-implementation

Phased Implementation

概述

本 Skill 约束最终形态不确定、需要人类全程决策的大型工程任务。

核心原则一句话：讲思路 → 等绿灯 → 动手 → 报告 → 等下一阶绿灯 → 提交上一阶。

把任务切成可独立提交的阶梯：每阶先确认方案，写完后不立即提交，等下一阶开工许可再提交上一阶。这种"延迟提交"给用户保留返工窗口。

何时使用

适用：

• 最终设计不确定的大型任务（搭平台、写新模块、复杂重构）
• 用户明确希望全程参与决策、不愿意被一次性塞结果
• 蓝图 / 需求文档存在但细节未敲死，需要边做边调
• 任务由多个可测试子单元组成（如 3.1 / 3.2 / 3.3）

不适用：

• 单一明确小任务（直接做就行）
• 用户已经给出完整规格、只需照做的任务
• 紧急 hotfix 或探索性 spike

核心循环

阶段 N 开始
   ↓
讲思路（方案 / 文件结构 / 接口设计 / 风险点 / 选择题）
   ↓
等用户明确说 "开干" / "OK 开始" / 选 A/B
   ↓
实施（写代码 + 写测试 + 跑通）
   ↓
报告完成（"X.Y 阶完成；回'继续 X.Z'我先 commit X.Y"）
   ↓
等用户说 "继续 X.Z"
   ↓
先 commit 上一阶（X.Y）→ 再讲 X.Z 思路
   ↓
回到顶部

铁律

| # | 规则 | 反例 | |---|------|------| | 1 | 预告 ≠ 方案确认。即便用户说 "下一步做 X"，仍要先讲方案再等 "开干" | 用户说 "开始 3.2" 就直接写代码 | | 2 | 写完不立即提交。等用户给下一阶绿灯时才 commit 上一阶 | 写完测试通过就立刻 git commit | | 3 | 一阶一 commit。每个阶梯一个独立提交，commit message 体现阶梯编号 | 多阶混合提交、跨阶混用一次 commit | | 4 | 代码里不写决策历史注释。阶段号、issue 号只属于 commit message | 在代码里写 # 阶段 3.5 引入此类 | | 5 | 遇到偏离原计划的反馈，立即停手并按反馈重做，不要为了维持进度抗辩 | "已经写了，下阶段再改吧" | | 6 | 任何用户图片 / 质疑指向的代码片段都视为 RED 信号，先理解意图再改 | 不看图就解释 | | 7 | 批量推进请求要拆。用户说 "3.2/3.3/3.4 都给我做了" 仍要逐阶等绿灯，不能一次性写到 3.4 | 一口气写三阶代码 |

单阶段结构

讲思路时必须包含

本阶目标、文件清单、关键设计、选择题、风险点、测试策略。

报告完成时必须包含

新增 / 修改文件、测试结果、关键决策回顾、下一阶预告 + 绿灯触发词："回 「继续 X.Z」 我先 commit X.Y，然后讲 X.Z 思路"。

绿灯识别

下列表达视为开干（可以动手实施）：

• "开干"、"OK 开始"、"上"、"动手吧"
• 对选择题的明确选择："A"、"选 A"、"用方案 1"

下列表达视为继续 X.Z（提交上一阶 + 进入下一阶讲思路）：

• "继续 X.Z"、"继续下一阶"、"继续 3.6"
• "OK 继续"

下列表达不是绿灯：

• "好的"、"嗯"（含糊确认，需追问）
• "听起来不错"（可能仅评价方案）
• 仅复述用户上一句的回声

模糊时主动追问："是要我现在动手实施 3.5，还是先讨论？"

提交上一阶的时机

只有在收到下一阶绿灯之后才提交上一阶。提交时：

1. commit message 用 emoji + 阶梯编号 + 简短特征： ✨ feat(runtime): 3.5 ConcurrencyManager — 全局+per-key 双层 Semaphore + 10 单测
2. 仅 commit 本阶相关文件，不夹带无关变更
3. 提交完成后再讲下一阶思路，不要把 commit 和讲思路混在一条消息里

反馈处理

用户对已写代码提出质疑时：

1. 立即停手，不要继续写新代码
2. 回到反馈指向的具体位置（用户给图片就看图片指的那行）
3. 回溯相关阶段：如果反馈推翻早期决策（例如 "数据库访问必须走 Repository 层"），要修所有违反规则的历史阶段代码，不能只改新代码
4. 重做后重新跑测试，确认回归通过

不要因为"已经 commit 了"就拒绝回溯——本流程的"延迟提交"机制就是为了给反馈留窗口。

压力场景与应对

| 压力 | 表现 | 应对 | |------|------|------| | 快进 | "这部分简单，跳过讲思路直接干" | 仍先讲方案 | | 沉没成本 | 写到一半发现方案有问题 | 立即停手报告，不要硬撑 | | 批量 | "3.2 / 3.3 / 3.4 都给我做了" | 仍按一阶一 commit 节奏，逐阶等绿灯 | | 合理化 | "这是小修改，提前 commit 没关系" | 不行，违背"延迟提交"机制本质 |

红旗信号

出现这些想法时，停下来：

• "用户已经预告过这阶，跳过讲思路吧"
• "测试都通过了，先 commit 一下吧"
• "这一阶代码很少，和下一阶合并一起 commit"
• "反馈先记下，下阶段顺便改"
• "这个注释加上阶梯编号方便理解"
• "三阶都讲清了，一次性都实施完"

每一条都意味着违反铁律，必须立即纠偏。

常见错误

| 错误 | 后果 | 修正 | |------|------|------| | 写完阶段就 commit | 用户失去回溯审查的窗口 | 等下一阶绿灯再 commit | | 多阶代码堆在一个 commit | 出问题难以二分定位 | 一阶一提交 | | 用户给反馈后只改新代码、不回头修旧代码 | 历史污染累积，规则被破坏 | 反馈回溯所有相关阶段 | | 在代码注释里写阶段编号 | 注释快速过时、变成噪音 | 只在 commit message 里写 | | 不讲思路就动手 | 方向跑偏，返工成本高 | 先讲方案 | | 把 commit 和讲下一阶思路混一条消息 | 用户难以分别审查 | 先 commit，commit 完成后单独讲下一阶 | | 接收"OK"就当绿灯 | 用户可能只是表达接收、未授权 | 模糊时主动追问 |

与其他流程的关系

• 与 TDD：本 Skill 管宏观节奏；单阶内部仍应先写测试再实现
• 与 Plan 工具：Plan 提供阶梯划分；本 Skill 规定阶梯之间如何衔接
• 与 anti-over-engineering：每阶讲思路时仍遵循"够用即可"

适配建议

• 绿灯触发词：可以约定其他短语，但要在第一阶明确告知用户
• 阶梯命名：可用 3.1 / 3.2 / 3.3、phase-1a 或 milestone-A1
• commit message 模板：可保留 emoji 风格，也可改为常规 conventional commits

但铁律 1-7 不可调整，否则会退化为普通分阶段开发。