SuperAPI AI 工具集

planning-and-task-breakdown

智能体与模型

查看项目

更新于 10-15 11:04

技能介绍

本技能提供一套把工作拆解为小型、可验证任务的方法,目标是在智能体或人工会话中可靠交付,而不是产出混乱的返工。

用途

当你已有规格或清晰需求、需要把工作拆成可实现的单元时使用;当某个任务过大或过模糊难以启动时使用;当工作需要在多个智能体或会话之间并行时使用;当你需要向人沟通范围时使用;当实现顺序不明显时使用。不适用的情况:范围明显的单文件修改,或规格中已经包含定义良好的任务。

规划流程

第一步:进入计划模式。在写任何代码之前采用只读方式:阅读规格与相关代码库部分,识别既有模式与约定,映射组件之间的依赖,记录风险与未知项。规划期间不写代码,产物是保存到 tasks/plan.md 的计划文档,以及记录在任务清单目标(默认 tasks/todo.md)中的任务列表,而不是实现。

第二步:识别依赖图。梳理什么依赖什么,例如数据库模式派生 API 模型与类型,再派生 API 端点、前端 API 客户端与 UI 组件;校验逻辑挂在 API 模型下;种子数据与迁移挂在数据库模式下。实现顺序按依赖图自底向上,先建基础。

第三步:垂直切片。不要先建完整个数据库、再做全部 API、再做全部 UI,而应一次构建一条完整的功能路径。例如任务是“用户可创建账户(注册所需的模式+API+UI)”“用户可登录(认证模式+API+UI)”“用户可创建任务”“用户可查看任务列表”。每个垂直切片都交付可运行、可测试的功能。

第四步:编写任务。每个任务无论落在 markdown 任务列表还是外部追踪器,都遵循同一结构,包括:任务编号与简短描述性标题;一段说明该任务达成什么的描述;具体、可测试的验收标准清单;验证清单,如运行仓库的聚焦测试命令、构建命令、需要人工确认的检查;依赖的任务编号或无;预计涉及的文件路径;规模估算。

第五步:排序并设置检查点。安排任务时保证依赖被满足、每个任务结束后系统仍处于可工作状态、每2至3个任务之后有验证检查点、高风险任务靠前以便尽早失败。检查点以清单形式加入任务清单目标,例如“任务 1-3 后:所有测试通过、应用构建无错误、核心用户流程端到端可用、继续前与人工评审”。

任务规模指南

XS:1 个文件,单函数或配置改动,如新增一条校验规则。S:1-2 个文件,一个组件或端点,如新增一个 API 端点。M:3-5 个文件,一个功能切片,如用户注册流程。L:5-8 个文件,多组件功能,如带筛选与分页的搜索。XL:8 个以上文件,过大,需要进一步拆分。L 及以上的任务应拆小,智能体在 S 与 M 任务上表现最佳。需要进一步拆分的信号:会超过一次专注会话(约 2 小时以上的智能体工作)、验收标准无法用 3 条或更少要点描述、触及两个或以上相互独立的子系统(如认证与计费)、任务标题里出现“和”(说明是两件事)。

输出文件

计划文档:保存到 tasks/plan.md,始终是 markdown 文件,因为设计决策、风险与开放问题不易映射到单个追踪器条目。任务列表:记录在任务清单目标中。若 tasks/ 目录不存在则创建。绝不覆盖未完成的计划:写入 tasks/plan.md 或 tasks/todo.md 之前,检查它们是否已存在且仍含未勾选任务。若是对同一工作的重新规划(用户要求修改或扩展该计划),则就地更新现有文件;若是不同工作,停止并询问。未勾选任务可能正在另一个会话中构建,不要擅自删除、覆盖或重命名现有文件,应呈现冲突让用户决定(先完成旧计划、明确丢弃,或指定新计划的存放位置)。同一规则适用于外部任务列表目标:绝不为腾出位置而批量关闭或删除另一计划的开放追踪项。

任务清单目标

任务清单目标是记录任务与检查点的位置,在此定义一次,本技能其它地方均以此为准。默认:tasks/todo.md 的清单式 markdown 文件,这是 /build 命令与其它下游工具期待的约定,除非项目另有说明。外部追踪器:若项目的智能体规则(CLAUDE.md、AGENTS.md 等)或用户指定了问题追踪器(如 GitHub Issues、Jira、Linear、bd/beads),则每个任务创建一个追踪项,而不是写 tasks/todo.md。把第四步的结构映射到追踪器字段:验收标准与验证步骤放在条目正文,依赖关系用追踪器的链接机制(bd dep add、“blocked by” 等)。第五步的检查点也记录为追踪项,若追踪器没有自然对应物,则作为计划文档中的清单。使用外部追踪器时,在 tasks/plan.md 中注明(例如“任务追踪于 Linear 项目 FOO”),以便下游步骤与未来会话知道去哪里找,并让计划文档的任务列表部分保持为追踪项 ID 或链接的有序索引,而不是重复的清单。

计划文档模板

包含以下部分:标题(实现计划:功能/项目名称)、概述(一段话总结要构建什么)、架构决策(关键决策及理由)、任务列表(按阶段划分,如第一阶段基础、基础检查点、第二阶段核心功能、核心功能检查点、第三阶段打磨、完成检查点)、风险与缓解(表格:风险、影响高/中/低、缓解策略)、开放问题(需要人工输入的问题)。当任务存放在外部追踪器时,任务列表部分保持为追踪项 ID 或链接的有序索引,而不是重复清单。

并行化机会

有多个智能体或会话可用时:可安全并行的是相互独立的功能切片、已实现功能的测试、文档;必须串行的是数据库迁移、共享状态变更、依赖链;需要协调的是共享同一 API 契约的功能(先定义契约,再并行)。

常见合理化与事实

“我边做边想”会导致混乱与返工,10 分钟规划可省数小时。“任务很明显”也要写下来,显式任务能暴露隐藏依赖与被遗忘的边界情况。“规划是开销”其实规划就是任务本身,没有计划的实现只是打字。“我能全部记在脑子里”但上下文窗口有限,书面计划能跨越会话边界与压缩。“旧的 tasks/plan.md 过时了,直接替换”则可能破坏其它会话正在构建的工作状态,应停下询问。

红旗信号

没有书面任务列表就开始实现;未询问就覆盖仍有未勾选任务的 tasks/plan.md 或 tasks/todo.md;项目已指定外部追踪器却写 tasks/todo.md(或两边散落任务);任务只说“实现该功能”而没有验收标准;计划中没有验证步骤;所有任务都是 XL 规模;任务之间没有检查点;未考虑依赖顺序。

实现前验证

开始实现前确认:每个任务都有验收标准;每个任务都有验证步骤;任务依赖已识别并正确排序;任务记录在任务清单目标(默认 tasks/todo.md);未经用户明确确认没有覆盖既有未完成计划;没有任务触及超过约 5 个文件;主要阶段之间存在检查点;人类已评审并批准该计划。

另见

验收标准是按任务定义的,回答“我们是否构建了正确的东西”,它建立在项目级完成定义之上,即每个任务在算作完成前都要达到的固定标准。参见 ../../references/definition-of-done.md。