SDD 项目开发步骤与提示词

本文以"英文网页翻译 Chrome 插件"为例，整理一套可以反复使用的 Spec-Driven Development（SDD，规范驱动开发）流程。

核心顺序：

复制代码

问题与目标
  ↓
proposal.md：做什么
  ↓
design.md：怎么做
  ↓
layouts：页面怎么组织
  ↓
tasks.md：先做什么
  ↓
project_rules.md：AI 如何执行
  ↓
一致性检查
  ↓
AI 分任务实现
  ↓
验收、文档回写、Git 提交

一、三个核心文档

文档	要回答的问题	不应该包含的内容
`proposal.md`	做什么、为什么做、范围是什么	具体代码和过早的技术实现
`design.md`	用什么技术、模块如何协作	未经需求支持的额外功能
`tasks.md`	先做什么、如何验收	模糊的"完善项目"类任务

简单记忆：

ini 复制代码

proposal = 做什么
design   = 怎么做
tasks    = 先做什么

layouts/ 和 project_rules.md 是辅助规范：前者描述页面和交互状态，后者约束 AI 的执行方式。

二、开始前：建立 Git 基线

在生成代码前先初始化仓库，并提交一个可回退的基线：

csharp 复制代码

git init
git add .
git commit -m "chore: initialize project"

每个任务完成并验收后再提交一次。不要让多个未验收任务混在同一个提交里。

三、步骤 1：生成 `proposal.md`

markdown 复制代码

我想使用 SDD 开发一个项目。

项目想法：
[描述项目想法]

请生成 docs/proposal.md，只描述需求，不设计技术实现，不编写代码。

必须包含：
1. 项目背景
2. 要解决的问题
3. 目标用户
4. 核心目标
5. MVP 功能范围
6. 用户操作流程
7. 输入和输出
8. 异常场景
9. 非功能需求
10. 明确不做的事情
11. 验收标准

要求：
- 明确区分"必须做"和"暂不做"
- 每条需求都必须可以验证
- 不要引入我没有提出的功能
- 完成后立即停止
- 只修改 docs/proposal.md，不创建代码文件

当前项目的需求描述示例：

css 复制代码

我想做一个 Chrome Manifest V3 扩展。

用户在英文网页中点击扩展按钮后，插件提取当前页面的主要文章，转换为 Markdown，调用用户配置的大模型翻译成中文，并在侧边栏以流式打字机效果展示。

MVP 必须包含：提取标题、作者、原文链接和正文；HTML 转 Markdown；英译中；流式展示；停止、复制和下载；保存最近一次结果。

明确不做：翻译历史、批量翻译、离线翻译、中英对照、多语言方向、图片下载。

四、步骤 2：补充需求边界

bash 复制代码

请阅读 docs/proposal.md，检查需求边界是否足够明确。

重点补充以下内容是否提取：广告、弹窗和 Cookie 提示、导航栏、侧边栏、页脚、推荐文章、评论区、iframe 内容、动态加载列表、非文章页面。

请只更新 docs/proposal.md，不编写代码。补充完成后立即停止，并列出新增的边界条目。

五、步骤 3：生成 `design.md`

diff 复制代码

请阅读 docs/proposal.md，根据需求生成 docs/design.md。

design.md 只描述"怎么做"，不编写具体业务代码。

必须包含：技术选型及理由、总体架构、模块划分和职责、端到端数据流、核心数据结构、关键接口设计、状态流转、错误处理、权限安全和隐私、性能考虑、降级方案、目录结构、需求与技术方案的对应关系。

要求：
- 每个设计必须能对应 proposal.md 中的需求
- 不设计 proposal.md 中没有的功能
- 明确 MVP 能力和后续预留能力
- 关键技术选型说明为什么采用、为什么不采用其他方案
- 如果需求不清楚，先列出问题，不要自行猜测
- 只修改 docs/design.md，完成后立即停止

当前项目的技术约束可以追加：

bash 复制代码

技术约束：Chrome Manifest V3、TypeScript、React、Vite + @crxjs/vite-plugin、@mozilla/readability、turndown + turndown-plugin-gfm、OpenAI SDK 兼容模式、chrome.storage.local、md-wx。

除非 design.md 说明必要性，不要新增框架或依赖。

六、步骤 4：生成页面布局文档

diff 复制代码

请阅读 docs/proposal.md 和 docs/design.md，生成页面布局设计。

要求：
- 使用 ASCII 图描述页面结构
- 按页面分别保存到 docs/layouts/
- 页面内按功能模块划分
- 描述空状态、加载中、成功、错误和停止状态
- 标出按钮在什么状态下可用或禁用
- 只设计 proposal.md 中要求的功能
- 不编写 React、CSS 或其他代码

请生成 docs/layouts/示意图-侧边栏.md 和 docs/layouts/示意图-设置页.md，完成后立即停止。

七、步骤 5：生成 `tasks.md`

diff 复制代码

请阅读 docs/proposal.md、docs/design.md 和 docs/layouts/。

根据这些文档生成 docs/tasks.md，把设计拆成可以逐个实现和验收的开发任务。

每个任务必须包含：任务编号、任务名称、优先级、前置依赖、涉及文件或模块、具体工作内容、完成标准、验证方式、是否可以并行。

要求：
- 从基础设施到核心功能，再到界面和最终验收排序
- 一个任务只解决一个清晰问题
- 不要出现"完善项目""优化体验"这类不可验收的任务
- 完成标准必须可以通过命令、测试或手工操作验证
- 严格遵守 proposal.md 的范围
- 只修改 docs/tasks.md，完成后立即停止

