跳转至

基于 Harness + SDD + 多仓管理模式的 AI 全栈开发实践｜得物技术

Ch05.044 基于 Harness + SDD + 多仓管理模式的 AI 全栈开发实践｜得物技术

📊 Level ⭐⭐ | 13.9KB | entities/harness-sdd-duiwu-ai-fullstack-dewux.md

基于 Harness + SDD + 多仓管理模式的 AI 全栈开发实践｜得物技术

一、核心理念：Harness 思维 — 让 AI 模仿，而不是凭空创造

全栈 SDD 开发中，最常见也最致命的错误是：让 AI 从零开始写代码。AI 模型具备"通识能力"，给它一个需求描述，它确实能生成可运行的代码。但问题在于，这些代码往往是"外星代码"：

  • 风格不一致（命名规范、目录结构、分层方式与项目现有代码不同）
  • 复用率低（没有利用项目已有的公共组件、工具函数、请求封装）

相关实体

→ 原文存档

深度分析

1. Harness 思维的本质是"约束导航"而非"自由生成"

全栈 SDD 开发中最大的认知陷阱是把 AI 当作"灵感生成器"。得物经验的精髓在于：给 AI 一个已有的实现作为参照，让它照着复刻一份。从工程角度，这意味着你需要在代码库中主动找到最相似的已有实现，并在提示词中明确指定参考文件、接口路径和数据结构。这种"约束导航"的思路将 AI 生成的质量从"看缘分"变成"看上下文密度"。约束越精准，生成代码的采纳率越高，Review 成本越低——这直接解释了为什么凭空生成代码往往在 Code Review 阶段被大量打回。

2. 多仓工作区是 AI 全栈开发的上下文基础设施

前后端代码分仓是常态，但 AI 全栈开发的效率瓶颈恰恰在于"跨仓上下文断裂"。将两个仓库放在同一工作区后，Cursor 的 Codebase Indexing 能对工作区内所有代码进行向量化嵌入，使 AI 同时具备前后端视角。这意味着接口字段命名自然对齐、分层方式一致、数据结构前后对应。从实测对比来看，Cursor 在语义索引速度上显著优于 Claude Code，但 Claude Code 在长链路复杂任务中依赖卓越基础模型表现更稳。关键洞察是：多仓工作区不只是目录层面的合并，它是 AI 全栈开发者的"共享大脑"。

3. SDD 不仅是文档，而是 AI 与人类之间的"接口契约"

得物经验的独特之处在于：SDD 在这里不只是需求澄清工具，它是前后端 AI Agent 之间的强制对齐机制。两份 SDD 文档（前端一份、后端一份）通过接口契约和字段映射严格对应，任何不一致都会在 SDD Review 阶段被发现，而不是等到联调阶段。这种"前置于编码的对齐"从根本上降低了返工成本。openspec-propose → openspec-apply-change → openspec-archive-change 的工作流，本质上是让 AI 在一个规范化的状态机中执行，减少了 AI"自由发挥"的空间。

4. Subagent 模式将"全栈"从单兵作战变成并行工厂

Claude Code 的 Subagent 模式允许将前端、后端、Mock 三个角色注册为独立子 Agent，主 Agent 负责任务分解和调度，子 Agent 负责具体执行。这是工程组织原理在 AI 编程中的直接映射：专业分工 + 并行执行。model: sonnet 用于前端和后端代码生成（能力与速度平衡），model: haiku 用于 Mock 数据生成（成本最优）。这种分层模型选型策略，避免了在所有任务上使用最强模型的资源浪费，是 AI 工程化的重要体现。

5. 三阶段验证策略将 AI 生成的"不确定成本"前置化

AI 生成代码的最大风险不是功能错误，而是"看起来对但隐性行为不对"。三阶段验证（前端 Mock 验证 → 后端独立编译 → 前后端联调）的精髓在于：每一阶段都在一个低依赖的环境中验证核心假设。前端 Mock 自测意味着不依赖后端即可验证 UI 逻辑；mvn clean compile 验证意味着不需要完整启动服务即可验证编译正确性；联调阶段才真正验证端到端数据流。这种分阶段前置验证的策略，是将 AI 的不确定性约束在可控范围内的关键工程实践。

