fmode-app/.claude/skills/dev-expert/references/task-decomposition-and-execution.md

# 任务拆解与执行

输入要求

1. 需求或spec（必填）：需要实现的功能描述或已有spec
2. 现有代码（可选）：相关代码片段或文件列表
3. 约束条件（可选）：时间、性能、依赖限制

执行流程

第一步：需求分析

• 理解核心目标和边界
• 不得委派理解：在拆分或调用子 Agent 前，主 Agent 必须先自行确认目标、边界、验收口径和风险点；子 Agent 只能接收明确任务，不能替主 Agent 判断用户真实意图
• 如需求属于做网站/建站/企业官网/CMS网站/营销页/网站上线，先调用 website-project 确认站点规划、SEO、部署、验收和运维阶段，再进入任务拆解
• 如需求属于 API服务/后端服务/后台模块/CLI工具/数据脚本/自动化任务/插件项目，先调用 software-project 确认边界、架构、数据/API、发布、回滚和交付阶段，再进入任务拆解
• 识别隐含依赖（如"用户系统"依赖"数据库表已存在"）
• 识别风险点（复杂算法、第三方集成、性能瓶颈）
• 识别安全触发面：外部输入、权限、数据库、文件上传、API、后台操作、长任务、第三方回调

第二步：原子任务拆解

将复杂需求拆分为2-7个原子任务（每Wave 2-5个）。每个任务必须满足：

• 单一职责：只解决一个明确问题
• 可独立完成：一个context window内可完成
• 可验证：有明确的完成标准
• 可回滚：失败时不影响其他任务
• 安全可验收：涉及输入/权限/数据/文件/API/后台操作的任务必须包含安全检查项
• 可委派：任务目标、输入、输出和验收标准已明确；若仍需判断用户意图或业务边界，须回第一步继续分析

任务结构（XML格式）：

<task type="auto|human-verify|decision">
  <name>[任务名称]</name>
  <files>[涉及文件列表]</files>
  <action>
    [具体执行步骤]
  </action>
  <verify>
    [验证方法：测试命令/检查清单/人工确认]
  </verify>
  <security>
    [安全验证：SQL注入/XSS/CSRF/权限绕过/文件上传/反序列化/敏感信息泄露；不涉及则写"不涉及，原因：..."；**禁止留空**]
  </security>
  <done>
    [完成标准：什么状态算完成]
  </done>
</task>

长任务需求专项拆解：若需求含"批量导入/导出/生成静态页/重建索引/采集同步/清理缓存/>3 秒或 >100 条处理"，不得按单端点单任务拆解，必须按 Init → Step → Poll 拆成依赖有序的 Wave：

• Wave 1（Init）：校验权限/CSRF/参数，创建任务记录，计算总量 → 返回 task_id、total、status=queued
• Wave 2（Step）：每批 20-100 条，更新进度、持久化状态、检测取消标记、幂等（用 last_id/游标保证每批唯一）
• Wave 3（Poll）：查状态/进度/错误，检测僵尸任务（running 超阈值标记 failed 或允许 resume）
• Wave 4（Cancel）：标记取消，正在执行的 Step 在下一批次检测取消标记后优雅退出
• Wave 5（前端轮询交互）：Init/Step/Poll/Done/Failed/Cancelled 状态、轮询间隔 800-2000ms、重试/取消入口、进度感知
• Wave 6（长任务测试）：Init/Step/Poll/失败重试/取消/超时/幂等全覆盖

各 Wave 间存在依赖（Step 依赖 Init 的任务记录，Poll 依赖 Step 的进度），必须串行；权限/CSRF/文件/SQL 等安全触发面须在每 Wave 的 <security> 写明验证方法。

第三步：Wave分组

按依赖关系将任务分组：

Wave 1（并行，无依赖）
├── Task 1.1: [任务A]
└── Task 1.2: [任务B]

Wave 2（依赖Wave 1）
├── Task 2.1: [任务C，依赖1.1]
└── Task 2.2: [任务D，依赖1.2]

Wave 3（依赖Wave 2）
└── Task 3.1: [任务E，依赖2.1和2.2]

分组原则：

• 无依赖的任务 → 同一Wave，可并行
• 有依赖的任务 → 后续Wave，必须串行
• 可能文件冲突的任务 → 同一Wave内串行或合并为一个任务
• 涉及安全触发面的Wave → 必须安排安全验证任务或在每个相关任务的 <security> 中给出验证方法

第四步：上下文隔离

执行单个任务时，只加载必要上下文：

任务上下文 = {
  spec: [相关requirement和scenario],
  design: [相关技术决策],
  files: [该任务需要读写的文件],
  decisions: [影响该任务的历史决策],
  previous_summary: [前置Wave的任务summary]
}

如平台允许子 Agent 或并行代理执行，必须使用简报式上下文，而不是传递完整对话历史：

委派简报 = {
  task: [单一任务目标],
  background: [只保留与任务直接相关的背景],
  files: [允许读取或修改的文件范围],
  constraints: [技术/安全/编码/输出限制],
  verify: [必须返回的验证证据],
  forbidden: [不得触碰的模块、不得扩展的范围]
}

禁止加载：

• 无关模块的代码
• 已完成的无关任务细节
• 未决但无关的讨论
• 完整聊天记录或未经筛选的日志

上下文隔离同时受主 SKILL.md「二、子Agent 边界与委派协议 → 2.3」与「长任务执行可靠性（L0）」约束：长任务只加载当前 Wave / 当前原子任务所需上下文，已完成 Wave 细节仅以 previous_summary 传递，不回灌完整对话历史，避免上下文污染导致后续 Wave 误判。

