🎉 init: 小龙的工作空间

tools/agent-decomposition.md

@@ -0,0 +1,171 @@
+# Agent 任务拆解规范（v2）
+
+> 2026-05-31 从红尘提供的拆解框架内化 + 自审迭代
+> 本版本修复了 v1 的 6 个已知漏洞
+
+## 核心原则
+
+1. **Agent Package 是可被单个 Agent 独立完成的最小工作单元**
+2. **优先考虑上下文容量**，不追求任务少，追求一次能完成
+3. **禁止出现 XL 级任务**（耗时 > 120分钟）
+4. **最大化并行能力**，多个 Agent 同时启动
+5. **每个包必须有明确的风险评估**，不能无脑分工
+
+## 任务拆解流程
+
+```
+Step1：构建项目全景图
+  ├─ 产品层 / 前端层 / 后端层 / 数据层
+  ├─ 中间件层 / 基础设施层 / 运维层 / 测试层
+  └─ 形成系统架构地图（8层全覆盖）
+
+Step2：构建模块树
+  └─ 按业务域划分模块（用户系统/资源系统/评论系统...）
+  └─ 每模块标注：P0/P1/P2/P3 优先级
+
+Step3：构建依赖图
+  ├─ 模块依赖（模块A → 模块B）
+  ├─ 数据依赖（表A → 表B）
+  ├─ API依赖（接口A → 接口B）
+  └─ 开发顺序依赖（必须先做什么）
+
+Step4：任务拆解（逐层）
+  模块 → Feature → Task → Agent Package
+  每步检查：是否拆到可独立交付的最小粒度？
+```
+
+## Agent Package 标准格式
+
+```
+## Agent-ID: P<优先级>-<序号>
+
+### Objective
+任务目标（一句话说清）
+
+### Scope
+影响范围（模块/层/文件范围）
+
+### Inputs
+需要阅读的文件（列出具体路径，≤15个）
+
+### Outputs
+需要产出的内容（代码/配置/文档/脚本）
+
+### Dependencies
+依赖哪些 Agent Package（用 ID 引用）
+
+### Deliverables
+交付物清单（具体文件路径）
+
+### Acceptance Criteria
+验收标准（可测试、可验证的条件）
+
+### Risk Assessment
+风险评估（每个包单独评估，见下方 Risk 分类）
+
+### Estimated Complexity
+复杂度评估（Small / Medium / Large，XL禁止）
+
+### Efficiency Score
+效率评分（1-10，[8,10]为合格，<8 需重构边界）
+```
+
+## Task Size 等级
+
+| 等级 | 耗时 | 阅读文件 | 修改文件 | 新增代码 |
+|------|------|----------|----------|----------|
+| Small | 5-15min | ≤ 3 | ≤ 2 | ≤ 300行 |
+| Medium | 15-45min | ≤ 8 | ≤ 5 | ≤ 800行 |
+| Large | 45-120min | ≤ 15 | ≤ 10 | ≤ 1500行 |
+| XL | > 120min | ❌ 禁止 | ❌ 禁止 | ❌ 禁止 |
+
+## XL → Large 拆分策略
+
+如果发现 XL，按以下策略拆解（不直接说"禁止"了事）：
+
+```
+XL 任务
+├─ 跨模块拆分 → 每个模块独立为一个 Medium
+├─ 跨层拆分   → 前端/后端/数据库各为一个 Medium
+├─ 大文件拆分 → 核心逻辑 / 辅助逻辑 / 配置 各为一个 Small
+├─ 复杂业务流 → 按步骤拆为链式 Small（A→B→C）
+└─ 大代码量   → 按功能切片，每片 ≤ 300 行
+```
+
+## 效率评分规则
+
+每个 Agent Package 从 4 个维度评分，加总后 [1, 10]：
+
+```
+Complexity（复杂度）：1=单文件修改，3=多文件联动，5=跨模块
+Context Usage（上下文使用率）：1=读满15个文件，3=读8个，5=读3个
+Dependency Count（依赖数）：1=依赖3+个包，3=依赖1-2个，5=零依赖
+Parallelism（可并行度）：1=阻塞链中，3=可部分并行，5=完全独立
+```
+
+**公式：** `Score = (Complexity + Context + Dependencies + Parallelism) × 0.5`
+
+**合格线：≥ 8**。低于 8 分继续拆分或重构任务边界。
+
+## 风险分析
+
+每个 Agent Package 必须评估以下风险，写出规避方式：
+
+| 风险类型 | 检查项 |
+|----------|--------|
+| 架构风险 | 是否引入新依赖？是否改变模块边界？ |
+| 数据风险 | 是否改数据库结构？是否有迁移脚本？ |
+| 并发风险 | 是否有资源竞争？是否有锁问题？ |
+| 安全风险 | 是否涉及鉴权？是否有输入校验？ |
+| Agent 协作风险 | 依赖的其他包失败如何自救？ |
+| 上下文超限风险 | 是否需要的上下文超出预算？ |
+
+## Large 任务审查
+
+只有 Large 及以上需要此审查：
+
+```
+## Large Task Justification
+
+1. 为什么无法继续拆分？
+2. 为什么需要多个文件协同？
+3. 为什么仍适合单 Agent 完成？
+
+如果解释不成立 → 自动重新拆分。
+```
+
+## 开发路线图
+
+| 等级 | 内容 | 特征 |
+|------|------|------|
+| **P0** | 核心基础设施 | 数据库、认证、基础框架 |
+| **P1** | 核心业务功能 | 主要业务逻辑、关键 API |
+| **P2** | 增强功能 | 辅助业务、优化功能 |
+| **P3** | 优化功能 | 性能、UI 打磨、文档 |
+
+## 依赖图输出格式
+
+```
+P0-01: 用户模型（无依赖）
+   ↓
+P1-01: 注册API（依赖P0-01）
+   ↓（可并行）
+P1-02: 文章模型（无依赖）
+   ↓
+P2-01: 文章CRUD（依赖P1-01, P1-02）
+```
+
+## 最终自检
+
+输出前逐项检查：
+
+- [ ] 所有 Agent Package 总耗时是否 > 2小时？（每包单独评估，不是总时间）
+- [ ] 是否存在 XL 任务？（不直接说"禁止"→ 给出拆分方案）
+- [ ] 是否存在上下文超限任务？（阅读 > 15 文件？修改 > 10 文件？新增 > 1500 行？）
+- [ ] 是否存在不可并行的阻塞链？（A→B→C→D→E 这种长链要优化）
+- [ ] 是否存在跨业务域任务？（→ 必须拆分）
+- [ ] 是否存在效率评分 < 8 的包？
+- [ ] 是否存在没有风险评估的包？
+- [ ] 是否存在循环依赖？
+
+如果任意一项为"是" → 自动重新拆分 → 直到全部通过。