SDD实战：如何用文档驱动，让AI写出高质量代码？

在AI编程工具日益强大的今天，许多开发者却遇到了新的痛点：AI生成的代码质量不稳定、不符合项目上下文、容易产生“幻觉”甚至引入bug。问题的根源往往不在于AI本身的能力，而在于我们向它传递需求和上下文的方式。

文档驱动开发（SDD）正是为了解决这一挑战而生。它并非一种全新的编程范式，而是一套旨在明确化、结构化人类需求，并将其作为AI编码核心输入的工作流。今天，我们便来深入探讨这套从proposal到tasks，再到最终AI编码的完整实战流程。

第一阶段：撰写Proposal —— AI的“设计蓝图”

一切始于一份高质量的Proposal文档。这不是一个简单的需求列表，而是一份结构化的、面向AI的“设计蓝图”。一份优秀的Proposal应包含以下核心部分：

上下文与目标：简明扼要地描述项目的背景、当前状态以及本次迭代的核心目标。
功能描述：使用清晰、无歧义的语言描述需要实现的功能。关键在于：像给一位能力很强但完全不了解项目背景的新同事讲解一样，提供足够细节。
技术方案与约束：明确推荐的技术栈、架构模式、必须遵守的编码规范或安全要求。这是确保AI产出符合你技术路线的关键。
验收标准：定义清晰的“完成”标准，通常是一系列可测试的场景。这是后续AI编码和测试的直接依据。

实践技巧：使用Markdown撰写，保持层级清晰。可以像Text2SQL：用自然语言操作 SQLite 数据库中展示的那样，用自然语言精确描述逻辑，AI就能更好地理解你的意图。

第二阶段：生成Task List —— 从蓝图到施工图

有了蓝图，下一步就是将其分解为具体的、可执行的任务。这个过程可以手动完成，也可以借助AI。你可以这样提示AI：

“根据以下Proposal，为我生成一个详细的、按优先级排序的开发任务列表。每个任务应独立、原子化，便于AI逐步实现。”

一个典型的Task可能如下所示：

任务ID：T001
任务描述：实现用户登录接口，接受用户名和密码，返回JWT令牌。
相关文件：src/auth/login.controller.ts, src/auth/auth.service.ts
输入/输出：定义明确的输入参数格式和返回的JSON结构。
依赖任务：无。
验收标准：1. 能通过Postman测试；2. 密码需使用bcrypt加密；3. 包含基本的错误处理。

这种高度结构化的任务列表，成为了AI编程工具最完美的输入。

第三阶段：AI编码 —— 在约束中高效执行

现在，我们进入了最激动人心的环节：让AI按照我们的“施工图”进行编码。以Cursor为例，最佳实践是：

创建新对话：为每一个独立的Task创建一个新的聊天窗口，避免上下文污染。
提供完整上下文：在对话开头，粘贴或引用相关的Proposal段落、技术规范以及当前的Task描述。
分步指令与验证：发出编码指令，待AI生成代码后，立即运行测试、检查风格，再进行下一步。不要期望一次性得到完美结果。

在AI模型选择上，像 Claude多模型性能下滑，官方紧急回应中提到的，不同模型各有优劣。对于复杂的代码生成和重构任务，建议使用Claude 3.5 Sonnet、GPT-4o等前沿模型，并密切关注其输出质量。如果项目对代码风格或架构有特殊要求，不妨先在本地部署一些模型进行测试，正如【AI】大模型本地部署与量化：Ollama、transformers、llama.cpp实践所探讨的，这能让你在完全可控的环境中验证AI的编码能力。

SDD的优势与思考

采用SDD工作流，能带来几个显著好处：

可控性与可预测性：开发过程被明确的文档和任务所驱动，AI的行为变得更有迹可循。
降低上下文丢失：每个Task的聚焦对话，最大限度地减少了AI“遗忘”关键信息的可能性。
提升代码质量：AI在明确的约束和验收标准下工作，生成的代码更符合规范，也更易于维护和测试。
知识沉淀：所有Proposal和Task文档自然成为了项目的活文档，极大方便了后续维护与交接。

当然，SDD也对开发者的前期设计能力提出了更高要求。它更像是一种将软件工程思想与AI工具深度结合的实践。当AI能够像 AI 画架构图总差点意思，archify 给它加了一条验收流水线中的工具一样，开始理解设计约束并接受验收时，文档驱动的理念就显得尤为重要。

总结而言，SDD并非要取代程序员的思考，而是通过强化文档这一“通用接口”，将人类的战略思考与AI的高效执行完美衔接起来。在AI编程的新时代，学会如何与AI对话、为AI设计，正成为一项核心技能。从下一次功能开发开始，试着写下你的第一份Proposal吧。