从想法到设计文档:TaskSync Specs规格驱动开发教程(EARS需求实战指南)

原创2026-11-13 12:24:282,177 阅读

从想法到设计文档: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:先想法,后代码

TaskSync Specs规格驱动开发助手Logo

传统做法是「想到哪写到哪」,AI Agent 经常跑偏返工。TaskSync Specs 换了个思路:先锁需求,再谈设计,最后才列任务,每个阶段都由你审批把关(human-in-the-loop)。它由一份 Markdown 提示词驱动,核心工作流定义在 Prompt/specs-tasksync.md 中:

想法(Idea) → requirements.md(EARS需求) → design.md(设计文档) → tasks.md(任务清单) → 逐条执行

三个阶段的入口规则分别位于:

🚀 快速开始:克隆仓库并加载 Specs 协议

准备工作只需 4 步,最快 5 分钟即可跑通第一个 Spec:

git clone https://gitcode.com/gh_mirrors/tas/TaskSync
  1. 打开 Prompt/specs-tasksync.md,将其作为上下文提供给你的 AI IDE(如 VS Code Copilot);
  2. 用一句话描述你的功能想法,例如「给我的博客加一个全文搜索功能」;
  3. Agent 会先生成一个 kebab-case 的功能名(如 blog-fulltext-search),随后自动创建 .tasksync/specs/{feature_name}/ 目录;
  4. 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 验收标准长这样:

  1. WHEN 用户连续 5 分钟未操作 THEN 系统 SHALL 显示离开提醒
  2. IF 用户已关闭提醒开关 THEN 系统 SHALL 跳过检查
  3. 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 总结已确认内容、指出具体缺口,或给示例选项帮你决策
调研受限 拿不到所需资料 记录缺失信息,基于现有信息继续推进,不阻塞整体进度
设计过于复杂 文档越写越臃肿 拆分为更小的组件,优先实现核心功能,必要时退回需求阶段做优先级排序

📋 总结:一页上手清单

  1. 加载 Prompt/specs-tasksync.md 到 AI IDE;
  2. 丢出功能想法,等 Agent 生成 requirements.md 初版;
  3. 用 EARS 五句式检查每条验收标准,批准后进设计;
  4. 核对 design.md 六大章节齐全且覆盖所有需求;
  5. 审批 tasks.md,逐条执行、逐条勾选;
  6. 任何阶段发现缺口,放心退回上一阶段——迭代正是规格驱动开发的精髓。

配合 TaskSync 的 keep-alive session 机制,这套流程还能持续保持会话活跃,进一步压低 AI 积分消耗。现在就克隆仓库,写下你的第一个功能想法吧 ⚡

登录后查看全文
TaskSync