第五步：执行与验证闭环

每个任务执行后：

1. 执行：按action完成代码修改
2. 自测：运行verify中的验证方法
3. 复核结果：对照目标完成度、格式合规性、事实准确性、上下文一致性、边界条件和安全约束逐项检查；子 Agent 输出不得未经复核直接转交给用户

4. 记录summary：

   ## Task Summary: [任务名]
   
   **完成状态**: [完成/部分完成/失败]
   **修改文件**: [文件列表]
   **验证证据**: [命令/API响应/测试结果/人工确认]
   **置信度**: [高/中/低，低置信度必须说明原因]
   **关键决策**: [执行中做出的决策]
   **偏差说明**: [与plan的差异及原因]
   **遗留问题**: [未解决的问题]
   

5. 验证通过：标记done，进入下一任务

6. 验证失败：修复或回滚，重新执行

第六步：记录到项目记忆

所有Wave执行完毕后，将任务执行结果和关键决策沉淀到项目记忆（参见 project-memory-management.md）：

• 汇总各任务的 summary，生成整体执行报告（Session Summary 模式）
• 记录执行中的关键决策和偏差（Decision Record 模式）：如任务拆分调整、依赖关系变更
• 记录新发现的项目约束和规范（Convention Capture 模式）：如文件组织约定、模块边界规则

输出格式

## 任务拆解报告

### 需求概述
[一句话总结]

### 任务列表

#### Wave 1（并行）
```xml
<task type="auto">
  <name>...</name>
  <files>...</files>
  <action>...</action>
  <verify>...</verify>
  <security>...</security>
  <done>...</done>
</task>
```

#### Wave 2（依赖Wave 1）

...

### 执行建议

- 优先执行Wave 1，并行推进
- Wave 2等Wave 1全部完成后再开始
- 每个任务完成后立即验证

### 风险点

- [风险1及缓解措施]

质量标准

• 每个任务必须可在单个context window完成（建议不超过200行代码变更）
• 每个任务必须有明确的verify方法，不能是"看起来对就行"
• Wave分组必须明确标注依赖关系
• 涉及外部输入、权限、数据库、文件上传、API、后台操作、长任务、第三方回调的任务，必须写明安全验证方法
• 安全验证不得只写"已检查"，必须指向具体风险：SQL注入、XSS、CSRF、权限绕过、文件上传、反序列化、敏感信息泄露
• <security> 节点禁止为空：涉及安全触发面必须写明验证方法，不涉及必须写明原因
• 任务summary必须记录偏差，不能假装一切按计划进行
• 失败任务必须说明原因，不能默默跳过
• 子 Agent 或并行任务输出必须经过主 Agent 复核后才能计入完成度，不能把“已返回结果”等同于“已验证完成”
• 优先"垂直切片"（端到端功能）而非"水平分层"（全部模型→全部API）

失败回退机制

步骤	失败条件	回退目标	最大重试	不可恢复时升级路径
第一步：需求分析	需求边界不清，隐含依赖未识别	基于已知信息拆解，标注"依赖待确认"	1	输出需求澄清清单，等待用户补充
第二步：原子任务拆解	任务数量超出单次context window容量	按模块/资源域拆分为多个Wave集合	1	建议拆分为多个独立Spec驱动开发会话
第三步：Wave分组	任务间存在循环依赖	识别循环并合并为单任务，或引入中间状态	2	输出依赖图，建议架构层面解耦
第四步：上下文隔离	任务上下文跨Wave污染	强制重置context，仅加载previous_summary	1	标注"上下文隔离失败"，建议人工接管
委派执行	子 Agent 接收到完整对话、模糊目标或缺少验收口径	收回任务，重写委派简报后再执行	1	标注"委派边界失败"，由主 Agent 重新分析任务
第五步：执行与验证闭环	验证连续失败3次	暂停执行，输出差异分析	0	标记任务为"阻塞"，输出阻塞清单移交人工
第六步：记录到项目记忆	项目记忆系统不可用	输出执行报告和决策到本地文件	1	标注"执行结果未沉淀"，提示用户手动保存

关联 reference

• website-project（网站项目总控）— 建站类需求拆解前先定义完整生命周期阶段和上线交付清单
• software-project（软件项目总控）— 非网站类完整项目拆解前先定义边界、架构、验证、发布和交付清单
• spec-driven-development（Spec驱动开发）— 拆解前用 spec-driven-development 确保需求已对齐
• api-design（API设计）— API/服务类任务拆解前先定义接口契约、认证、错误码和分页
• frontend-design（前端设计）— 页面/后台交互任务拆解前先定义组件、状态、响应式和浏览器验证
• cms-development（CMS二次开发）— CMS/PHP二开任务拆解前先确认CMS访问层、插件入口和兼容性
• mysql-database（MySQL数据库）— 数据库/SQL任务拆解前先定义表结构、索引、事务、迁移和回滚
• code-generation（代码生成）— 每个task可用 code-generation 实现具体代码
• code-review（代码审查）— 每个task完成后用 code-review 检查质量
• test-generation（测试用例生成）— 每个Wave完成后补充正常、异常、边界、回归、安全、性能和长任务测试
• doc-generation（文档生成）— 交付前生成README、API文档、部署说明和使用说明
• project-memory-management（项目记忆管理）— 将task summary和决策记录到项目记忆