@chenguangyao/devflow-kit 0.1.43

package/skills/apply/references/tdd-loop.md

@@ -0,0 +1,287 @@
+# apply / tdd-loop
+
+TDD 每步该做什么 / 不该做什么,常见偏离的识别。
+
+---
+
+## TDD 一轮的 6 步
+
+```
+1. 读 task 5 要素                   (30 秒)
+2. 写失败测试(RED)                 (10-15 分钟)
+3. 最小实现让测试通过(GREEN)        (10-20 分钟)
+4. 运行所有相关测试(防回归)         (1-2 分钟)
+5. 重构(可选,测试为护栏)          (5-10 分钟)
+6. commit + --done                  (1 分钟)
+```
+
+---
+
+## Step 1:读 task 5 要素
+
+**动作**:
+
+```
+cat devflow/changes/<slug>/plan.md | awk '/^### T-<ID>/,/^### T-<next>/'
+```
+
+把 Files / Behavior / Test / Implementation / Commit 5 行读清。确认:
+
+- [ ] Files 列表的每个文件存在?(new 的确认要在哪里新建;modified 的读一遍当前)
+- [ ] Test 里引用的 TC 在 tests.md 真的定义了?(以防 plan 引用错 TC)
+- [ ] Behavior 有没有歧义?(有 → 别开始,回问)
+
+---
+
+## Step 2:写失败测试(RED)
+
+**关键纪律**:
+
+1. **先跑一次确认失败**:新测试 commit 前,确认它真的失败而不是误报
+2. **失败原因正确**:失败必须是"被测对象的期望行为不对",不是"NPE""未编译""找不到类"
+3. **断言具体**:不要 `assertTrue(result != null)`,要 `assertEquals(990, result.grantedCount)`
+
+### Go 测试文件落点
+
+Go 项目默认不要在业务源码目录旁边随手生成 `*_test.go`。优先把自动新增的黑盒 / 接口 / 联调 / 回归测试放到项目根目录 `test/` 下,例如:
+
+```text
+test/
+├── member_upgrade_test.go
+├── api/
+│   └── member_upgrade_api_test.go
+└── fixtures/
+    └── member_upgrade.json
+```
+
+推荐写成外部包测试,通过 module path import 被测包:
+
+```go
+package test
+
+import (
+    "testing"
+
+    member "code.example.com/health/go_member/internal/services/member"
+)
+```
+
+只有下面情况才允许在业务源码同目录新增 `*_test.go`,并且必须在 plan.md 的 Files / Test 中写明理由:
+
+- 包内白盒测试:必须访问未导出的函数 / 类型 / 变量,且通过公开 API 无法可靠覆盖
+- Go 编译限制:被测对象位于 `internal` 包且根 `test/` 无法合法 import
+- 现有项目已有明确约定:该 package 已经有大量同目录测试,本次只是补同 package 表驱动 case
+
+即使允许同目录测试,fixture / golden / 大样本仍优先放根目录 `test/fixtures/` 或 package 自己的 `testdata/`,不要散落到业务代码目录。
+
+**模板**(用项目的测试框架):
+
+```java
+@Test
+void batchGrant_allSuccess_returnsGrantedCount() {
+    // Arrange
+    List<String> userIds = fixtures.batch1k();
+    when(riskService.check(any(), any())).thenReturn(RiskResult.PASS);
+
+    // Act
+    BatchResult result = grantService.batchGrant(userIds, "ct_ok", "b_test");
+
+    // Assert
+    assertEquals(1000, result.getGrantedCount());
+    assertEquals(0, result.getFailedCount());
+    verify(dao, times(1000)).insertGrantLog(any());
+}
+```
+
+**常见偏离**:
+
+| 偏离 | 对策 |
+| --- | --- |
+| 假装"先写实现,反正最后有测试" | 强制:`git diff` 必须先有 test 文件,再有实现文件 |
+| 写了断言很弱的测试("doesn't throw") | 改写具体断言,覆盖 behavior 描述 |
+| 测试依赖多个复杂 mock,逻辑复杂 | 简化 mock;mock 过复杂说明设计有问题 |
+| 测试名像 `test1`(没描述) | 测试名必须描述"输入 → 期望",如 `batchGrant_emptyUserIds_returns400` |
+
+---
+
+## Step 3:最小实现(GREEN)
+
+**关键纪律**:
+
+1. **刚好让测试通过**,不多做事
+2. **不顺手重构**其他代码(除非 task 就是重构)
+3. **不添加没测到的代码路径**:如果你写了 branch,没测它,review 会要求补测
+4. **不"顺便"优化性能**(除非 task 就是性能):优化属于独立 task
+
+**常见偏离**:
+
+| 偏离 | 识别 |
+| --- | --- |
+| "既然已经在这里了,顺便把 X 也做了" | 违反 scope;X 如有价值开新 task |
+| 实现比测试要求的多 | 回头扫实现,问"这行代码对应哪条断言?无对应 → 删 或 补测" |
+| 使用全局 / static 状态 | 测试会 flaky;改构造注入 |
+| 硬编码(magic number / string) | 起码抽常量;避免 review 时被 NIT |
+
+---
+
+## Step 4:运行所有相关测试
+
+**不仅**跑新加的测试。至少跑:
+
+- 修改文件所在 module / package 的全部 test
+- CI 必跑的 smoke 层
+
+```bash
+# Java
+mvn -pl <entry-module> -am test
+# Java DDD 多模块:如果只想先编译受影响链路
+mvn -pl <entry-module> -am -DskipTests compile
+
+# Go
+go test ./test/... ./coupon/...
+
+# Python
+pytest tests/coupon/
+
+# Node
+npm test -- coupon
+```
+
+### Baseline Attribution / 验证阶梯
+
+在老项目、DDD 多模块或编译环境不稳定时，先把"项目原本就坏"和"本轮 diff 改坏"拆开。改代码前做一次最小基线探测，改完后走验证阶梯。
+
+**改代码前**：
+
+```bash
+mvn -version
+mvn -pl <entry-module> -am -DskipTests compile
+```
+
+如果失败，记录到 `baselineKnownFailures`：命令、错误摘要、是否涉及计划 Files / 本轮 diff、是否属于环境或历史红点。不要立刻改业务代码来迁就基线错误。
+
+**改完后按从快到慢验证**：
+
+```bash
+git diff --check
+mvn -pl <entry-module> -am -Dtest=<TestClass> test
+mvn -pl <entry-module> -am -DskipTests compile
+```
+
+- 命中新改文件 / 新增测试 / 本轮 diff 依赖链路的错误：当前 task 内修。
+- 与改代码前一致、且不触碰本轮 diff 的错误：作为 `baselineKnownFailures` 上报。
+- 单条 compile/test 的时间预算建议 3-5 分钟；超过 5 分钟不要换一串全量命令盲跑，先输出阻塞/风险和下一步卡片。
+- 已确认的基线失败不能无限重试；最多复核一次，之后用 `DONE_WITH_CONCERNS` 或 `BLOCKED` 表达风险。
+
+### Java DDD / 多模块 Maven 验证
+
+DDD 多模块项目不要把"单个源码目录"或"单个 leaf module"当成最终验证单位。domain / app / adapter / infrastructure 经常依赖 annotation processor、聚合 root、DTO/BO 转换和 reactor 顺序，单模块或裸 classpath 很容易误报。
+
+**验证前先确认实际构建 JDK**：
+
+```bash
+mvn -version
+rg 'maven-toolchains-plugin|toolchain|maven.compiler.release|maven.compiler.source|maven.compiler.target|<java.version>|maven-compiler-plugin|lombok' pom.xml **/pom.xml
+ls .java-version .sdkmanrc .tool-versions 2>/dev/null
+```
+
+- `java -version` 只能说明当前 shell 的默认 Java，不等于项目编译实际使用的 Java。
+- Maven 实际运行 JDK 以 `mvn -version` 的 `Java version` / `Java home` 为准。
+- 如果项目使用 `maven-toolchains-plugin`，还要检查 `~/.m2/toolchains.xml` 和 Maven 日志里最终选择的 toolchain。
+- 项目声明版本来自 `maven.compiler.release` / `source` / `target` / `<java.version>`；它只是声明，必须和 Maven 实际运行 JDK / toolchain 对照。
+- 遇到 `Unsupported class file major version`、`IllegalAccessError`、`NoSuchFieldError`、Lombok annotation processor 报错时，先诊断 JDK / Maven / toolchain / Lombok 版本，不要先改业务代码。
+
+**推荐策略**：
+
+- 开发中先跑最小可编译 reactor slice：`mvn -pl <entry-module> -am -DskipTests compile`
+- 跑相关测试也用 reactor slice：`mvn -pl <entry-module> -am -Dtest=<TestClass> test`
+- `<entry-module>` 选真实入口模块：改 domain 但使用入口在 app，就优先选 app；改 adapter/mapper 就选承载该链路的 app/boot 模块。
+- 公共 domain / DTO / mapper / interface 契约被多模块复用时，task 完成前再跑全量 `mvn -DskipTests compile` 或项目 CI 等价命令。
+
+**禁止把 `javac --proc:none` 当作最终验证**：
+
+- `javac --proc:none` 不跑 Lombok / MapStruct / QueryDSL 等 annotation processor，只能做临时语法探针。
+- 不能因为裸 `javac` 下 Lombok getter/setter 不生成，就给 BO/DTO/Domain 补显式 getter/setter。
+- 如果 Maven reactor 编译和裸 `javac` 结果冲突，以 Maven reactor / CI 为准。
+
+**如果回归挂了**:
+
+1. 第一反应:是不是我改动引起的?
+2. 如果是 → 修(不是新 task,是当前 task 的一部分)
+3. 如果不是(偶发 / 环境)→ quarantine 老 flaky,记 issue,继续(不要吞)
+
+---
+
+## Step 5:重构(可选)
+
+测试通过后,在测试护栏下重构:
+
+- 抽方法 / 拆 if-else
+- 去重复
+- 改命名
+
+**前提**:测试必须先通过。重构中**只改结构不改行为**,每一小步后重跑测试。
+
+**不要**:
+
+- 改测试("测试和实现一起改") → 失去护栏
+- 跨 task 重构(超出 Files 范围)
+- 大改结构(独立开 task)
+
+---
+
+## Step 6:commit + --done
+
+```bash
+git add .
+git commit -m "feat(coupon): T-01 add batch-grant controller skeleton + input validation"
+
+# 回到 devflow-kit 工作目录执行 df(不在 worktree 里):
+devflow apply --task 1 --done --note="commit $(git -C .devflow-worktrees/<slug>/task-1 rev-parse HEAD)"
+```
+
+**硬规则**:
+
+- commit message **严格按 plan.md** 里的格式
+- `--done` 的 `--note` 要含 commit sha,方便 review 溯源
+- 如果 task 分了多个 commit,note 含最后一个 sha(或所有 sha)
+
+---
+
+## TDD 的常见误区
+
+### "TDD 拖慢我"
+
+事实:TDD 前期慢 15%,但整体项目减少 40-70% 的 bug 返工时间(业界研究)。
+
+快感的 illusion:没写测试 → 跑快了 → 后面 review + verify + bug 追尾时间是 10x 回来。
+
+### "我知道要写什么,先写实现最快"
+
+结果:实现完你"记得"去写测试,但测试变成"为实现服务",断言往往会迁就实现的行为,而不是反向驱动正确的行为。review 会扫这种 test 叫 "implementation-driven test",严重度 SHOULD。
+
+### "这个 bug 太明显,不用写测试"
+
+事实:没测试的 fix 会在 3 周后由别的 commit 复活。所有 bug fix 都应该有一个 reproducing test → fix → test pass。
+
+### "单元测试覆盖不全,我直接集成测试"
+
+混合策略 OK,但:
+
+- 纯逻辑分支应该在 unit 测(快、稳)
+- 集成测试补充"真实依赖下整合对不对",不代替 unit
+
+---
+
+## TDD 的循环小技巧
+
+- **命名测试 → 想清行为**:写测试名时往往就想清楚 "要测什么";想不清就别写,说明 task behavior 没想清
+- **断言写前半**:先 `assertEquals(X, ...)`,再填实现去算 X;防止 "实现出啥我断啥" 的反向 flavor
+- **failing state 先 commit**(可选):先 `git commit -m "T-01 RED: add failing test"`,再 GREEN,再 `git rebase -i` squash;把思路流程也留下来
+- **测试不通过了别着急看实现**:先看测试代码是不是正确表达了 behavior;测试错了 / 不对会把 debug 带向错误方向
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 给了 4 步硬规则。本文给每步该做 / 不该做、常见偏离、修正、TDD 心法。apply 阶段每做一个 task 都应对照本文节奏。

