@chenguangyao/devflow-kit 0.1.43

package/skills/plan/references/task-breakdown.md

@@ -0,0 +1,207 @@
+# plan / task-breakdown
+
+Task 拆分的 4 种手法。选对手法比"拆得细"更重要。
+
+---
+
+## 4 种手法
+
+| 手法 | 核心 | 适用场景 | 好处 | 风险 |
+| --- | --- | --- | --- | --- |
+| **Vertical Slice**(竖切) | 每个 task 跨 层,做完一小块 end-to-end | 新功能、小需求 | 每 task 可独立 demo | 可能跨层 coupled,单 task 信息密度高 |
+| **By Layer**(按层) | 先数据层 → 服务层 → 接口层 → UI | 重构、迁移 | 层内专注、减少 context switch | 前几个 task 不可 demo(没 UI 透出来) |
+| **By F-ID**(按功能点) | 每个 F-ID 一个 task(或多个 task 聚焦一个 F-ID) | 多功能点并行的 L2 | 清晰对应需求 | 一个 F-ID 可能很大,仍需二次拆 |
+| **By Behavior**(按 TDD 行为) | 每个 task 推一个具体行为(测试)通过 | TDD 严格执行、L2/L3 业务类 | 每 task 天然对应 TC | 可能产生很多小 task,依赖图杂 |
+
+## 手法选择决策树
+
+```
+本次是什么类型?
+├─ 新功能(L1-L3)
+│   └─ 是否跨多个 F-ID?
+│       ├─ 1-2 个 F-ID → Vertical Slice(端到端一 task 一 task 推)
+│       └─ ≥ 3 个 F-ID → By F-ID(每 F-ID 一组 task)+ By Behavior(组内 TDD 拆)
+├─ 重构 / 代码迁移
+│   └─ By Layer(层层推进,每层换完再下一层)
+├─ 纯 DDL / 数据迁移
+│   └─ By Layer(DDL → 双写 → 切读 → 回收)
+├─ Bug fix(L1)
+│   └─ 1-2 个 task 完事;By Behavior(先写失败测试)
+└─ 性能优化
+    └─ By Behavior(每个优化对准一个 perf TC 或 profiling 结果)
+```
+
+---
+
+## Vertical Slice(竖切)详解
+
+**理念**:每个 task 切穿所有层,做一个可 demo 的小功能。
+
+**示例**(add-coupon-batch-grant):
+
+```
+T-01: "空输入返回 400"          (完整 Controller + validator + test)
+T-02: "1001 返回 BATCH_TOO_LARGE" (扩 validator + test)
+T-03: "1000 人全成功"           (Controller + Service + DAO + test)
+T-04: "部分失败返回 failedUsers"  (Service 加部分失败逻辑 + test)
+T-05: "幂等:同 batchId 再调"     (DAO 唯一键 + Service 幂等处理)
+...
+```
+
+**优**:
+
+- 每 task 做完都有可用的行为
+- TDD 友好(task = 一个测试的实现)
+- 容易并行(不同 vertical 独立)
+
+**劣**:
+
+- 每 task 跨文件多(Controller / Service / DAO / Test)
+- 需要熟悉全栈
+
+**适合**:功能开发,尤其是 L2;不适合大型重构。
+
+---
+
+## By Layer(分层)详解
+
+**理念**:底层稳定优先,上层构建在稳定基础上。
+
+**示例**(数据迁移):
+
+```
+Layer 1(DDL): T-01 新表 / T-02 索引 / T-03 约束
+Layer 2(双写): T-04 写新表 / T-05 写旧表保留
+Layer 3(对账): T-06 对账 job
+Layer 4(切读): T-07 读切新表
+Layer 5(回收): T-08 停旧写 / T-09 归档
+```
+
+**优**:
+
+- 逐层稳定,下层不动上层工作正常
+- 层内专注,减少上下文切换
+
+**劣**:
+
+- 前几个 task 不可 demo(对用户不可见)
+- 跨 phase 依赖多
+
+**适合**:重构、迁移、底层变更;不适合业务功能开发。
+
+---
+
+## By F-ID 详解
+
+**理念**:每个 F-ID 一组 task,组内按 TDD 或竖切。
+
+**示例**:
+
+```
+F-01 group: T-01, T-02, T-03      (批量接口)
+F-02 group: T-04, T-05             (风控逐条)
+F-03 group: T-06, T-07             (后台 UI)
+```
+
+**优**:
+
+- 对应需求清晰,code-review 时直接按 F-ID 查覆盖
+- 可以按 F-ID 为单位并行(不同 F-ID 给不同人)
+
+**劣**:
+
+- F-ID 可能大小不均,导致 task 估时分布不平衡
+
+**适合**:多功能点的 L2/L3。
+
+---
+
+## By Behavior(按行为)详解
+
+**理念**:每个 task 对应一个具体行为(一个 TC),严格 TDD:先写失败测试,再最小实现。
+
+**示例**:
+
+```
+T-01: behavior "EMPTY_BATCH on empty userIds"      对应 TC-002
+T-02: behavior "BATCH_TOO_LARGE on 1001 userIds"   对应 TC-003
+T-03: behavior "success on 1000 valid userIds"     对应 TC-001
+T-04: behavior "partial fail on 10 risk hit"       对应 TC-004
+...
+```
+
+**优**:
+
+- 最 granular 的拆法
+- 测试先行,实现跟随
+- 每 task 粒度稳定(都是"1 test + 最小实现")
+
+**劣**:
+
+- task 数量多(≥ TC 数量)
+- 依赖图杂
+
+**适合**:严格 TDD 团队;对业务复杂度高、行为多的核心 service。
+
+---
+
+## 混合策略(推荐)
+
+真实项目常常是**混合**:
+
+```
+大结构:By F-ID(F-01 / F-02 / F-03 分组)
+组内:By Behavior(每组内按 TC 拆 task)
+横切关注点:By Layer(DDL 最先、flag 最后、测试单独)
+```
+
+前述 L2 示例 plan.md 就是混合策略:T-01/03/04 是 F-01/F-02 的行为级 task;T-02(DDL) / T-06(flag) 是横切 layer;T-05 是 F-03 的竖切 UI。
+
+---
+
+## 拆得过细的信号(要合)
+
+- 两个 task 改同一文件且依赖紧密
+- 两个 task 的 test 在同一个 test class
+- 合起来仍 < 30 分钟
+
+→ 合为一个 task,但 Implementation 列 2-4 步保留粒度。
+
+## 拆得过粗的信号(要拆)
+
+- Implementation 超过 4 bullet
+- Files > 3 个
+- 预估 > 60 分钟
+- 跨 F-ID(一个 task 同时做 F-01 和 F-02 的事)
+
+→ 拆成多个 task。
+
+---
+
+## 特殊 task 类型
+
+### Flag task
+
+Feature flag 的 "加" 和 "开" 通常分两个 task:
+
+- T-NN(较早):加 flag 默认 **off**,代码路径已齐备
+- T-MM(最后):把 flag 切到 **on** 或加灰度比例逻辑
+
+### DDL task
+
+通常独立 task,估时 15-30 分钟。如果 DDL 影响 ORM mapping 或需要双写,拆为:
+
+- DDL 加列 task
+- ORM entity 更新 task
+- 双写 task
+- 切读 task
+
+### 验证 task
+
+独立的 integration / perf test task 通常放在最后。不要把 perf 塞进业务 task。
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 给了拆分规则(粒度数字、5 要素)。本文给拆分**手法**的选择与例子。agent 开始写 plan.md 前先按决策树选一个主手法,然后用混合策略细化。

