Task Decomposer

工程化任务拆解。三层拆解法+模板库+风险预警+动态调整+案例库+度量闭环。coordinator上游补充。

🔧 工程化任务拆解器（v2）

定位

coordinator 的上游补充。 coordinator 解决「谁来干、并行还是串行」，task-decomposer 解决「拆成什么、怎么拆、拆得好不好」。

---

核心原则

拆解不是手艺活，是工程活。拆解不是一次性的，是持续调整的。

每次拆解必须产出结构化文档。 拆解结果可交付、可审查、可回溯、可改进。

---

三层拆解法

第一层：业务拆解（做什么）

输入： 用户原始需求 产物： 需求拆解说明.md 方法：

1. 识别核心用户场景
2. 拆出功能边界（哪些做、哪些不做）
3. 标注优先级（P0/P1/P2）

第二层：工程拆解（怎么做）

输入： 需求拆解说明 产物： 模块依赖图.md + API 清单.md 方法：

1. 识别实体（表/数据结构）
2. 画依赖图（ASCII art）
3. 标注串行依赖和并行分支
4. 输出 API 端点清单
5. 过风险规则表，标注高风险节点

第三层：执行拆解（谁来做、什么顺序）

输入： 模块依赖图 + API 清单 + 风险标注 产物： 任务分配表.md + 执行计划.md 方法：

1. 按依赖关系和并行度切成原子任务
2. 匹配 agent 角色
3. 嵌入验收条件
4. 嵌入风险缓解措施

---

原子化标尺

维度	标准
文件数	1-5 个源文件
API 端点	不超过 5 个
测试	必须包含（3+ 用例）
验收条件	3-5 条硬验证
预估耗时	agent 可在 1-3 轮内完成

超出任何一项 → 继续拆。

---

风险预警系统

风险规则表

触发条件	风险等级	风险描述	缓解措施
涉及 Flyway 迁移脚本	🔴 高	版本冲突、checksum 不匹配	部署前跑 SELECT version, checksum FROM flyway_schema_history
涉及 JWT/Security 配置	🔴 高	密钥不一致	所有服务统一从 .env.runtime 读；SecurityConfig 放行认证端点
涉及 Docker 端口映射	🔴 高	容器内端口 ≠ 宿主机端口	显式设置环境变量
涉及跨服务 HTTP/Feign 调用	🟡 中	DNS 解析不到、网络隔离	确认目标服务在同一 docker network
涉及 context-path 配置	🟡 中	路径重复（/api/api/xxx）	Controller 不带 context-path 前缀
涉及 MySQL 中文存储	🟡 中	utf8 双倍编码乱码	JDBC URL 加 characterEncoding=UTF-8
涉及前后端字段对接	🟡 中	字段名不匹配	API 层加数据映射函数；数值用 ?? 保护
多 agent 并行写同一目录	🟡 中	文件覆盖冲突	确认文件清单无重叠
涉及事务+异步	🟡 中	事务未提交异步已读	异步任务加 500ms 延迟
涉及手动 DDL	🟢 低	未注册 Flyway 版本	手动 DDL 后创建 V 迁移脚本
涉及前端 enum 映射	🟢 低	STATUS_MAP 缺新增枚举	新增枚举值时同步更新
涉及超 30MB 文件传输	🟢 低	SCP 传输损坏	传输后校验 md5sum

---

动态调整策略

调整决策矩阵

agent 交付结果	判断	动作
✅ 一次通过	正常	继续原计划，释放后续依赖
⚠️ 返工 1 次	小偏离	先修复，该分支顺延，不波及其他
🔴 返工 ≥ 2 次	根因问题	暂停该分支，排查根因后重新派
📦 交付超出预期	边界侵入	检查是否侵入其他 agent 领地，调整边界
🚫 代码不落盘	致命	终止该 agent，换人重做，触发 P0 复盘

---

案例库

案例	类型	规模	关键经验
寓居智联	Spring Boot 微服务	10 服务 / 3 前端	CRUD 密集，上下文隔离、API 审计是瓶颈
法律 SaaS	Spring Boot + AI	4 服务 / 1 前端	LLM 集成是新增复杂度，RabbitMQ 异步需谨慎
LexGuard	Spring Boot 微服务	4 服务 / 前端	JWT+Security 反复出问题

新项目先搜案例库，复用骨架 + 加载历史风险点。

---

模板库

模板1：微服务 CRUD 模块

text

实体 → Repository → Service → Controller → DTO → 测试
执行：model+repo（1 agent）∥ service（1 agent）∥ controller+test（1 agent）
⚠️ 风险：Flyway冲突、context-path重复、字段不匹配

模板2：前端列表页

text

API 对接 → 列表+筛选+分页（1 agent）∥ 表单（1 agent）→ 路由+集成
⚠️ 风险：字段不匹配、STATUS_MAP 遗漏、API 失败白屏

模板3：数据库迁移

text

DDL → 数据迁移 → 校验+回滚（串行不可并行）
⚠️ 风险：版本冲突、checksum、手动DDL未注册

模板4：集成联调

text

接口审查 → 按模块联调 → 端到端测试
⚠️ 风险：端口映射、网络隔离、JWT不一致

模板5：Bug 修复

text

复现 → 定位 → 修复 → 回归（单 agent）
⚠️ 风险：修复引入新 bug，带回滚方案

---

版本化与度量

拆解产物结构

text

project/docs/decompose/{date}-{project}/
├── 01-需求拆解说明.md
├── 02-模块依赖图.md
├── 03-风险标注.md
├── 04-API清单.md
├── 05-任务分配表.md
├── 06-调整日志.md
└── 07-执行复盘.md

度量指标

指标	目标
并行度	≥ 3
一次通过率	≥ 70%
返工次数	≤ 1
遗漏率	0
风险命中率	持续跟踪
调整频率	< 30%

---

常见工程缺陷及对策

陷阱	对策
拆太粗 agent 迷路	强制过原子化标尺
拆太细沟通成本爆炸	拆解耗时 > 执行耗时 10% 即停止
只拆功能不拆数据	依赖图必须含实体/表节点
缺少验收标准	验收条件写进任务模板，不写完不派活
已知风险不预警	强制过风险规则表
交付偏离不调整	触发调整决策矩阵
agent 代码不落盘	验收第一条永远是文件存在性验证
同一个坑反复踩	复盘结论必须触发模板/风险表更新

---

使用流程

Step 1: 搜案例库 → 复用骨架 + 加载历史风险点

Step 2: 三层拆解 → 风险标注

Step 3: 自检清单

text

□ 原子化标尺通过？ □ 依赖图无循环？
□ 验收条件完善（第一条是文件验证）？ □ 高风险节点已标注？
□ 并行分支合理？ □ 产物已写入 docs/decompose/？

Step 4: 分批派活 + 动态调整

Step 5: 复盘 → 度量 → 更新风险表 + 入库

---

速查卡

1. 拆前：有相似案例吗？→ 搜案例库；风险规则表过了吗？
2. 派前：原子了吗？含测试吗？验收写了吗？依赖清了吗？能并行吗？
3. 派中：agent 偏了吗？→ 触发调整矩阵
4. 完后：度量了吗？复盘了吗？入库了吗？

---

与 coordinator 的关系

	task-decomposer	coordinator
关注	拆成什么、风险在哪、如何调整	谁来干、并行还是串行
输入	用户模糊需求	拆解后的任务清单 + 风险标注
输出	原子任务 + 依赖图 + 风险标注 + 调整日志	agent 分配 + 时序计划

先跑 task-decomposer 拆 + 预警，再跑 coordinator 派。