核心理念Harness思维 --- 让AI模仿而非凭空创造全栈SDD开发中最常见且致命的错误是让AI从零开始写代码。AI模型虽有“通识能力”能根据需求描述生成可运行代码但这些代码常是“外星代码”存在风格不一致、复用率低、采纳率低等问题导致Review和返工成本更高。Harness约束思维的本质是给AI一个已有实现作为参照让它复刻而非凭空创造就像让新入职工程师参照模块风格写代码这样能更快产出符合团队规范的代码。在提示词中体现Harness也很重要。不推荐让AI凭空创造如“请实现一个结束语管理的CRUD接口”而推荐使用Harness约束如“请参照现有‘场景欢迎语’功能后端接口 /api/v1/feature/list前端入口FeatureTable/index.tsx:53 - 58实现‘结束语’功能。数据结构、分层方式、命名风格都保持一致。新增场景codecategoryCode SCENARIO_CLOSING”。约束越精准生成代码的可用性越高。全栈工作区搭建与Codebase Indexing为什么要搭多仓工作区呢前后端代码通常分布在两个独立仓库分开打开时AI生成后端接口看不到前端调用方式生成前端代码看不到后端返回结构接口字段易对不上。将前后端代码放在同一工作区有三个核心价值Codebase IndexingCursor对工作区内所有代码进行向量化嵌入建立语义索引AI能跨仓库理解代码关系生成质量大幅提升上下文完整AI能同时看到前后端代码接口字段、命名风格自然对齐SDD文档集中管理前后端SDD文档在同一工作区便于接口契约对齐。Cursor的Codebase Indexing会对工作区内代码进行向量化嵌入建立语义索引。这意味着当问AI“场景欢迎语是怎么实现的”它能通过语义检索自动找到相关的Controller、Service、前端组件当让AI“照着欢迎语写结束语”它会检索到欢迎语的前后端完整实现链路而不只是单个文件。前后端放在同一工作区Codebase Indexing覆盖两侧代码AI生成后端接口时能参考前端调用方式生成前端代码时能参考后端返回结构。不过Cursor打开工作区后首次索引可能需要几分钟可以在Cursor设置查看索引进度确保索引完成后再让AI生成代码效果会更好。在全栈AI开发场景下Cursor和Claude Code两款工具各有侧重。实测对比情况如下此处有相关对比图。以上述需求为例工作区结构如下.claude和.cursor中已对SDD能力进行初始化此处有相关工作区结构图片。SDD驱动的全栈代码生成流程全栈SDD与纯前端/纯后端SDD不同它需要生成两份SDD文档前端一份、后端一份接口契约要对齐前端SDD中的接口调用与后端SDD中的接口定义必须严格对应字段映射也要一致前端VO中的字段名与后端返回的JSON字段名一一对应。以下是经过实践验证的全栈SDD生成提示词模板这是一个前后端全栈开发工作区需要你设计技术接口方案同时开发前后端项目首先你需要cd到对应前后端应用目录中创建sdd文件所以你需要生成两份sdd文档之后我会启动两个agent分别实现在生成之前如果你需要确认某些细节你应当先确认后生成sdd文档。前端应用service - frontend/sdd - propose feature/your - feature - name前端修改入口参考FeatureTable/index.tsx:53 - 58 columns/index.tsx后端应用service - backend/sdd - propose feature/your - feature - name后端修改入口参考接口/api/v1/feature/list需求内容附上需求文档或描述并提供前后端需求点清单关键要素解读此处有相关解读图片。前后端需求点清单分工示例前端需求功能点主要是新增一个后台管理页面的tab涉及搜索、展示、配置新增、删除等利用内部SDD文档工具从PRD描述和文档图片中提炼出需求点。左侧导航新增“结束语”Tab右侧新增结束语列表页字段有结束语内容、结束语描述、优先级、更新人、更新时间、操作列。新增/编辑弹窗字段有结束语描述、生效日期、生效时段、结束语话术等。还有拖拽排序功能点击“排序”按钮进入排序状态拖拽调整顺序后点击“保存”生效此处有相关图片。后端功能由AI根据前端需求描述自主设计数据表和接口。AI在生成SDD前需要明确的关键设计问题包括主键设计即如何设计主键字段前端发起编辑、删除时需要传递该字段优先级自增逻辑优先级应基于当前数据条数自增由后端自动处理排序如何高效更新批量排序时如何设计接口避免N次单条更新嵌套对象如何建表参考已有的“场景欢迎语”接口入参中存在嵌套子对象此类子对象应拆分到多张表还是序列化为JSON字段存单张表isNextDay字段含义次日逻辑的具体含义是什么前端时段选择器中“次日”勾选状态如何映射到该字段列表回显设计列表接口需要返回完整的回显数据无需单独提供详情接口。把这份清单放进提示词前端侧能给AI完整的UI细节避免它做“最简实现”后端侧能把模糊的设计问题提前暴露让AI在写SDD之前先回答这些问题这正是Harness思维的体现。一次完整的全栈SDD生成会产出以下文档前端SDDproposal.md --- 需求提案描述前端要做什么spec.md --- 技术规格组件设计、接口调用、状态管理tasks.md --- 任务拆分每个task对应一个可执行的代码变更。后端SDDproposal.md --- 需求提案描述后端要做什么spec.md --- 技术规格接口设计、数据库设计、分层架构design.md --- 详细设计类图、字段映射、SQLtasks.md --- 任务拆分。SDD指令使用说明典型工作流示例入门引导1. openspec - onboard首次不熟悉才走引导完整步骤2. openspec - continue - change提示你下一步要干嘛3. openspec - ff - change快进。场景A初次开发1. openspec - explore调研脑暴2. openspec - propose ...生成设计3. openspec - apply - change写代码4. openspec - verify - change自测校验代码与SDD文档是否对应5. openspec - archive - change收尾归档。场景B二次开发修改迭代已有功能1. openspec - explore定位旧代码/旧spec2. openspec - propose 修改...生成变更Spec3. openspec - apply - change应用修改4. openspec - verify - change验证回归5. openspec - archive - change归档。场景C二次修改需求变更1. openspec - explore调研脑暴2. openspec - propose ...生成设计3. openspec - apply - change写代码4. 发现有问题就用openspec - explore修改提案5. openspec - explore 需求变更xxx二次脑暴6. openspec - propose 根据探索结果修改提案7. openspec - apply - change执行提案中变更内容8. 【可选】openspec - verify - change验证是否有未完成任务9. openspec - archive - change归档。场景D季度大清理1. openspec - bulk - archive - change --before 2023 - 12 - 31批量归档。总的来说上述流程相对繁琐保持最简使用想openspec - propose、做openspec - apply - change、收openspec - archive - change即可此处有相关图片。多Agent协作前后端并行开发为什么需要多Agent呢SDD文档生成完毕后前后端的代码生成工作相互独立前端根据前端SDD生成组件和页面后端根据后端SDD生成Controller/Service/Repository这天然适合并行执行。Cursor支持多个AI编程模式并行工作这是其核心优势之一。全栈开发场景下Tab 1负责前端代码生成Tab 2负责后端代码生成两个Agent同时运行、互不阻塞。Claude Code内置了Subagent子代理机制适合命令行场景下的多任务并行。Claude Code提供了两种多Agent协作模式下个迭代再实践一下Team模式和普通Subagent的差别此处有相关图片。Subagent的核心配置项如下{ description: 前端代码生成专家, tools: [Read, Edit, Write, Bash, Grep], permissionMode: bypass, model: sonnet, skills: [前端编码规范]}全栈开发场景中的应用如下主Agent你在对话的Claude Code ├── Subagent 1读取前端SDD生成前端代码 │ ├── model: sonnet │ ├── tools: Read, Edit, Write, Bash │ └── 任务按照tasks.md生成前端组件 │ ├── Subagent 2读取后端SDD生成后端代码 │ ├── model: sonnet │ ├── tools: Read, Edit, Write, Bash │ └── 任务按照tasks.md生成后端接口 │ └── Subagent 3可选生成接口Mock数据 ├── model: haiku └── 任务根据后端SDD spec.md生成Mock多Agent实践建议此处有相关图片。前后端联调Mock数据与分阶段验证直接联调往往是效率最低的验证方式推荐采用三阶段分离验证阶段1前端Mock验证 前端代码 Mock数据 → 本地跑通页面交互验证UI逻辑阶段2后端独立验证 后端代码 → mvn clean compile → 构建通过 → 部署到测试环境阶段3前后端联调 前端连接测试后端接口 → 端到端验证这样做的好处是前后两端的问题可以提前发现、分别修复避免在联调阶段才暴露节省大量排查时间。Mock数据编写要点Mock数据质量直接决定前端自测的有效性有三个关键要求字段名和字段类型必须与后端SDD中定义的完全一致参考已有接口的真实返回数据作为模板而不是随意构造覆盖边界场景空列表、单条数据、多条数据、各字段极值如空字符串、超长字符串、null值等。后端独立构建验证后端代码不需要在本地完整启动整个Java服务只需编译通过即可验证大部分代码问题。# 切换到Java 8环境根据项目实际JDK版本调整sdk use java 8# 进入后端项目目录cd service - backend# 编译验证无需本地启动整个服务mvn clean compile编译通过意味着语法正确、依赖关系正确、类型兼容是部署前最快速的验证手段。前后端联调步骤后端代码提交并部署到测试环境前端本地开发服务通过代理配置将API请求指向测试后端地址前端请求携带功能路由标识确保请求路由到对应的测试环境而不是其他人的环境逐接口验证重点关注字段映射、状态处理、错误场景。警惕SDD陷阱测试如何介入全栈研发SDD不等于需求文档这是AI全栈开发中最容易被忽视的问题。SDD描述的是“技术上怎么实现”而不是“业务上所有的行为”。AI在模仿参考代码生成新代码时会自动复刻很多隐性功能这些功能在参考代码中存在AI认为是“理所当然”的所以没有写进SDD文档但实际上已经悄悄实现了。隐性功能示例示例1变量/表单清除前端// AI模仿欢迎语弹窗生成结束语弹窗时自动复刻了“关闭弹窗时清空表单”的逻辑const handleClose () { form.resetFields(); // ← 隐性功能关闭时清空表单字段 setContentList([]); // ← 隐性功能清空内容列表状态 setVisible(false);};示例2数据格式转换后端// AI模仿已有接口自动添加了业务逻辑判断if (extendInfo.getIsPermanent()) { extendInfo.setEffectiveDate(null); // ← 隐性永久有效时自动清除开始日期 extendInfo.setExpirationDate(null); // ← 隐性永久有效时自动清除结束日期}示例3默认值补齐后端// AI自动实现了“优先级自增”逻辑SDD文档中未提及if (Objects.isNull(req.getSequence())) { req.setSequence(getMaxSequence() 1); // ← 隐性新增时优先级自动递增}这些隐性功能可能正是需要的也可能完全不符合当前需求问题在于你不知道它们的存在。给测试同学的实操建议把SDD文档当作起点而不是终点。重点Review AI生成的代码问自己一个问题“参考功能有哪些隐性行为这些行为在新功能中是否合适”此处有相关图片。综合效益与总结通过本文介绍的“Harness SDD 多Agent”全栈开发方法论在实际项目中验证的效益如下采纳率提升相比传统前后端分离开发工作区模式可以很好地把项目需求上下文放到一起更便于AI理解需求设计编码尤其通过Cursor的索引能力进一步提高采纳率以及功能实现的完整性。耗时降低SDD模式下AI分析需求后产生两套SDD文档使得前后端开发完全可以并行以本需求为例原本前后端2 4人日需求在这种模式下算上环境准备、踩坑时间、联调自测时间压缩至3人日提效50% 。调试环节不依赖阻塞前端功能在全栈开发的视野下已知数据结构可mock数据自测后端功能通过远程调试的方式支持本地打点调试最终一并上测试环境验证能够明确知道问题来自于前端还是后端AI全栈学习成本骤降只需掌握入门级别前后端知识即可介入简单全栈需求开发提高业务域需求吞吐率。本文介绍的全栈AI开发方法论核心可以用一张图概括此处有相关图片。本文基于实际全栈开发项目经验整理所有代码示例已脱敏处理使用通用命名替代业务专有名词如有问题欢迎交流探讨。