package/skills/plan/references/task-sequencing.md

@@ -0,0 +1,143 @@
+# plan / task-sequencing
+
+Task 排序 + 依赖图 + 并行化判断。
+
+---
+
+## 排序硬规则
+
+1. **契约变更在前**:DTO / proto / GraphQL schema 改动的 task 先,消费者 task 后
+2. **DDL 在前**:表结构变更 task 在业务代码 task 之前
+3. **每 task 后仓库 green**:task 完成后 repo 处于"所有测试都过"的状态(不允许暂时红)
+4. **Flag 开关最后**:flag 默认 off 先落,开启 / 分流比例配置最后
+5. **业务优先于基础设施**(同优先级下):业务 task 先跑出 review 价值,基础设施 task(监控 / 日志)补上
+6. **测试 task 独立或尾部**:integration / perf test 通常独立 task 放尾;unit test 嵌在对应业务 task 里
+
+---
+
+## 依赖类型
+
+| 类型 | 符号 | 含义 |
+| --- | --- | --- |
+| 强依赖 | `T-01 → T-02` | T-02 必须在 T-01 完成后 |
+| 弱依赖 | `T-01 ⇢ T-02` | T-02 最好在 T-01 后,但能先并行做 stub |
+| 并行 | `T-01 ∥ T-02` | 无先后关系 |
+| 互斥 | `T-01 ⊥ T-02` | 不能同时做(同一文件冲突) |
+
+**真实项目中主要是强依赖 + 并行**。
+
+---
+
+## DAG 画法示例
+
+### 简单(线性)
+
+```
+T-01 → T-02 → T-03 → T-04
+```
+
+### 中等(fan-out / fan-in)
+
+```
+         T-01
+        /    \
+     T-02   T-03    (T-02 ∥ T-03)
+        \    /
+         T-04
+```
+
+### 复杂(多入口)
+
+```mermaid
+flowchart TD
+  T-01[Controller skeleton] --> T-03[Service batch]
+  T-02[DDL batch_id] --> T-03
+  T-03 --> T-04[Risk wrapper]
+  T-03 --> T-05[Admin UI]
+  T-04 --> T-06[Flag + metric]
+  T-05 --> T-06
+  T-06 --> T-07[Integration tests]
+```
+
+---
+
+## 并行化判断决策树
+
+两个 task 可以并行 吗?按下表回答:
+
+| 问题 | 答 | 含义 |
+| --- | --- | --- |
+| 改同一个文件? | 是 → 不能并行 | 合并或强串行 |
+| 有前后依赖(A 的产出是 B 的输入)? | 是 → 不能并行 | 强依赖 |
+| 改同一个数据库表?(schema 改动) | 是 → 不能并行 | DDL 串行安全 |
+| 一个是契约定义,另一个是消费者? | 是 → 不能并行 | 契约必须先 |
+| 以上都否 | 可以并行 |
+
+---
+
+## 并行化的实际执行
+
+devflow-kit 的 `devflow apply --task=N` 默认给每个 task 创建一个 worktree。apply 阶段的并行度由依赖图决定:同一批 ready task 中只要有 ≥ 2 个互不依赖且无共享文件,上层 IDE/agent 就必须并行分派多个子 agent。
+
+- **串行**:只用于强依赖、共享文件、DDL/契约先后关系等不可并行场景
+- **2 路并行**:同一 ready wave 内有两个独立 task,例如 T-02 和 T-03
+- **多路并行**:L3 项目中 3-5 个独立模块同时 ready 时合理
+
+并行时注意:
+
+- 每路在**独立 worktree**,git 状态不冲突
+- 并行启动要在同一轮 dispatch 完成,不要等 T-02 返回后才启动本可并行的 T-03
+- **合并顺序**按依赖图:T-02 并行好了要先合,T-03 依赖 T-02 才能拉最新合并
+- **review 仍然按 task 顺序或按合并顺序做**,不要"并行 5 个 task 一次合 5 个 commit 再 review"
+
+---
+
+## 依赖图检查
+
+写完 plan.md 过一遍:
+
+- [ ] 每个 task 都在图上?(或标注 "**isolated**")
+- [ ] 图有**明确起点**?(至少 1 个无依赖 task 是 "Ready")
+- [ ] 图无**环**(不能 T-01 → T-02 → T-01)
+- [ ] 图有**汇点**?(最后一个 task 没下游;通常是 integration test 或 deliver task)
+- [ ] 并行节点确实可并行(按上面判断)
+
+---
+
+## 关键路径(critical path)
+
+关键路径 = 串行依赖最长的那条链。优化点:
+
+- 关键路径上的 task 缩短 = 总工期缩短
+- 关键路径上的 task 质量风险高(阻塞其他)
+- 优先 review / 优先验收
+
+示例:
+
+```
+T-01 → T-03 → T-06 → T-07   (关键路径)
+T-02 → T-03
+T-04 → T-06
+T-05 → T-06
+```
+
+关键路径 = T-01 → T-03 → T-06 → T-07。T-02/04/05 可以并行,但它们不是关键路径,缩短它们不缩短总工期。
+
+---
+
+## 常见排序坑
+
+| 坑 | 表现 | 对策 |
+| --- | --- | --- |
+| 把 DDL 放最后 | 所有业务 task 都跑在旧 schema 上,集成测试才发现 | DDL 必在业务 task 前 |
+| 契约和消费者同 task | 契约改完还没合,消费者已开始用 mock,后面换真实契约又要改 | 契约独立 task,先合 |
+| 测试放在业务 task 里没单独放 | 某 task 改动大,unit + integration 都塞进去,超粒度 | integration test 独立 task |
+| 以 task 数量估时 | "10 task,每 30 分钟,5 小时搞定" | 按 task 复杂度加权估,且考虑并行加速 |
+| Flag 在业务 task 里一起加 + 一起开 | flag 开了业务没做完,半成品上线 | Flag 先加 off、最后改 on,分两 task |
+| 性能 / 压测塞进 deliver 前 | 临时抱佛脚 | perf TC 明确任务,独立 task 早跑 |
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 给了排序硬规则 4 条。本文给依赖类型、DAG 画法、并行化判断、关键路径、常见坑。agent 写 plan.md §1 依赖图时按本文流程来。