实践启示

1. 在给 AI 任何编码任务前，先强制执行"找相似实现"步骤

不要直接描述需求功能，而要先在代码库中定位功能最相似的已有实现，明确在提示词中写出参考文件路径、参考接口和数据结构。这一步的投入会直接决定后续代码的采纳率。工具建议：使用 grep 或 IDE 语义搜索找到相似代码，将关键片段作为提示词上下文输入。

2. 建立多仓工作区，将前后端代码在目录层面纳入同一语义空间

前端和后端工程师通常各自维护仓库，但 AI 全栈开发要求 AI 同时具备双端视角。在本地工作区建立符号链接或直接将双仓 checkout 到同一父目录下，为 AI 工具（Cursor / Claude Code）提供跨仓语义索引能力。这是 SDD 驱动开发的前提条件，也是 AI 全栈效率提升的第一杠杆。

3. 将 SDD 作为前后端 AI Agent 的强制对齐检查点，而非可选项

在开始编码前，要求 AI 输出前后端两份 SDD 文档，核对接口路径、HTTP 方法、请求/响应字段名是否完全对应。只有对齐检查通过后才能进入 openspec-apply-change 阶段。这个机制可以将大量联调阶段才发现的接口不一致问题，提前到设计阶段解决。

4. 对复杂任务使用 Subagent 模式，并为每个子 Agent 指定专用模型

将前端、后端和 Mock 角色注册为独立子 Agent，使用 model: sonnet 进行代码生成（能力和速度平衡），使用 model: haiku 进行数据生成（成本最优）。主 Agent 负责任务分解和进度调度，子 Agent 负责具体执行。这种分层架构使 AI 全栈开发从"单兵串行"变为"团队并行"。

5. 始终按三阶段验证顺序推进，不要跳过前两个阶段直接联调

每一阶段都在最低依赖环境中验证核心假设：前端 Mock 验证 UI 逻辑 → 后端编译验证代码正确性 → 联调验证端到端数据流。不要因为赶时间而跳过前端 Mock 阶段或后端编译验证——这些前置检查是 AI 生成代码的"低成本排雷区"，等到联调阶段才发现问题的返工成本远高于此。

补充：从 AI Coding 走向企业研发全链路（2026-08-25 SUPP）

得物推荐团队白忠魏 AICon 演讲（InfoQ 整理），把得物 Harness 实践从「写代码」扩展为覆盖 Plan/Do/Check/Act 的完整研发迭代飞轮。与上文 SDD/多仓模式互补：上文解决「怎么让 AI 写好代码」，本篇解决「怎么让 AI 进入完整研发链路并沉淀可复用知识」。

PDCA 七阶段护栏与全链路 AI 化

一次完整研发迭代抽象为 PDCA 循环（Plan 需求对焦/Do 开发实现/Check 效果校验/Act 分析反思）。多数团队 AI 实践集中在 Do 阶段写代码，得物希望 AI 进入完整循环。全链路 AI 化四前提：Plan 需求明确（目标边界不摇摆）、Do 减少中断（AI 持续执行不频繁提问）、Check 结果量化（黑盒靠测试结果+后验数据判断）、Act 经验复用（过去的坑不重复）。目标是提高 AI 渗透率和采纳率、缩短迭代周期（双周→周、周→天）。

Harness 是环境而不是铁笼：借《楚门的世界》比喻——真正让楚门不敢离开的不是"禁止离开"的墙而是水（环境本身）。好的 AI Harness 不是在 Prompt 堆叠"不要/禁止/必须"，而是把约束融入环境、工具和验证流程，让 AI 自然按预期方式运行；过多显性限制反而让 AI 因无法同时满足而停止执行。人仍承担技术方案评审（AI 长时间自主执行前最后的双层 Review）和 Check/Act 阶段的不可替代作用。