建议的任务阶段：

复制代码

T0 项目初始化、依赖和入口
T1 正文提取、图片处理、Markdown 转换
T2 Service Worker 和按需注入
T3 LLM 客户端、提示词、存储、错误处理
T4 设置页
T5 侧边栏、状态机、流式展示、下载
T6 体验打磨、打包和最终验收

八、步骤 6：生成 `project_rules.md`

diff 复制代码

请阅读 docs/design.md 和 docs/tasks.md，生成 docs/project_rules.md。

这份规则给后续 AI 开发使用，重点约束高层行为，不重复具体实现细节。

必须包含：任务范围控制、单一任务原则、任务执行指令格式、完成标准和验收要求、异常处理和依赖处理、语言与框架约束、包管理规则、目录结构和模块隔离、命名与代码风格、安全和隐私红线、文档同步规则、Git 提交规则。

核心要求：
- AI 一次只执行一个任务
- 不得擅自扩展任务范围
- 发现设计与实现不一致时，先同步文档
- 完成后必须对照验收标准自检
- 只修改 docs/project_rules.md，完成后立即停止

九、步骤 7：文档一致性检查

bash 复制代码

请检查 docs/proposal.md、docs/design.md、docs/tasks.md、docs/layouts/ 和 docs/project_rules.md 的一致性。

重点检查：proposal 中的每个功能是否都有设计方案；design 中的每个模块是否都有任务；tasks 中的每个任务是否能追溯到需求；页面布局是否覆盖交互状态；是否存在设计了但需求明确不做的功能；技术选型、目录名和任务文件名是否一致；验收标准是否可执行。

不要修改代码。请先列出问题，再给出建议的文档修改顺序。

十、步骤 8：执行单个开发任务

diff 复制代码

请阅读 docs/proposal.md、docs/design.md、docs/tasks.md、docs/layouts/ 和 docs/project_rules.md。

现在只执行 tasks.md 中的 T0.1：[任务名称]。

要求：
- 只完成 T0.1，不执行其他任务
- 修改前先检查当前项目和 Git 状态
- 复用现有代码、类型和依赖
- 不新增设计文档未批准的依赖
- 不修改无关文件
- 完成后运行 T0.1 要求的最小验证
- 对照完成标准逐项验收
- 汇报修改文件、命令结果和剩余风险
- 完成后停止，等待确认

十一、步骤 9：验收、回写和提交

每个任务都按照这个顺序收尾：

复制代码

实现代码 → 运行验证 → 对照 tasks.md 验收 → 必要时更新文档 → 更新任务状态 → Git 提交

验收提示词：

bash 复制代码

请对照 docs/tasks.md 中的 T0.1 完成标准检查当前实现。

请输出：已通过的验收项、未通过的验收项、使用过的验证命令及结果、是否需要更新 proposal.md/design.md/tasks.md、当前任务是否可以提交。

只做检查，不继续实现下一个任务。

验收通过后：

sql 复制代码

git status
git diff --check
git add <本任务相关文件>
git commit -m "feat: complete T0.1 project setup"

十二、需求变化时的处理方式

新需求不能直接跳到代码：

复制代码

新需求 → 分析 proposal 影响 → 分析 design 影响 → 调整 tasks → 实现 → 重新验收

提示词：

bash 复制代码

项目出现了新需求：[描述新需求]

请不要直接修改代码，先分析它对 docs/proposal.md、docs/design.md、docs/tasks.md 和现有代码模块的影响。

请输出：是否属于当前项目范围、需要修改哪些文档、对架构的影响、新增或调整哪些任务、对已有功能的影响、推荐的实施顺序。

十三、当前项目状态

本项目是英文网页翻译 Chrome 插件，规范文件为：

bash 复制代码

docs/proposal.md       需求
docs/design.md         技术架构
docs/layouts/          页面布局
docs/tasks.md          任务拆分
docs/project_rules.md  AI 开发规则

已完成：需求、边界、技术架构、页面布局、任务拆分、项目规则和 T0.1 项目脚手架。后续应以 tasks.md 的实际状态为准继续推进。

十四、最短版流程

markdown 复制代码

1. 写 proposal：做什么
2. 写 design：怎么做
3. 写 layouts：页面怎么组织
4. 写 tasks：先做什么
5. 写 project_rules：AI 如何执行
6. 检查文档一致性
7. AI 一次执行一个任务
8. 验收任务
9. 回写文档
10. 提交 Git

SDD 的核心不是多写几份 Markdown，而是让需求、设计、任务、代码和验收可以相互追溯。聊天窗口只是执行入口，文档和 Git 才是项目的长期记忆。

SDD 项目开发步骤与提示词

一、三个核心文档

二、开始前：建立 Git 基线

三、步骤 1：生成 proposal.md

四、步骤 2：补充需求边界

五、步骤 3：生成 design.md

六、步骤 4：生成页面布局文档

七、步骤 5：生成 tasks.md

八、步骤 6：生成 project_rules.md

九、步骤 7：文档一致性检查

十、步骤 8：执行单个开发任务

十一、步骤 9：验收、回写和提交

十二、需求变化时的处理方式

十三、当前项目状态

十四、最短版流程

三、步骤 1：生成 `proposal.md`

五、步骤 3：生成 `design.md`

七、步骤 5：生成 `tasks.md`

八、步骤 6：生成 `project_rules.md`