package/skills/plan/references/task-template.md

@@ -0,0 +1,248 @@
+# plan / task-template
+
+plan.md 完整模板 + task 5 要素的详细模板 + 正反例 + 完整 L2 示例。
+
+---
+
+## plan.md 模板
+
+```markdown
+---
+slug: <slug>
+createdAt: <ISO>
+level: L1 | L2 | L3
+refs:
+  - design.md
+  - tests.md
+---
+
+# 任务计划: <一句话标题>
+
+## 1. 任务依赖图
+```
+
+        T-01 (Controller 骨架)
+              ↓
+        T-02 (DDL batch_id 列)
+              ↓
+        T-03 (Service batch 方法,复用 grantOne)
+              ↓            ↓
+        T-04 (RiskService 串行) [可与 T-05 并行]
+              ↓            ↓
+        T-05 (Admin UI CSV import) [可与 T-04 并行]
+              ↓            ↓
+        T-06 (Feature flag + metric)
+              ↓
+        T-07 (集成测试 + 回归扫)
+
+```
+
+## 2. 任务清单
+| 任务ID | 文件 | 估时 | TC | 依赖 | 可并行 |
+| --- | --- | --- | --- | --- | --- |
+| T-01 | BatchGrantController.java (新建) | 30min | TC-002, TC-003 | — | — |
+| T-02 | V2_add_batch_id.sql (新建) | 15min | - | — | — |
+| T-03 | GrantService.java (修改) | 45min | TC-001, TC-004 | T-01, T-02 | — |
+| T-04 | RiskClientWrapper.java (新建) | 30min | TC-006 | T-03 | T-05 |
+| T-05 | admin-ui/BatchUploadPage.vue (新建) | 60min | TC-008 | T-01 | T-04 |
+| T-06 | feature flag 配置 + 指标 | 30min | — | T-03, T-04, T-05 | — |
+| T-07 | integration tests | 60min | TC-005, TC-009, NFR-PERF-001 | T-06 | — |
+
+## 3. 每个任务详表
+
+### T-01:Controller 骨架
+- **文件**:
+  - `coupon-service/src/main/java/.../BatchGrantController.java` (新建)
+- **行为**:
+  新增 POST /api/v2/coupon/batch-grant,校验 userIds 长度 1-1000,返回占位响应 {code:"NOT_IMPL"}
+- **测试**:
+  TC-002 (空 → 400 EMPTY_BATCH),TC-003 (1001 → 400 BATCH_TOO_LARGE)
+- **实现**:
+  1. 新建 Controller 类,加 @RestController + @RequestMapping("/api/v2/coupon")
+  2. 加方法 @PostMapping("/batch-grant"),入参 DTO(userIds, couponTemplateId, batchId?)
+  3. 加 @Valid + 自定义 validator(size check)
+  4. 实现体暂返回 501 NOT_IMPL
+- **提交**:
+  `feat(coupon): T-01 add batch-grant controller skeleton + input validation`
+
+### T-02:DDL 加 batch_id
+- **文件**:
+  - `coupon-service/src/main/resources/db/migration/V2_add_batch_id.sql` (新建)
+- **行为**:
+  coupon_grant 表加 batch_id VARCHAR(36) NULL + idx_grant_batch_id 索引
+- **测试**:
+  — (DDL 不需要独立 test;Flyway 启动会自测)
+- **实现**:
+  1. 写 SQL:ALTER TABLE ... ADD COLUMN IF NOT EXISTS batch_id ...
+  2. 写 CREATE INDEX IF NOT EXISTS ...
+  3. 本地 Flyway 启动验证
+  4. 回滚脚本注释到文件末尾(DROP COLUMN IF EXISTS)
+- **提交**:
+  `feat(coupon): T-02 add batch_id column to coupon_grant`
+
+### T-03:Service 批量方法
+- **文件**:
+  - `coupon-service/src/main/java/.../GrantService.java` (修改)
+- **行为**:
+  新增 batchGrant(userIds, templateId, batchId) 方法,逐条独立事务调 grantOne,聚合成功 / 失败
+- **测试**:
+  TC-001 (1000 全成功),TC-004 (部分失败)
+- **实现**:
+  1. 新方法 public BatchResult batchGrant(...)
+  2. 循环 userIds,每条包 try-catch 调 grantOneInNewTx(@Transactional(REQUIRES_NEW))
+  3. 成功 → succeeded;RiskRejectedException → failed with RISK_HIT
+  4. 聚合返回 BatchResult(grantedCount, failedCount, failedUsers)
+- **提交**:
+  `feat(coupon): T-03 implement batch grant with per-user tx`
+
+### T-04:RiskClientWrapper
+- **文件**:
+  - `coupon-service/src/main/java/.../RiskClientWrapper.java` (新建)
+- **行为**:
+  包装 RiskService,给批量场景提供带 timeout + 指标上报的 check
+- **测试**:
+  TC-006 (timeout 降级 + failedUsers reason=RISK_TIMEOUT)
+- **实现**:
+  1. 新建 wrapper 类,注入原 RiskService
+  2. 加 timeout 配置(riskTimeoutMs)
+  3. try timeout → throw RiskTimeoutException
+  4. Mmetrics.timer.record("risk.check.latency")
+- **提交**:
+  `feat(coupon): T-04 add risk client wrapper with timeout`
+
+### T-05:Admin UI CSV 上传(并行 with T-04)
+- **文件**:
+  - `admin-ui/src/pages/coupon/BatchUpload.vue` (新建)
+  - `admin-ui/src/api/coupon.ts` (修改)
+- **行为**:
+  运营后台页面:上传 CSV → 预览(前 20 行)→ 点击发放 → 调 POST /batch-grant → 展示结果
+- **测试**:
+  TC-008(integration 端到端)
+- **实现**:
+  1. 新 Vue page,用 el-upload + 自定义 CSV parser(papaparse)
+  2. 上传后展示表格前 20 行 + 命中风控预估(调 preview API 或本地推算)
+  3. 点击"发放"弹窗确认 → 调 coupon.batchGrant API
+  4. 展示 result 表(grantedCount / failedUsers list)
+- **提交**:
+  `feat(admin-ui): T-05 add batch upload page for coupon grant`
+
+### T-06:Feature flag + metric
+- **文件**:
+  - `coupon-service/src/main/resources/application.yml` (修改)
+  - `coupon-service/src/main/java/.../BatchGrantController.java` (修改)
+- **行为**:
+  加 feature flag coupon.batch.enabled,关闭时接口 503;加 coupon.batch.latency histogram
+- **测试**:
+  —(通过 T-07 整合 TC 验证)
+- **实现**:
+  1. application.yml 加 feature.coupon.batch.enabled=false(默认关)
+  2. Controller 入口加 flag check → throw ServiceUnavailable if disabled
+  3. 入参校验后、返回前分别打 metric(MeterRegistry.timer)
+  4. Apollo 对接(若项目已集成)
+- **提交**:
+  `feat(coupon): T-06 add feature flag + latency metric`
+
+### T-07:集成测试 + 回归扫
+- **文件**:
+  - `coupon-service/src/test/java/.../BatchGrantIntegrationTest.java` (新建)
+  - `coupon-service/src/test/java/.../GrantServiceTest.java` (修改,加回归)
+- **行为**:
+  跑 TC-005/009/NFR-PERF-001;加回归 TC 保证单发 path 不受影响
+- **测试**:
+  TC-005(DB 落库), TC-009(权限), NFR-PERF-001(1000 人 P99)
+- **实现**:
+  1. 起 Testcontainers MySQL
+  2. BatchGrantIntegrationTest:fixture 1000 用户 → POST → 断言 DB + 响应
+  3. Permission test:用 mock token 无 coupon:batch_grant → 期望 403
+  4. Perf(k6 / JMH 单独启动)→ P99 断言
+  5. 回归扫:加几条 GrantServiceTest 确保单发不变
+- **提交**:
+  `test(coupon): T-07 integration + perf baseline for batch grant`
+
+## 4. 变更日志
+- 2026-04-24 初始版本,7 task
+- (若后续拆 / 合 task,在此记)
+```
+
+---
+
+## 5 要素详细规则
+
+### 文件
+
+- **具体路径**,绝对路径或相对 repo root 都行(保持一致)
+- 标注 `(新建)` / `(修改)` / `(删除)`
+- **≤ 3 个文件**;超出说明粒度不够,拆
+- **Go 默认根目录 `test/`**:新增 Go 黑盒 / 接口 / 联调 / 回归测试优先写 `test/**/*.go`;只有包内白盒测试必须访问未导出符号、`internal` import 受限、或项目已有同目录测试约定时,才允许在业务包旁新增 `*_test.go`,并在 task 的 Test 中写明理由。
+- 不允许 `whatever needed` / `TBD` 这种模糊表述
+
+### 行为
+
+一句话,必须满足:
+
+- **具体**:写 "返回 400 EMPTY_BATCH",不是"处理空输入"
+- **可测**:能直接对应 1+ TC
+- **≤ 30 字**(不包括标点)
+
+**反例**:
+
+> "实现 Controller 方法处理各种情况"(不具体、不可测)
+
+**正例**:
+
+> "POST /batch-grant 校验 userIds 长度 1-1000,越限返回 400 + code"(具体 + 可测)
+
+### 测试
+
+- 必须引用 `tests.md` 里**存在**的 TC 编号
+- 允许多个 TC(这个 task 覆盖多条)
+- 允许 TC 在多 task 间共享(T-01 跑一次,T-03 跑一次)
+- L1 可写 inline 简述:`Test: "调 /batch-grant 空 userIds 返回 400"`
+
+### 实现
+
+- **2-4 条** bullet,再多说明粒度太大
+- 不写代码行(不允许 ```Java ... ```)
+- 每条描述"做哪一步",粒度是"能独立执行"
+- 可以引用类名 / 方法名(因为这是具体改动点)
+
+### 提交
+
+- Conventional Commits 格式:`<type>(<scope>): T-NN <verb> <object>`
+- `type`:feat / fix / refactor / test / docs / chore / build
+- `scope`:模块或服务名
+- 含 T-NN 方便追溯
+- 动词 + 宾语,描述性
+
+**反例**:
+
+> `update code`(没有 task ID / 没动词 / 毫无信息)
+
+**正例**:
+
+> `feat(coupon): T-01 add batch-grant controller skeleton`
+
+---
+
+## 依赖图画法(§1)
+
+简单箭头链即可,不强求 mermaid。原则:
+
+- 每个 task 一个节点
+- 箭头表示"必须先完成"
+- 可并行 task 并列(同一行 / 合并节点 labeled "[parallel]")
+- 合并点(fan-in)用 "↓  ↓  → T-06"
+
+若 DAG 复杂(> 10 节点) → 用 mermaid `flowchart TD`。
+
+---
+
+## 完成状态(task level)
+
+task 的 state 由 `devflow apply --task=N --start/--done` 驱动,不由 plan skill 自己改。plan 只定义"要做什么"。
+
+---
+
+## 本文与 SKILL.md 的关系
+
+SKILL.md 给了 5 要素字段名 + 拆分规则数值。本文给:完整 plan.md 模板、每个 task 详表 + 5 要素写作规则 + 正反例 + 完整 L2 示例。agent 写 plan.md 时从本文开始。