TPRD + Contract：把需求变成可执行边界

在 PRD 之后增加 TPRD 并引入 Contract：提前明确需求影响哪些模块、优化目标、调整方向、不能突破的技术约束。TPRD 把需求拆解为多个 EP（具体功能点），每个 EP 明确修改位置、实现目标、约束条件、实验方式、验收标准；Contract 为每个 EP 划定边界。TPRD 是后续所有阶段的围栏——目标和方向不清楚，代码写得再快也可能在错误方向努力。以"用户点击不感兴趣后少推荐类似商品"为例，技术拆解暴露大量待澄清问题（不感兴趣的是商品/品牌/类目？"少推荐"是不出现/三天内减少/几小时降频/长期降权？品牌什么条件恢复推荐？）。

Do：三类基础设施减少 AI 等待

沙箱隔离（本地可运行环境/代理/预发，让 AI 一边改代码一边执行获取日志）、UTD 单测驱动（用数据形成验证闭环，AI 根据已有+新增测试的执行结果判断修改是否可靠，如 2500→2600 用例重跑 400 不过即反思）、外部依赖 Mock（把推荐引擎/下游服务/随机条件静态化，输入稳定才能准确评估影响范围）。三类基础设施同时服务 AI 和工程师。

CDD 三层知识体系（L1/L2/L3）

为解决知识丢失、随机漂移、路径不透明三问题，得物采用 CDD（Comment-Driven Development）：先让 AI 补注释而不是补文档，注释距离代码最近、可随代码变化及时更新。把 AI Coding 所需知识组织为三层：

  • L1 不可逾越的行为边界：团队级硬约束（如必须配单测、注释率超 30%），全程生效，不解释代码如何运行而是规定必须遵守什么
  • L2 模块级设计知识：解释模块为什么这样设计、关键依赖关系，需架构师梳理，更新频率低（半年一次），处理跨模块/复杂问题时提供架构背景
  • L3 与代码直接关联的注释知识：距离代码最近的即时知识，随代码变化更新，AI Coding 最先接触，理解"这个常量什么意思""这段逻辑在做什么"

执行时不机械从 L1 读到 L3：L1 硬边界全程生效；处理具体任务先读 L3，不足再启用 L2。知识不集中在一份易过期、与代码分离的大文档，而是放在距离使用场景最合适的位置。实测：没有注释时 AI 回答准确率约 52%，补齐注释后达 90% 以上，追问次数和总体 Token 消耗下降（复杂问题单次 Token 增加因注释占上下文，但解决过程总 Token 下降）。

Highway + ATV 混合 Agent 架构与 Story

用二八定律设计混合 Agent 架构对抗黑盒与随机漂移：80% 高频问题走 Highway（确定性路径，把已明确问题全部代码化，意图路由匹配已知问题就直接执行已验证代码，不让 AI 每次重新推导），20% 长尾问题走 ATV（允许 AI 自由探索，尝试过 OpenClaw/Hermes 并提供 Skill/MCP/工具策略）。两条路径下设进化层：长尾问题经 AI+人多轮对话解决后，每天晚间反思，把当天解决的问题重新转化成代码（而非再写一段 Skill），人按 Checklist 校验后成为新 Story 进入 Highway。随问题积累 Highway 确定性能力持续增加、ATV 探索需求减少。

Story 与 Skill 的核心区别：Skill 是一段需要 AI 再次理解的能力说明（重新理解就可能产生新随机性）；Story 是经过实际问题验证并被固化为代码的执行经验（代码永远稳定，运行一万遍结果相同）。经验从"可参考"转变为"可重复执行"。

阶段性实战结果

AI 在需求链路渗透率约 30%（但非所有需求适合 AI，如只改一行配置没必要强引复杂流程）；问题排查处理时长下降约 80%（部分场景更高）——将已知问题代码化后一轮执行跑完，处理速度接近人工甚至更快。