从想法到设计文档:TaskSync Specs规格驱动开发教程(EARS需求实战指南)
从想法到设计文档:TaskSync Specs规格驱动开发教程(EARS需求实战指南)
TaskSync 是一个采用 keep-alive session 技术来降低 AI 积分成本的人机协同开发工具包,而 TaskSync Specs 正是它内置的「规格驱动开发」(Spec-Driven Development)提示词协议:把一句模糊的功能想法,通过 requirements.md → design.md → tasks.md 三件套,一步步打磨成可执行的设计文档和任务清单。本教程带你用 EARS 需求语法(Easy Approach to Requirements Syntax)实战走通全流程,全程无需手写代码。
🎯 什么是 TaskSync Specs:先想法,后代码
传统做法是「想到哪写到哪」,AI Agent 经常跑偏返工。TaskSync Specs 换了个思路:先锁需求,再谈设计,最后才列任务,每个阶段都由你审批把关(human-in-the-loop)。它由一份 Markdown 提示词驱动,核心工作流定义在 Prompt/specs-tasksync.md 中:
想法(Idea) → requirements.md(EARS需求) → design.md(设计文档) → tasks.md(任务清单) → 逐条执行
三个阶段的入口规则分别位于:
- 需求收集:Prompt/specs-tasksync.md#L16-L72
- 设计文档:Prompt/specs-tasksync.md#L74-L108
- 任务清单:Prompt/specs-tasksync.md#L111-L169
🚀 快速开始:克隆仓库并加载 Specs 协议
准备工作只需 4 步,最快 5 分钟即可跑通第一个 Spec:
git clone https://gitcode.com/gh_mirrors/tas/TaskSync
- 打开 Prompt/specs-tasksync.md,将其作为上下文提供给你的 AI IDE(如 VS Code Copilot);
- 用一句话描述你的功能想法,例如「给我的博客加一个全文搜索功能」;
- Agent 会先生成一个 kebab-case 的功能名(如
blog-fulltext-search),随后自动创建.tasksync/specs/{feature_name}/目录; - Agent 通过终端命令暂停等待你的输入,你用终端回复反馈即可,全程人机协同。
💡 如果不需要规格驱动流程,也可以换成通用版任务协议 Prompt/tasksync-v5.2.md,它适合「持续派任务」的自主开发模式。
📁 三件套目录结构:一个功能一个文件夹
每个功能的所有产物都收在同一个目录里,结构清晰、方便版本管理:
.tasksync/specs/{feature_name}/
├── requirements.md # 需求文档(EARS格式)
├── design.md # 设计文档(架构+接口+测试策略)
└── tasks.md # 任务清单(可勾选的执行步骤)
| 文件 | 内容 | 审批门禁 |
|---|---|---|
requirements.md |
用户故事 + EARS 验收标准 | 「需求看起来没问题吗?」 |
design.md |
架构、组件、数据模型、错误处理、测试策略 | 「设计看起来没问题吗?」 |
tasks.md |
编号复选框任务,逐条引用需求 | 「任务看起来没问题吗?」 |
规则很严格:未收到明确批准(如 "yes"、"approved")之前,绝不允许进入下一阶段,反馈-修改-再审批会循环进行,直到你点头为止。
✍️ EARS 需求语法实战:5 种标准句式
EARS(Easy Approach to Requirements Syntax)把自然语言需求变成结构严谨的测试式描述,AI 和人类都读得懂。TaskSync Specs 要求验收标准必须用 EARS 书写(见 Prompt/specs-tasksync.md#L27-L60),常用 5 种句式:
| 模式 | 句式模板 | 适用场景 | 示例 |
|---|---|---|---|
| 事件驱动 | WHEN [事件] THEN [系统] SHALL [响应] | 用户触发操作 | 用户点击搜索按钮时,系统应返回匹配结果 |
| 条件判断 | IF [前置条件] THEN [系统] SHALL [响应] | 特定状态下生效 | 若关键词为空,则系统应提示「请输入关键词」 |
| 组合条件 | WHEN [事件] AND [条件] THEN [系统] SHALL [响应] | 事件+条件同时成立 | 用户提交表单且字段完整时,系统应保存记录 |
| 持续状态 | WHILE [状态] THE system SHALL [响应] | 持续行为 | 索引构建期间,系统应显示进度条 |
| 无条件通用 | THE system SHALL [响应] | 始终成立 | 系统应对所有搜索请求记录日志 |
📌 实战技巧:先让 Agent 基于你的想法一次性生成初版需求(协议要求不逐条追问),你再整体审读修改,效率远高于逐条问答。
第一步 requirements.md:写一份可审批的需求文档
TaskSync Specs 对 requirements.md 有固定模板:每个需求包含一个「用户故事」+ 一组 EARS 验收标准:
# Requirements Document
## Introduction
[功能简介]
## Requirements
### Requirement 1
**User Story:** As a [角色], I want [功能], so that [收益]
#### Acceptance Criteria
1. WHEN [事件] THEN [系统] SHALL [响应]
2. IF [前置条件] THEN [系统] SHALL [响应]
以一个「登录提醒」功能为例,合格的 EARS 验收标准长这样:
- WHEN 用户连续 5 分钟未操作 THEN 系统 SHALL 显示离开提醒
- IF 用户已关闭提醒开关 THEN 系统 SHALL 跳过检查
- WHILE 提醒弹窗打开 THE system SHALL 暂停倒计时
⚠️ 注意:这个阶段不要看代码,只聚焦写需求。Agent 还应主动考虑边界情况、用户体验和技术约束,并提示你可能需要澄清的地方。
第二步 design.md:设计文档的 6 个必备章节
需求审批通过后,Agent 会基于需求开展调研,并输出包含以下固定章节的设计文档:
- Overview —— 功能总览
- Architecture —— 整体架构(建议用 Mermaid 画架构图)
- Components and Interfaces —— 组件划分与接口定义
- Data Models —— 数据模型
- Error Handling —— 错误处理策略
- Testing Strategy —— 测试策略
设计阶段有两条隐性规则值得记住:调研结果直接写进设计,不另开调研文件;每个关键设计决策都要标注理由(rationale)。如果设计过程中发现需求有缺口,Agent 会主动建议退回需求阶段补充——这正是规格驱动开发防止「边写边改」的关键机制。
第三步 tasks.md:AI 可执行的任务清单
tasks.md 是把设计「翻译」成 AI 能逐条执行的任务清单,格式为最多两级层级的编号复选框列表,每条任务必须引用具体需求编号。官方示例(Prompt/specs-tasksync.md#L176-L213):
# Implementation Plan
- [ ] 1. Set up project structure and core interfaces
- Create directory structure for models, services, repositories
- _Requirements: 1_
- [ ] 2. Implement data models and validation
- Write TypeScript interfaces for all data models
- _Requirements: 2, 3, 1_
- [ ] 3. Implement User model with validation
- Write User class with validation methods
- Create unit tests for User model validation
- _Requirements: 1_
✅ 好任务的标准:具体到「写/改/测哪个文件」、优先测试驱动、每一步都建立在前一步之上,且不包含部署、用户培训、性能采集等无法通过写代码完成的任务。
🔁 审批门禁与状态流转:为什么人必须在环
整套工作流的状态机如下(源自 Prompt/specs-tasksync.md#L245-L281):
stateDiagram-v2
[*] --> Requirements : 新建/更新
Requirements --> ReviewReq : 需求完成
ReviewReq --> Requirements : 反馈/修改
ReviewReq --> Design : 明确批准
Design --> ReviewDesign : 设计完成
ReviewDesign --> Design : 反馈/修改
ReviewDesign --> Tasks : 明确批准
Tasks --> ReviewTasks : 任务完成
ReviewTasks --> Tasks : 反馈/修改
ReviewTasks --> [*] : 明确批准
三个阶段各自支持「断点续传」:你可以直接对已有的 spec 更新需求、设计或任务,也可以随时从 tasks.md 挑一条开始执行。任务执行规则(Prompt/specs-tasksync.md#L283-L323)非常克制:
- 执行前必须重读 requirements.md、design.md 和 tasks.md 三个文件;
- 一次只做一个任务,完成后停下来等你审查,绝不自动连做;
- 完成一个任务后,必须在
tasks.md中勾选标记。
🛠️ 遇到瓶颈怎么办:3 类常见问题与对策
工作流内置了 Troubleshooting 指引(Prompt/specs-tasksync.md#L216-L243),覆盖三种典型卡点:
| 问题 | 表现 | 建议对策 |
|---|---|---|
| 需求澄清卡死 | 反复讨论原地打转 | 让 Agent 总结已确认内容、指出具体缺口,或给示例选项帮你决策 |
| 调研受限 | 拿不到所需资料 | 记录缺失信息,基于现有信息继续推进,不阻塞整体进度 |
| 设计过于复杂 | 文档越写越臃肿 | 拆分为更小的组件,优先实现核心功能,必要时退回需求阶段做优先级排序 |
📋 总结:一页上手清单
- 加载 Prompt/specs-tasksync.md 到 AI IDE;
- 丢出功能想法,等 Agent 生成
requirements.md初版; - 用 EARS 五句式检查每条验收标准,批准后进设计;
- 核对
design.md六大章节齐全且覆盖所有需求; - 审批
tasks.md,逐条执行、逐条勾选; - 任何阶段发现缺口,放心退回上一阶段——迭代正是规格驱动开发的精髓。
配合 TaskSync 的 keep-alive session 机制,这套流程还能持续保持会话活跃,进一步压低 AI 积分消耗。现在就克隆仓库,写下你的第一个功能想法吧 ⚡