package/skills/apply/references/when-plan-is-wrong.md

@@ -0,0 +1,279 @@
+# apply / when-plan-is-wrong
+
+发现 plan / design / requirement 不对时的决策树与审计格式。
+
+---
+
+## 核心原则
+
+apply 是**执行**,不是**决策**。当前上游产出有问题时:
+
+1. **停**:停止编码,不在 apply 里暗改
+2. **定位**:问题在哪个 phase(plan / tech-spec / requirement-analysis)
+3. **回退**:跳回对应 phase 修正
+4. **审计**:产物里记录"第 N 次返工"的原因和改动
+5. **恢复**:回到 apply,继续当前或下一 task
+
+最大的错误是**在 apply 里暗自调整**——代码和 design / plan 对不上,review 会炸,archive 的 spec delta 也乱。
+
+---
+
+## 决策树:回退到哪?
+
+```
+发现问题
+   ↓
+问题本质?
+   ├─ "我按 task 描述做,但 test 过不了" → design 有缺陷
+   │    → 回退 tech-spec
+   │
+   ├─ "task 描述不清,两种实现都说得通" → plan 颗粒度不够
+   │    → 回退 plan
+   │
+   ├─ "我发现这种情况 AC 没定义应该怎么办" → 需求边界漏掉
+   │    → 回退 requirement-analysis(Round 2 追加 Q)
+   │
+   ├─ "前 N 个 task 写完,才发现整体架构有问题" → design 级缺陷
+   │    → 回退 tech-spec(严重时回退 requirement-analysis)
+   │
+   ├─ "依赖的外部服务接口和 design 的假设不符" → 假设错误
+   │    → 回退 tech-spec(可能 requirement)
+   │
+   ├─ "性能测试发现 X 不满足 AC" → 设计没考虑
+   │    → 回退 tech-spec
+   │
+   ├─ "task 做着做着发现能拆成 3 个更独立的子 task" → 颗粒度
+   │    → 回退 plan(小改,不是大回退)
+   │
+   └─ "AC 本身写错了 / 含糊" → 需求缺陷
+        → 回退 requirement-analysis
+```
+
+---
+
+## 回退流程
+
+### 第 1 步:暂停当前 task
+
+```bash
+devflow apply --task N --pause --reason="<具体描述>"
+```
+
+会:
+
+- 把 task 状态从 in_progress 标为 paused
+- 记录 reason 到 state.json
+- 提示要回到 devflow-kit 工作目录处理(不在 worktree 里)
+
+**不要**直接跳过或 abandon——要留痕。
+
+### 第 2 步:进入对应 phase 修正
+
+#### 回退到 plan
+
+```bash
+devflow plan --edit --reason="task T-07 描述有歧义"
+```
+
+在 plan.md 里:
+
+- 找到有问题的 task
+- 修正 5 要素描述
+- 如果是颗粒度问题:拆分 / 合并
+- 更新依赖 DAG(如果有影响)
+- 保留一段"# 返工记录"
+
+然后硬闸:
+
+```bash
+devflow plan --check
+```
+
+#### 回退到 tech-spec
+
+```bash
+devflow tech-spec --revise --reason="事务边界在并发场景下不安全"
+```
+
+在 design.md:
+
+- 改动受影响的"技术方案"/"关键决策"部分
+- 更新或新增 ADR(记录为什么改)
+- 如有 spec delta 变化 → 更新 `delta/<capability>.md`
+- 留下修订说明
+
+然后必然要回到 plan 重新核对:design 变了,plan 的 task 可能也要调整。
+
+#### 回退到 requirement-analysis
+
+```bash
+devflow requirement-analysis --round-3 --reason="发现批量失败时的处理 AC 未定义"
+```
+
+- 新开一轮 Q&A 补清楚
+- 更新 requirement.md 的"功能需求"/"边界与异常"
+- 新增 / 修改 F-ID 的 AC
+
+然后所有下游(design / plan / tests)都要跟着核对,是否需要 revise。
+
+### 第 3 步:审计记录
+
+每次回退都在对应产物里留一段(附录或末尾):
+
+```markdown
+## 修订历史
+
+### v1.2 (返工 #1, 2026-04-24)
+- **触发**:apply 阶段 T-07 发现事务边界在并发超 100 时死锁
+- **调整**:
+  - 设计:由 `@Transactional` 包整个 service method,改为拆分为 "校验(无事务)+ 核销(短事务)+ 记录(独立事务)"
+  - Spec delta:新增 `delta/coupon-batch-grant.md` "MODIFIED: 事务策略"
+- **影响下游**:
+  - plan.md T-07 Files 新增 `TransactionConfig.java`
+  - plan.md T-08 被拆成 T-08a / T-08b
+- **作者**:@eng-a(executor)+ @arch-b(tech-spec reviewer)
+- **审批**:roll back approved
+```
+
+### 第 4 步:恢复 apply
+
+```bash
+devflow apply --task N --resume
+```
+
+- 当前 task 状态从 paused → in_progress
+- 重新读 plan.md / tests.md / design.md
+- 按新 plan 重新做(可能需要 revert 部分已写代码)
+
+---
+
+## 已完成 task 受到影响怎么办?
+
+### 场景:做 T-05 时发现 design 有问题,回退 tech-spec 后,T-01~T-04 受影响
+
+对策:
+
+1. **逐个评估**:T-01 ~ T-04 的 Behavior / Implementation 是否受新 design 影响
+2. **受影响的 task**:
+   - 重置状态为 todo:`devflow apply --task 3 --reset --reason="design revised in #1"`
+   - 重新做(可能能复用部分代码 / 测试)
+3. **不受影响的 task**:状态保持 done,但在 state.json 记录 "verified against revise #1"
+4. **更新 plan.md**:反映 task 重置信息
+
+### 场景:已经 push 到远端的代码受影响
+
+不能 revert 历史(多人协作)。做法:
+
+- 新开 task 修正(不是回退)
+- plan.md 里新加 task T-Nx 或 T-N+1
+- 走正常 apply 流程
+
+---
+
+## 什么情况下**不**回退,继续 apply
+
+有些发现不够到 "回退" 级别,只是 "noting":
+
+| 发现 | 对策 |
+| --- | --- |
+| 变量命名更好的写法 | 记 NIT,当前 task 内修正即可 |
+| 代码里可以抽一个 util | 当前 task 内抽(若 scope 合适)或 TODO + 新 task |
+| 测试覆盖率可以更高 | 当前 task 补测试(review 前自查) |
+| design.md 的一个小拼写错误 | apply 结束后一起修,不回退 |
+| 发现一个 code review 风格问题 | 按 cheatsheet 自改,不回退 |
+| 临时找到更优性能写法 | 看是否 AC 要求;不要求 → 记 TODO,新 task 讨论 |
+
+**判断标准**:回退是"行为 / 契约 / AC 级"的;小改不是。
+
+---
+
+## 返工的审计字段
+
+state.json 里为每次返工加一条:
+
+```json
+{
+  "iterations": [
+    {
+      "id": 1,
+      "triggeredAt": "apply:T-07",
+      "rollbackTo": "tech-spec",
+      "reason": "事务边界在并发超 100 时死锁",
+      "durationMinutes": 120,
+      "affectedTasks": ["T-01","T-02","T-03","T-05","T-06","T-07","T-08"],
+      "impactSummary": "design revised: 事务拆分;plan revised: T-08 拆分",
+      "resolvedAt": "2026-04-24T14:30:00Z"
+    }
+  ]
+}
+```
+
+这份数据在 archive 阶段会汇总进 retrospective.md(如有),也在 `devflow doctor` / `devflow metrics` 里统计"平均返工率"。
+
+---
+
+## 常见的错误应对
+
+### 错:在 apply 里偷改 design
+
+```
+# code 里实现了 design 没说的并发控制
+# design.md 没更新
+```
+
+后果:
+
+- review 看不懂代码("为什么这里有锁?design 没说啊")
+- archive 时 spec delta 对不上代码
+
+正确:停 → 回退 tech-spec → 更新 design + delta → 再回来 apply。
+
+### 错:在 apply 里直接改 plan.md
+
+```
+# 把 Files 列表加了一个文件
+# 没记录 revise 原因
+```
+
+后果:下次 review 找不到"为什么要加这个文件",可能会质疑合理性。
+
+正确:`devflow plan --edit --reason=...` 走流程,留审计。
+
+### 错:绕过回退,"临时"写个补丁
+
+```
+# code 里加了 @SuppressWarnings
+# 或者硬编码 workaround
+# 想 "先过 CI 再说"
+```
+
+后果:review 会挂,即使不挂也是技术债。
+
+正确:回退对应 phase 彻底解决;实在紧急 → 开 ADR 明确 "临时方案" + 还债 task。
+
+### 错:返工时漏了下游同步
+
+```
+# 改了 tech-spec
+# 没更新 plan
+# apply 时按老 plan 做 → 和新 design 对不上
+```
+
+正确:返工后必须按顺序检查下游:requirement → spec → plan → tests → apply。每一层都要"对齐"了才继续。
+
+---
+
+## 返工次数的预警
+
+| 单个 slug 返工次数 | 说明 | 建议 |
+| --- | --- | --- |
+| 0 次 | 一次过 | 健康(但要警惕:是不是真的想清楚了?) |
+| 1-2 次 | 正常 | L2/L3 常见,复杂系统难免 |
+| 3-4 次 | 警告 | 上游清晰度不够,要反思 |
+| ≥ 5 次 | 问题 | 大概率需求 / 设计没想清,建议暂停并重新 framing |
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 说了"回退优先级 + 表"。本文详解决策树 / 审计格式 / 受影响 task 处置 / 常见错误。发现问题时对照本文操作。