create-spec

创建功能规格说明

将规划讨论转换为结构化的规格说明文件夹，以支持多个 Agent 并行实现。规格说明会将功能拆分为相互独立的任务文件——每个文件都足够详细，编码 Agent 无需阅读其他内容，就能直接着手实现。

关键在于：放在单个文件中的实现计划，要么过于庞大，超出上下文窗口的限制；要么过于浅显，无法独立执行。将计划拆分为多个任务文件，并在每个文件中提供完整上下文，就能让多个 Agent 并行工作，同时确保每个 Agent 的上下文聚焦于当前任务。

适用场景

• 讨论完需求和技术细节的规划对话结束后
• 用户要求创建规格说明、规划功能或拆分任务时
• 用户想为多个 Agent 并行实现做好准备时

操作说明

第 1 步：收集需求

如果对话中已有规划上下文（例如讨论过需求、确定了技术决策、概述了架构），就提取全部内容。完整回顾整个对话，确保没有遗漏——规格说明是唯一事实来源，未在此处记录的内容都会丢失。

如果没有规划对话，就采访用户：

• 此功能的作用是什么？为什么重要？
• 验收标准是什么？
• 已确定哪些技术约束或决策？
• 涉及哪些文件、API、架构或模式？

第 2 步：为功能命名

选择一个能清楚标识功能的 kebab-case 名称（例如，add-user-auth、migrate-to-postgres、dashboard-redesign）。该名称将作为 specs/ 下的文件夹名称。

第 3 步：拆分任务

将实现拆分为原子任务。每个任务都应：

• 能由一个 Agent 在单次编码会话中完成
• 范围清晰、具体（每个任务只关注一个方面）
• 完成后能产出可运行、可测试的代码
• 在同一波次内，与其他任务修改的文件不重叠

请仔细把握粒度。粒度太粗，Agent 就无法并行工作；粒度太细，任务间切换上下文的开销就会过大。一个合适的任务通常围绕单一关注点创建或修改 1-5 个文件。

除非用户明确要求，否则不要添加测试任务（单元测试、端到端测试）。

第 4 步：构建依赖关系图

针对每个任务，确定：

• 依赖项：必须先完成哪些任务，此任务才能开始
• 后续依赖任务：哪些任务必须等此任务完成后才能开始

没有依赖项的任务属于第 1 波次。依赖项均属于第 1 波次的任务属于第 2 波次，以此类推。同一波次内的所有任务都可以并行执行。

分配波次时，请确认同一波次内的任务不会修改重叠的文件。如果同一波次内的两个任务会修改同一个文件，就将其中一个移到后续波次——在同一个分支上并行工作的 Agent 无法安全地修改同一个文件。

第 5 步：创建规格说明文件夹

在 specs/{feature-name}/ 下创建以下结构：

specs/{feature-name}/
├── README.md
├── requirements.md
├── action-required.md
└── tasks/
    ├── task-01-{name}.md
    ├── task-02-{name}.md
    └── ...

在编写每个文件之前，先阅读 references/ 中的模板：

• references/readme-template.md — 用于 README（依赖关系图、波次表、状态跟踪）
• references/task-template.md — 用于每个任务文件（内容自包含，包含所有上下文）
• references/requirements-template.md — 用于需求文档
• references/action-required-template.md — 用于人工操作步骤

任务文件按拓扑顺序使用补零的两位数字前缀编号：先列出第 1 波次的任务，再列出第 2 波次的任务，以此类推。同一波次内的顺序可以任意安排，但应保持稳定。

步骤 6：编写自包含的任务文件

这是最重要的一步。每个任务文件都是编码 Agent 在开始实现前唯一会阅读的内容。文件必须包含 Agent 所需的一切：

• 描述：要构建什么，以及它在当前情境下为何重要
• 依赖上下文：此任务需要哪些前序任务的产出（用文字概述，而不只是列出文件名）。Agent 不应需要阅读其他任务文件。
• 技术细节：CLI 命令、代码片段、架构、文件路径、环境变量、API 端点——规划对话中的所有实现细节
• 要创建或修改的文件：明确列出文件，并说明每个文件的用途
• 验收标准：具体且可验证的条件

以全新的视角审阅每个任务文件：一个从未看过规划对话的 Agent，能否只凭此文件正确完成实现？如果不能，请补充缺失内容。

步骤 7：提取人工操作事项

找出所有需要人工操作的步骤（创建账户、设置 API 密钥、配置 DNS、设置环境变量、注册第三方服务等）。按时间分组（实现前／实现期间／实现后），将这些步骤写入 action-required.md。如果没有此类步骤，请注明“无需人工操作。”

步骤 8：向用户报告

创建规范后，显示：

Feature specification created at specs/{feature-name}/

Files created:
- README.md (dependency graph, {N} waves, {T} tasks)
- requirements.md
- action-required.md
- tasks/ ({T} task files)

Wave breakdown:
- Wave 1: {count} tasks (parallel) — {brief description}
- Wave 2: {count} tasks (parallel) — {brief description}
- ...

Next steps:
1. Review action-required.md for tasks you need to complete manually
2. Review the requirements and task files
3. Use /implement-feature to start parallel implementation

关键规则

• 每个任务文件都必须完全自包含——这是这种规范结构的全部意义。只阅读该文件的编码 Agent 必须确切知道要做什么。
• 记录规划对话中的所有技术细节。规范是唯一可信来源——CLI 命令、架构、代码片段、文件路径、环境变量、API 端点。任何未记录在此处的内容都会丢失。
• 同一波次中的任务不得修改有重叠的文件。在同一分支上并行工作的 Agent 无法安全地修改相同文件。
• 保持任务原子性——每个任务只涉及一个关注点。如果一个任务需要修改超过 5-7 个文件，请考虑拆分。
• 除非用户明确要求，否则不要创建测试任务。
• 按拓扑顺序为任务文件编号（先第 1 波，再第 2 波，以此类推），方便快速查阅。