你越来越熟练地把活甩给 AI 了。需求丢过去它给你写 controller需求丢过去它给你搭 domain需求丢过去它给你跑 JaCoCo。可你最近有没有这种感觉——同一个约束你跟它讲了三遍、五遍、十遍它还是按它印象里的样子写不是 AI 学不会是 AI 每次都是从零开始学。它不知道你们用 Java 17 还是 Java 21、不知道你们 Header 全小写、不知道你们 domain 层零 Spring、不知道你们 P0 红线包括 SSO Cookie 必须 JS 写。它每接一个新会话、每开一个新分支都把这些事重听一遍。你觉得它学得越来越快——是的快到把你每次口头告知的技术约束全都重新发明了一遍。这一篇专门解决这件事——给 AI 立第三道秩序。也就是 SDD。不是教你 SDD 是什么。你可能早就看过规范驱动开发Spec 驱动这类词知道要把规范写下来。你缺的不是这个动作是怎么让规范真正长期挂在 AI 工作台里让工程师只聊业务、让 AI 自动按规范落地、不再每次重复告知。这一篇不讲 SDD 的全套理论二十多年前的方法论一篇讲不完只讲AI 时代最该抓住的那一段——Spec 端打底、Story 端交付、留白区让 AI 飞。三件事讲清楚AI 协作的第三道秩序分水岭就立起来了。下面我们一段一段拆。一、AI 协作的最大痛点——工程师每次都要重复告知技术约束你可能觉得这标题反了——AI 越来越聪明约束告知应该是越来越轻松才对啊。AI 上下文窗口越来越大、记忆能力越来越强、Agent 循环越来越稳以前得说三遍的事现在一遍它就记住了。听起来很有道理。可真实现场不是这样。我先把现场摆给你看。我过去一年在多个 AI 协作项目里看到的剧本几乎都是这么演的。第一个会话你跟 AI 说帮我写一个Tenant聚合根。它给你整出 constructor、factory、setter、equals、hashCode整整齐齐一坨。你打开一看——好家伙Tenant直接调tenantRepository.save()domain 层 import 了 Spring。你心里咯噔一下提醒它domain 层不能 import Spring。它点点头“好的下次注意。”第二个会话你又拉了一个新会话让它写另一个聚合根。它又一次凭印象写——上次会话的提醒它早就忘了domain 层又 import 了 Spring。你又提醒一次。它又点点头。第三个会话你新开一个分支让它写一个新的限流器。它还是 import 了 Spring还是在 domain 层调了 Redis 客户端还是在 Service 层用了RestTemplate该用 WebClient。你又、又、又提醒一遍。第六个月你打开 PR 列表发现——同一个约束domain 零 Spring你跟 AI 讲了不下二十遍。每一遍它都点头、每一遍它下次又忘。约束没有沉淀下来约束成了你每次会话必带的开场白。这不是 AI 太笨这是约束没有被长期挂载。AI 没有团队约束的本能。你看到 domain 层不该有 Spring立刻会想起框架依赖倒置原则 六模块分层铁律 AGENTS.md P0 红线——这一整套判断是多年工程纪律和团队规范堆出来的。AI 没有这堆纪律。它看到的是字符、命名、文件位置、上下文里你最近一次提的偏好。它能写语法正确的代码但它写不出团队规范上的对。更扎心的是它不是在犯错它是在用最快的速度忘掉你跟它讲过的一切。会话一关记忆清零下次开工又从语料库平均值那个工程师开始写。所以这个反直觉的结论你得先吞下去——AI 协作的最大痛点不是 AI 不够聪明是工程师每次都要重复告知技术约束——SDD 就是要让这件事不再发生。这一句你得记牢。它是这一篇的底色。Spec 端把团队规范长期挂载AI 训练时吸收记忆Story 端把工程师对话聚焦到业务目标——聊天即交付是 SDD 双端的终极目标。这两句合起来就是 AI 时代 SDD 的真正价值——不是教你写更全的规范文档是给 AI 立一套它开机就读得到的技术规范基础设施。为什么这件事过去没人提你可能想问规范、规约、约束是软件工程的老生常谈为什么二十多年过去今天才突然被 AI 时代捧成第三道秩序分水岭因为过去不需要。2002 年到 2022 年那段时间团队规范是写在 wiki、写在 onboarding 文档、写在老员工脑子里——新人入职看一遍、老员工带一遍、code review 复审一遍。流程跑二十年团队规模从 5 人到 50 人规范能磨平、传递能到位。AI 时代情况反过来了。AI 进来之后“老员工这个角色被 AI 替代了——你不再带新人 onboarding你带的是 AI 读规范文档。可 AI 不会看一遍 wiki 就记住”AI 每次会话都从零开始。你不能把团队规范写进 wiki 就指望 AI 自动遵循——AI 读 wiki 跟读小说一样扫一遍就忘。每一次新会话都得重新告知。每一次新分支都得重新对齐。这件事靠口头告知磨不平——你不能让团队里每个工程师、每次新会话、每次新分支都重新告知一次domain 零 Spring、Header 全小写、P0 红线包括 SSO Cookie 必须 JS 写。怎么办把规范写进文档还不够得把规范焊进 AI 工作台。SDD 在 AI 时代的真正用法是把团队规范长期挂在 AI 训练阶段——AI 开工前自动读、自动吸收、自动记成自己的团队习惯工程师只聊业务、不再重复告知。这件事过去没人提是因为过去没有 AI 需要读这份规范。今天有 AI 进场了规范才变成必须长期挂载的基础设施。所以 SDD 的价值从来没变——把团队规范沉淀下来。变的是它今天服务的对象过去给老员工 onboarding今天给 AI 训练。过去是文档备查今天是 AI 开机就读。那到底怎么立这套规范基础设施长什么样下一节我们正式讲 SDD 双端是什么。二、什么是 SDD 双端——Spec 端打底 Story 端交付两端各管一段我们把 SDD 摆到桌面上。SDD 全名 Spec-Driven Development规范驱动开发。这不是什么新方法论——二十多年前软件工程就有先把规范写下来再写代码的实践。今天在 AI 时代SDD 突然从好习惯升级成双端架构——原因就是上一节说的AI 没有团队约束的本能得靠规范长期挂载。这套双端架构的骨架由两件事组成——Spec 端训练阶段人全权沉淀 Story 端交付阶段工程师唯一入口。两件事就是 SDD 在 AI 时代的核心骨架。把它们讲清楚你就看懂了 SDD 在 AI 时代的一半。下面我们按先讲为什么需要它再讲它是什么的顺序拆。整套讲述我用厨房两本手册作主线比喻——这套比喻不是装饰是帮你从厨房的物理直觉直接推出 SDD 的工程结论。一句话故事为什么团队规范会漏我先给你讲一个真实的小故事。有一次我跟一个团队的架构师聊他们的 AI 协作流水线。他说“我们团队规范写得很全——六模块分层、AGENTS.md、coverage-rules、P0/P1/P2文档加起来 200 多页。”我点点头问“那 domain 层 import Spring 这种事AI 还会犯吗”他叹口气“会。”“为什么”“因为 AI 每次新会话都从零开始。规范文档它读一遍就忘下次开工又回到它’印象里’的工程师那套写法。我让团队每个工程师每天提醒 AI 不要 import Spring——可工程师们又不是复读机提醒三遍五遍他们自己也烦最后变成没人提醒AI 该 import 还是 import。”更糟的是团队花了三个月写的规范文档AI 完全不读——它扫一眼就过去了连SSO Cookie 必须 JS 写这种最关键的 P0 红线都没记住。你听出问题在哪了吗规范文档有了可 AI 不读、读了也记不住。规范成了贴墙上的告示AI 路过看一眼、走过去了。传统开发里这种漏靠老员工盯、靠 code review 拦、能磨平。AI 时代磨不平。AI 写代码的速度是人工的几十倍reviewer 看不完AI 不读规范文档reviewer 想拦也拦不住——PR 提上来才发现问题已经晚了。怎么办两本手册Spec 端 Story 端SDD 在 AI 时代的解法是把团队规范 工程师对话切成两个完全独立的端——Spec 端和 Story 端。两端各管一段AI 只跟这两端打交道。我用厨房两本手册作最直觉的比喻。一家像样的餐厅后厨一定有两本手册——第一本手册挂在墙上叫团队操作手册 设备清单——封面印着Spec 端。这本手册长期挂在厨房墙上记录团队的整套技术规范灶具怎么用、刀具怎么选、调料怎么配、菜品有哪些标准做法。新人入职第一天主厨指着手册说“这本先读透后续做菜不用每次问师傅。”这本手册对应 SDD 的Spec 端——AI 工作台前置打底人在训练阶段全权沉淀、AI 训练时吸收记忆。规范不是贴墙上的告示是新人入职必读的入门教材。第二本手册是服务员手里的叫顾客点菜单——封面印着Story 端。这本手册没有技术细节只记录顾客要什么——“我要一份七分熟的牛排”、“我要一碗不要辣的酸辣汤”。服务员工程师拿菜单接单厨师AI看到菜单后自动按 Spec 端手册匹配团队技术规范落地。这本手册对应 SDD 的Story 端——交付阶段工程师唯一交互入口。工程师只聊业务目标、流程、价值、验收不涉及任何团队技术规范、架构细节、Header 命名、P0 红线。AI 看到 Story自动按 Spec 端沉淀的团队规范写代码。两本手册各管一段——Spec 端团队规范手册长期挂在厨房墙上AI 训练时读一次就吸收成自己的团队习惯后续做菜写代码自动按手册规范来做——不用每次提醒用这把刀、这个灶、这个调料。Story 端顾客点菜单服务员只听顾客要什么厨房收到菜单自动按 Spec 端手册匹配团队技术规范做菜。服务员工程师全程没碰过技术细节——他只对顾客说好的七分熟牛排转身交给厨房。这就是 SDD 在 AI 时代的核心创新——双端架构。Spec 端把团队规范长期挂载AI 训练时吸收记忆Story 端把工程师对话聚焦到业务目标——人机分工彻底切分。这一句你记下来。它是 SDD 的核心命题也是 AI 时代工程师给 AI 加的第三道秩序分水岭。两端各管一段互不越界Spec 端和 Story 端不是两件事是一套分工纪律——Spec 端人全责——团队规范由人全权整理、迭代、更新。AI 不参与规范的制定AI 只负责吸收、记忆整套技术范式。人定 Spec、AI 记 Spec规范改了人改、AI 跟着改。Story 端工程师唯一入口——交付阶段工程师只沟通业务目标/用户流程/业务价值/验收场景不涉及任何团队技术规范/架构细节。AI 收到 Story 自动匹配 Spec 基线落地——输出代码、跑测试、提 PR。AI 永远只接收两样东西一是 Spec 端长期挂载的团队规范背景知识二是 Story 端工程师的业务对话任务输入。AI 不需要工程师每次重新告知技术约束也不需要工程师在 Story 里塞技术细节。两端绝不混用——Spec 端不写业务对话Story 端不写技术约束。一旦混用就回到AI 凭印象写代码的旧模式——约束每次都讲一遍、每次都漏一次。到这里你大概有感觉了SDD 双端的核心不是两份文档是人机分工纪律。Spec 端把立规矩这件事长期挂在 AI 训练阶段Story 端把做业务这件事聚焦到工程师唯一入口。两端切分清楚工程师从重复告知约束里彻底解放出来。那 Spec 端具体沉淀什么Story 端具体长什么样下一节我们先讲 Spec 端。三、Spec 端——AI 工作台前置打底我们把 Spec 端摆到桌面上。Spec 端是 SDD 双端里的训练端——AI 工作台前置打底把团队技术规范长期挂载、人全权负责整理、AI 训练时吸收记忆。Spec 端要沉淀的内容不是零散的几条规矩是一整套团队技术范式——技术栈、编码规范、类结构、惯用设计模式、架构方案、最优实践六大类缺一不可。这套范式被 AI 吸收成自己的团队习惯后续写代码自动按这套习惯来。下面我们一段一段拆。Spec 端沉淀什么——六大类团队技术范式Spec 端要沉淀的不是一份几十页的规范大全是AI 读一遍就能照着做的六类核心内容。我把它们列出来你按你团队的实际情况增减第一类团队技术栈——项目用的是什么语言、什么框架、什么版本。比如语言Java 17框架Spring Boot 3.3 / Spring Cloud 2023消息中间件Kafka数据库MySQL 8.0缓存Redis 7工具库Lombok / Guava测试框架JUnit 5 / Mockito / JaCoCoAI 读完这一类下次写代码就默认用 Java 17 Spring Boot 3.3不再写var用 Java 11 风格、不再调RestTemplate该用 WebClient、不再用com.sun.*内部 API。第二类编码规范——团队约定的代码风格、命名规则、注释规则、Header 规范。比如命名UserId / TenantId / OrderId强类型 ID 值对象禁止用 String 或 Long命名UserStatus.ACTIVE / DEACTIVATED / LOCKED枚举禁止魔字符串命名x-user-id / x-tenant-id / x-tenant-ids全小写 Header禁止 X-User-Id格式Google Java Format日志SLF4J 门面 Logback 实现禁止 System.out.println异常单一DomainException类 工厂方法禁止自定义 Exception 子类注释业务方法必须有 Javadoc 中文说明AI 读完这一类下次写代码就默认按团队的命名风格来——不再混用驼峰和下划线、不再到处写 System.out、不再每个 service 造一个自己的 Exception。第三类类结构设计习惯——团队偏好的代码组织方式、分层纪律、模块边界。比如分层六模块bootstrap / interfaces / application /domain⭐零 Spring / infrastructure /common⭐零框架依赖方向bootstrap → interfaces → application → domain → common、infrastructure → domain → common充血模型业务逻辑归聚合根Order.pay()/Order.cancel()service 只编排不实现仓储接口定义在 domain 层实现在 infrastructure 层领域事件NoArgsConstructor 字段禁止 finalJackson 反序列化要求AI 读完这一类下次写代码就默认按分层纪律来——不再把 Spring 注解写进 domain 层、不再让 service 直接调 repository、不再给 DomainEvent 字段加 final。第四类惯用设计模式——团队偏好的模式选择和落地方式。比如聚合根基类AggregateRoot自带private final ListDomainEventregisterEvent()clearDomainEvents()仓储模式BaseRepositoryT, ID通用接口 各聚合根专用接口幂等消费OnEventIdempotentAspect自动幂等业务代码完全无需手写幂等响应包装RTResponseBodyWrapperController 不手动包 RAI 读完这一类下次写代码就默认用团队偏好的模式——不再自己造轮子写 BaseEntity、不再每个 service 手写幂等、不再 Controller 里手动.data(...)包响应。第五类内部架构方案——团队的整体架构选择、技术选型、模块边界。比如双文档体系readme.md人友好 AGENTS.mdAI 友好——同一套秩序两种表达权限模型PBAC 权限码资源:操作规范USER:CREATE / USER:DELETE / ORDER:VIEW网关 Header 透传AppContext请求级 ThreadLocal 异步线程ContextTaskDecorator反应式纪律全 WebFlux Reactor禁绝Mono.block()/RestTemplateSPI 接口ConditionalOnMissingBean让 AI 按需替换默认实现AI 读完这一类下次写代码就默认按团队架构来——不再自己选 WebFlux 还是 MVC、不再自己定义权限模型、不再 Header 透传写 ThreadLocal 还是别的方案。第六类长期最优落地实践——团队踩过的坑、验证过的最佳实践。比如覆盖率门槛common domain 各层 ≥ 90%行/分支双门槛作为 P0 准入Mock 边界禁止 Mock 实体 / ValueObject / Command / Query必须真造真测P0 红线清单domain 层零 Spring / SSO Cookie 必须 JS 写 / Header 全小写不能改Given-When-Then 强制AGENTS.md§6.3 测试方法命名规范AI 读完这一类下次写代码就默认按团队纪律来——不再把覆盖率刷成 60%、不再 mock 实体、不再用 Servlet API 写 Cookie。六类合起来就是 Spec 端沉淀的完整团队技术范式。每一类都不是贴墙上的告示是AI 训练时吸收成自己习惯的入门教材。人全权负责整理、迭代、更新Spec 端的关键纪律只有一条——人全权负责。团队规范不是 AI 写的是人写的。AI 不参与规范的制定、修改、迭代AI 只负责吸收、记忆整套范式。为什么必须人全责因为 AI 一定会改。AI 给数字感觉合理、给命名看着舒服——可它不知道你这个项目的上下文历史痛点不知道以前哪个 P0 红线是因为漏掉出了生产事故。它只看当下的代码和当下的语境把我看着合理当作项目应该这样。所以规范必须由人定、AI 记——人定期 review Spec、更新 Spec、迭代 SpecAI 训练时读一次、按 Spec 写后续所有代码。Spec 端不是一锤子买卖。规范随项目一起演化——新技术栈引入时加进 Spec、老红线不再适用时从 Spec 移除、新的最优实践被验证后写进 Spec。人改 Spec、AI 跟 Spec两端切分清楚。行业案例Spec 端长期挂载省了多少成本Spec 端长期挂载是不是真的能省成本我给你一组行业数据你判断。腾讯云 BMAD 平台把团队的architecture.md永久挂载在 AI 工作台——AI 每次编码自动读取团队架构 Spec不需要工程师每次重复告知架构约束。结果是——上下文重复提示词成本下降 65%。aiXcoder 在某银行做私有化部署时把行内完整技术规范做模型微调 工作台长期挂载——AI 不再凭印象写代码按行内规范落地的代码合规性提升 50%代码生成准确率从 10% 提升到 35%。腾讯云 aiXcoder 两个案例摆在一起看——一个靠 Spec 文档长期挂载BMAD一个靠模型微调 工作台挂载aiXcoder结果都指向同一件事规范长期挂载 工程师重复告知成本暴跌 代码质量跃升。Spec 端不是贴墙上的告示是 AI 工作台的开机启动项。规范在那里AI 就按规范写规范不在那里AI 就按印象写。四、Story 端——FDE 工程师唯一交互入口我们把 Story 端摆到桌面上。Story 端是 SDD 双端里的交付端——交付阶段工程师唯一交互入口。工程师只沟通业务不涉及技术细节AI 收到 Story 自动匹配 Spec 基线落地。Story 端的目标只有一个——让工程师从重复告知技术约束里彻底解放出来只聊业务。下面我们一段一段拆。Story 端工程师只聊什么Story 端的输入是业务对话——工程师跟 AI 说的话只围绕四件事业务目标——这个 Story 要解决什么问题、为谁解决、解决到什么程度。例子“我们 SaaS 平台的客服部门需要一个功能让客服能查询某租户下的所有用户信息包括用户名、手机号、最近登录时间。这是为了处理’租户投诉某用户违规’的场景。”用户流程——用户怎么走到这一步、前置条件是什么、后置效果是什么。例子“客服登录后台 → 进入’租户管理’ → 选择具体租户 → 点击’查看用户列表’ → 输入查询条件用户名/手机号 → 看到用户列表。列表要分页每页 20 条。”业务价值——这个功能上线后业务上有什么变化。例子“上线后客服处理租户投诉的效率从 30 分钟降到 5 分钟用户满意度提升。”验收场景——怎么算做对了。例子“验收场景 1输入手机号前缀 138能查到所有 138 开头的用户验收场景 2用户列表按最近登录时间倒序验收场景 3分页参数 page2size10 返回第 11-20 条。”这四件事讲清楚业务对话就完了。不需要工程师讲用什么语言、“用什么框架”、“Header 怎么写”、“P0 红线有哪些”。这些事 Spec 端已经沉淀好AI 自动按 Spec 落地。Story 端工程师绝不聊什么反过来Story 端工程师绝不聊以下内容——❌ “用 Java 17 写、用 Spring Boot 3.3”❌ “domain 层不要 import Spring”❌ “Header 写 x-user-id 不要写 X-User-Id”❌ “SSO Cookie 必须用 JS 写”❌ “覆盖率达到 90% 才算过”❌ “Mock 不要 mock 实体”❌ “DomainEvent 子类字段禁止 final”这些事都在 Spec 端——AI 训练时已经读过、已经吸收成自己的团队习惯。工程师再讲一遍就是重复告知重复告知在 SDD 双端架构里是冗余、是浪费、是体系失效的征兆。工程师在 Story 端讲技术约束相当于把已经贴在墙上的告示再口头念一遍——告示还在墙上没人去看工程师念完没人记得。两端切分就是要把念告示这件事从工程师的日常工作里彻底拿掉。行业案例Story 端只聊业务提了多少效Story 端只聊业务是不是真的提效我给你两组行业数据。SpecStory Studio在一家海外 SaaS 团队落地 SDD 双端后——澄清轮次仅 1.01 次即 AI 平均只需要被澄清 1 次就能交付远低于传统开发的 5-10 次日均提交代码量是传统开发的 10 倍首次交付通过率达 85.7%即 10 次提交有 8.5 次一次就过剩下的 1.5 次打回改改就过海外某 Fintech 公司 14 人团队用 SDD 双端落地后——9 个月业务 roadmap 压缩到 11 周交付上线故障从 17 个降至 3 个下降 82%两组数据摆在一起看——一个靠澄清轮次 日均提交 首次交付衡量SpecStory Studio一个靠交付周期 故障数衡量Fintech 14 人。两组数据都指向同一件事——Story 端只聊业务AI 自动按 Spec 落地工程师从重复告知里解放出来交付效率和代码质量同时跃升。工程师只聊业务AI 自动匹配技术规范落地——聊天即交付是 SDD 双端的终极目标。这一句你记下来。它是 SDD 双端的最终归宿也是 AI 时代 FDE 工程师的核心工作方式。五、核心创新——留白区把自由还给 AI我们把留白区摆到桌面上。留白区是 SDD 这套方法论的差异化亮点——前三道秩序DDD / TDD / Spec 端把规矩焊死了规矩之间留出来的空间就是留白区。留白区完全交 AI 自主发挥工程师不该再管。留白区不是放任 AI 乱写是在三层刚性约束之间给 AI 留出怎么实现的自由空间。下面我们一段一段拆。三层刚性约束焊死第一层——DDD 锁业务赛道上一篇讲过的边界。业务边界 AI 边界。AI 进了哪个限界上下文就说哪个上下文的术语出上下文就停下来问人。限界上下文、聚合根、统一语言——这三件事焊死业务赛道AI 不会越界。第二层——TDD 卡审计红线上一上篇讲过的试菜员。覆盖率 ≥ 90% Given-When-Then P0/P1/P2 分级阻塞 Mock 边界焊死。AI 写完代码CI/CD 流水线自动试菜——逻辑不对直接打回违规红线直接拦截。审计红线焊死AI 不会逻辑上不对地交付。第三层——Spec 固技术基线这一篇刚讲的。团队技术栈、编码规范、类结构、设计模式、架构方案、最优实践——六大类范式长期挂载AI 训练时吸收、后续写代码自动按规范来。技术基线焊死AI 不会凭印象写代码。三层合起来——DDD 锁赛道 TDD 卡审计 Spec 固技术 三层刚性约束。这三层之外就是留白区。留白区——三层之外的自由空间留白区是菜单没写但厨师可自由发挥的部分——比如非核心中间件适配——比如日志中间件用 Logback 还是 Log4j2、AI 自主选设计模式落地——比如领域事件发布是同步还是异步、AI 自主选类拆分——比如一个 service 该拆成三个还是五个、AI 自主决定工具函数实现——比如字符串处理是用 Apache Commons 还是 Guava、AI 自主选分支算法——比如某种业务分支该用 if-else 还是策略模式、AI 自主决定局部变量命名——比如ListUser叫users还是userList、AI 自主决定注释风格——比如某个方法要不要加 Javadoc、AI 自主决定这些事不影响业务验收、不影响审计红线、不影响技术基线——纯技术实现细节AI 怎么写都对工程师不该再管。工程师管这些事会怎样回归到重复告知的旧模式——工程师告诉 AI “这里用 if-else”、AI 下次又按印象写 “这里用 switch”、工程师再告诉它一遍……无限循环。留白区的设计价值是——既杜绝 AI 篡改业务、越界架构又不束缚 AI 批量生成的灵活性。三层约束守做对的底线留白区让 AI 在底线之上自由发挥。平衡风险管控与交付效率留白区的关键洞察是——风险管控和交付效率不是反义词是同一件事的两面。不留空间——AI 只会抄模板写出来的代码死板、没优化、读着别扭过度发挥——AI 越界业务糊掉、架构腐化、故障满天。只有焊边界 放选择才能让 AI 在风险可控的前提下充分释放产能。我用厨房比喻把这件事讲透——三层刚性 厨房的三道焊死的规矩DDD 后厨工种分区焊死切配不能跑炒锅区TDD 出菜口试菜员焊死不合格不上桌Spec 端 墙上挂的手册焊死团队规范全员遵守留白区 工种区之间的过道、调料台、装盘装饰区——葱花怎么摆——AI 自己决定盘边用什么装饰——AI 自己决定调料配比微调——AI 自己决定这些细节不影响味道对不对DDD TDD 守住、不影响团队规范守没守Spec 端守住纯粹是美感和效率的发挥空间。留白区是这套方法论的差异化亮点——DDD 锁赛道 TDD 卡审计 Spec 固技术这三层之外完全交给 AI 自由发挥。这一句你记下来。它是 SDD 的差异化亮点也是 AI 时代工程师给 AI 的最后一层自由度。适用边界留白区不是万能解药留白区不是放之四海皆准的设计模式——它有严格的适用边界。留白区适用于复杂业务系统——业务跨多个限界上下文、有清晰的领域边界企业业务服务——长期演化的核心系统、团队稳定、规范沉淀成本高FDE 一线交付场景——工程师和 AI 协作密集、效率是核心 KPI留白区不适用于小型工具——一次性脚本、几小时写完的小工具Spec 端沉淀成本远高于收益独立脚本——单文件、单函数的轻量活AI 凭印象写就够探索性原型——业务边界还没定、规范还没沉淀硬上 Spec 端就是过度工程这套方法论仅针对复杂业务系统 / 企业业务服务 / FDE 一线交付场景——不适用小型工具 / 独立脚本。把 SDD 硬套到小工具上就是把杀鸡刀用在蚂蚁上。六、完整四阶段工作流——SDD 怎么落地到日常交付我们把 SDD 的完整落地工作流摆到桌面上。Spec 端 Story 端 留白区是 SDD 的三块拼图。这一节把它们拼成一条完整的、可实操的 FDE 工程师日常工作流。整条工作流分四个阶段——前置工程一次性→ 需求对话Story 端→ AI 自动开发Spec 基线匹配→ TDD 全流程审计自动拦截→ 上线交付。下面我们一段一段拆。阶段一前置工程——平台搭建一次性前置工程是 SDD 的造厨房环节——一次性投入把 Spec 端的基础设施搭好。责任人架构师 / 平台工程师产出物framework 工程骨架——六模块分层铁律、双文档体系readme.mdAGENTS.md、覆盖率门槛、P0 红线清单、Given-When-Then 规范、Mock 边界规范Spec 端知识库——团队技术栈、编码规范、类结构、设计模式、架构方案、最优实践——按六大类整理成结构化文档CI/CD 流水线——Maven 配置、JaCoCo 配置、P0 阻断脚本、GitHub Actions 触发器、PR 模板关键工具framework 仓库开源工程底座 Spec 端整理工具前置工程的产出物就是 SDD 的基础设施——它一旦搭好新服务 clone 下来就自带团队规范、AI 训练时直接读、不用从零搭。阶段二需求对话——Story 端工程师唯一入口需求对话是 SDD 的接单环节——工程师只聊业务把 Story 端的输入讲清楚。责任人FDE 工程师产出物业务 Story 卡片——业务目标、用户流程、业务价值、验收场景按上一节讲的四件事结构化整理用例规约可选——如果业务复杂把每个动作展开成输入/输出/边界/异常路径的结构化描述关键工具工程师的嘴 纸笔 / 任务卡工具需求对话的关键纪律——只聊业务不聊技术。工程师不讲用什么语言、“用什么框架”、“Header 怎么写”。这些事 Spec 端已经写好AI 自动按 Spec 落地。阶段三AI 自动开发——Spec 基线匹配AI 自动开发是 SDD 的做菜环节——AI 收到 Story 自动按 Spec 端团队规范落地。责任人AI产出物代码——controller / service / domain / repository / dto / tests单元测试——Given-When-Then 结构、真造真测、覆盖率门槛满足领域事件如需要——NoArgsConstructor 字段禁止 finalPR——提交流水线关键工具AI Spec 端知识库 framework 工程骨架AI 自动开发的关键纪律——按 Spec 写、按留白区发挥。技术栈、命名、分层、Header、P0 红线——这些都按 Spec 来非核心中间件、设计模式、类拆分、工具函数——这些在留白区自由发挥。阶段四TDD 全流程审计——自动拦截TDD 全流程审计是 SDD 的试菜环节——CI/CD 流水线自动跑单元测试 集成测试 覆盖率检查 P0 红线扫描。责任人CI/CD 流水线产出物测试结果——单元测试绿/集成测试绿/E2E 测试绿覆盖率报告——JaCoCo 统计的 LINE / BRANCH 覆盖率P0 检查报告——domain 层零 Spring / SSO Cookie JS 写 / Header 全小写 / Mock 边界等拦截 / 通过——任意一项不达标PR 打回 AI 重做全绿PR 进主分支关键工具JaCoCo P0 阻断脚本 GitHub ActionsTDD 全流程审计的关键纪律——流水线 24 小时在线、不累、不跳着看、不走神。AI 写得再快流水线跟得上。阶段五上线交付——灰度 / 监控 / 回滚上线交付是 SDD 的出菜环节——代码进生产、灰度发布、监控告警、故障回滚。责任人FDE 工程师 运维产出物可上线版本——每个上下文独立版本号、独立发版灰度策略——按上下文粒度灰度auth-center 先灰 10%、观察稳定后 50%、最后 100%监控指标——每个上下文独立 QPS / 错误率 / 响应时间回滚预案——事务回滚 / 事件反向补偿关键工具CI/CD 流水线 监控告警 配置中心上线交付的关键纪律——版本化、灰度化、可回滚、可监控。AI 部署按规矩发版、按规矩灰度、按规矩回滚、按规矩监控不出格、不翻车。五个阶段合起来的全景图五个阶段连成一条流水线——前置工程一次性→ 需求对话Story→ AI 自动开发Spec 匹配→ TDD 审计拦截→ 上线交付灰度。每个阶段有明确的产出物 责任人 关键工具。FDE 工程师拿到这条流水线日常工作就两件事——业务对话Story 端——跟业务方聊清楚做什么、为什么、验收什么平台复用Spec 端 framework——直接用前置工程搭好的基础设施不用从零搭剩下的活代码怎么写、测试怎么跑、规范怎么守、审计怎么过、上线怎么发——AI 自动按 Spec 端团队规范 TDD 审计红线落地FDE 工程师不需要重复告知。七、写在最后——SDD 双端 留白区AI 时代工程师的第三道秩序回到开头那个反直觉的判断——AI 协作的最大痛点不是 AI 不够聪明是工程师每次都要重复告知技术约束。你可能还在想以前没这么麻烦啊。规范写进文档、onboarding 带一遍不就够了吗这是把 SDD 当文档备查了。SDD 在 AI 时代不是文档备查是给 AI 立一套它开机就读得到的技术规范基础设施。规范不长期挂载在 AI 工作台AI 就每次从零开始规范挂在那里AI 就按规范写——这就是Spec 端打底的真正含义。所以 SDD 在 AI 时代的角色不是教你写更全的规范文档是给 AI 立一套它能照着走的团队规范基础设施。这套基础设施我们用厨房两本手册这个最日常的比喻串了一整篇——Spec 端 厨房的团队操作手册 设备清单。长期挂在墙上新人AI 训练读一遍就吸收成自己的团队习惯后续做菜写代码自动按手册规范来做——不用每次提醒用这把刀、这个灶、这个调料。Story 端 厨房的顾客点菜单。服务员工程师只听顾客要什么七分熟牛排、不要葱厨房AI收到菜单自动按 Spec 端手册匹配团队技术规范做菜。服务员全程没碰过技术细节。留白区 菜单没写但厨师可自由发挥的部分。DDD 锁赛道 TDD 卡审计 Spec 固技术三层刚性之外完全交 AI 自主——葱花怎么摆、盘边怎么装饰AI 决定。完整四阶段工作流 FDE 工程师日常交付的标准化流水线。前置工程一次性搭基础设施→ 需求对话只聊业务→ AI 自动开发按 Spec 匹配→ TDD 审计流水线拦截→ 上线交付按规矩发版。Spec 端把团队规范长期挂载AI 训练时吸收记忆Story 端把工程师对话聚焦到业务目标——人机分工彻底切分。这一句你记下来。它是 SDD 的核心命题也是 AI 时代工程师的第三道秩序分水岭。你可能会问DDD TDD SDD 三件套听起来都是给 AI 立规矩规矩立完了 AI 哪还有发挥空间有的——就是留白区。留白区是这套方法论的差异化亮点——DDD 锁赛道 TDD 卡审计 Spec 固技术这三层之外完全交给 AI 自由发挥。三层约束守做对的底线留白区让 AI 在底线之上自由发挥。这就是 AI 时代工程师给 AI 的最后一层自由度——既杜绝 AI 篡改业务、越界架构又不束缚 AI 批量生成的灵活性。DDD 锁赛道、TDD 卡审计、Spec 固技术、留白区让 AI 飞——这四层加在一起才是 AI 时代工程师的完整秩序。这一句你记下来。它是这一篇的收束也是 29-32 四篇一组的总结。光说不练假把式。下一篇我们到 framework 仓库里去看一份完整的乐谱怎么谱出来——DDD / TDD / SDD 三件套在 framework 里怎么长成可跑可用的工程骨架怎么让 AI 在四层秩序里真正飞起来。你会在 framework 里看到——六模块分层铁律、零 Spring 依赖、JaCoCo 90% 强制覆盖率、P0 / P1 / P2 分级、双文档体系、SPI 软秩序——这套工程骨架把 DDD / TDD / SDD 三件套从方法论落到代码新服务 clone 下来第一天就有完整秩序。这就是 32 篇要讲的——framework 是一座已经搭好的厨房。关于 ArchAIHarness这篇文章是「看懂 AI 与智能体」专栏的一部分由ArchAIHarness持续输出。ArchAIHarness 是一套面向 AI 时代软件工程的人机协同架构哲学与公开工程资产主张架构师定义秩序AI 在秩序中生长。人立法AI 执行体系审计。如果你也希望 AI 在明确的架构边界内协作而不是在混沌中碰运气欢迎到 GitHub 上看看我们在做什么组织主页github.com/ArchAIHarness — 了解完整理念与资产全景本专栏zhuanlan-ai-and-agents— 所有文章的源码与发布记录实践指南docs— 架构哲学、工程方法和落地指南开源工具agent-workflows— 可复用的 AI 协作 Agents、Skills 与 Tools工程样例framework— DDD AI 协作的工程底座展示如何在开发中融合 AIEngineered by Architects · Empowered by AI · Audited by Discipline
SDD 完整指南——Spec 端打底、Story 端 交付、留白区
你越来越熟练地把活甩给 AI 了。需求丢过去它给你写 controller需求丢过去它给你搭 domain需求丢过去它给你跑 JaCoCo。可你最近有没有这种感觉——同一个约束你跟它讲了三遍、五遍、十遍它还是按它印象里的样子写不是 AI 学不会是 AI 每次都是从零开始学。它不知道你们用 Java 17 还是 Java 21、不知道你们 Header 全小写、不知道你们 domain 层零 Spring、不知道你们 P0 红线包括 SSO Cookie 必须 JS 写。它每接一个新会话、每开一个新分支都把这些事重听一遍。你觉得它学得越来越快——是的快到把你每次口头告知的技术约束全都重新发明了一遍。这一篇专门解决这件事——给 AI 立第三道秩序。也就是 SDD。不是教你 SDD 是什么。你可能早就看过规范驱动开发Spec 驱动这类词知道要把规范写下来。你缺的不是这个动作是怎么让规范真正长期挂在 AI 工作台里让工程师只聊业务、让 AI 自动按规范落地、不再每次重复告知。这一篇不讲 SDD 的全套理论二十多年前的方法论一篇讲不完只讲AI 时代最该抓住的那一段——Spec 端打底、Story 端交付、留白区让 AI 飞。三件事讲清楚AI 协作的第三道秩序分水岭就立起来了。下面我们一段一段拆。一、AI 协作的最大痛点——工程师每次都要重复告知技术约束你可能觉得这标题反了——AI 越来越聪明约束告知应该是越来越轻松才对啊。AI 上下文窗口越来越大、记忆能力越来越强、Agent 循环越来越稳以前得说三遍的事现在一遍它就记住了。听起来很有道理。可真实现场不是这样。我先把现场摆给你看。我过去一年在多个 AI 协作项目里看到的剧本几乎都是这么演的。第一个会话你跟 AI 说帮我写一个Tenant聚合根。它给你整出 constructor、factory、setter、equals、hashCode整整齐齐一坨。你打开一看——好家伙Tenant直接调tenantRepository.save()domain 层 import 了 Spring。你心里咯噔一下提醒它domain 层不能 import Spring。它点点头“好的下次注意。”第二个会话你又拉了一个新会话让它写另一个聚合根。它又一次凭印象写——上次会话的提醒它早就忘了domain 层又 import 了 Spring。你又提醒一次。它又点点头。第三个会话你新开一个分支让它写一个新的限流器。它还是 import 了 Spring还是在 domain 层调了 Redis 客户端还是在 Service 层用了RestTemplate该用 WebClient。你又、又、又提醒一遍。第六个月你打开 PR 列表发现——同一个约束domain 零 Spring你跟 AI 讲了不下二十遍。每一遍它都点头、每一遍它下次又忘。约束没有沉淀下来约束成了你每次会话必带的开场白。这不是 AI 太笨这是约束没有被长期挂载。AI 没有团队约束的本能。你看到 domain 层不该有 Spring立刻会想起框架依赖倒置原则 六模块分层铁律 AGENTS.md P0 红线——这一整套判断是多年工程纪律和团队规范堆出来的。AI 没有这堆纪律。它看到的是字符、命名、文件位置、上下文里你最近一次提的偏好。它能写语法正确的代码但它写不出团队规范上的对。更扎心的是它不是在犯错它是在用最快的速度忘掉你跟它讲过的一切。会话一关记忆清零下次开工又从语料库平均值那个工程师开始写。所以这个反直觉的结论你得先吞下去——AI 协作的最大痛点不是 AI 不够聪明是工程师每次都要重复告知技术约束——SDD 就是要让这件事不再发生。这一句你得记牢。它是这一篇的底色。Spec 端把团队规范长期挂载AI 训练时吸收记忆Story 端把工程师对话聚焦到业务目标——聊天即交付是 SDD 双端的终极目标。这两句合起来就是 AI 时代 SDD 的真正价值——不是教你写更全的规范文档是给 AI 立一套它开机就读得到的技术规范基础设施。为什么这件事过去没人提你可能想问规范、规约、约束是软件工程的老生常谈为什么二十多年过去今天才突然被 AI 时代捧成第三道秩序分水岭因为过去不需要。2002 年到 2022 年那段时间团队规范是写在 wiki、写在 onboarding 文档、写在老员工脑子里——新人入职看一遍、老员工带一遍、code review 复审一遍。流程跑二十年团队规模从 5 人到 50 人规范能磨平、传递能到位。AI 时代情况反过来了。AI 进来之后“老员工这个角色被 AI 替代了——你不再带新人 onboarding你带的是 AI 读规范文档。可 AI 不会看一遍 wiki 就记住”AI 每次会话都从零开始。你不能把团队规范写进 wiki 就指望 AI 自动遵循——AI 读 wiki 跟读小说一样扫一遍就忘。每一次新会话都得重新告知。每一次新分支都得重新对齐。这件事靠口头告知磨不平——你不能让团队里每个工程师、每次新会话、每次新分支都重新告知一次domain 零 Spring、Header 全小写、P0 红线包括 SSO Cookie 必须 JS 写。怎么办把规范写进文档还不够得把规范焊进 AI 工作台。SDD 在 AI 时代的真正用法是把团队规范长期挂在 AI 训练阶段——AI 开工前自动读、自动吸收、自动记成自己的团队习惯工程师只聊业务、不再重复告知。这件事过去没人提是因为过去没有 AI 需要读这份规范。今天有 AI 进场了规范才变成必须长期挂载的基础设施。所以 SDD 的价值从来没变——把团队规范沉淀下来。变的是它今天服务的对象过去给老员工 onboarding今天给 AI 训练。过去是文档备查今天是 AI 开机就读。那到底怎么立这套规范基础设施长什么样下一节我们正式讲 SDD 双端是什么。二、什么是 SDD 双端——Spec 端打底 Story 端交付两端各管一段我们把 SDD 摆到桌面上。SDD 全名 Spec-Driven Development规范驱动开发。这不是什么新方法论——二十多年前软件工程就有先把规范写下来再写代码的实践。今天在 AI 时代SDD 突然从好习惯升级成双端架构——原因就是上一节说的AI 没有团队约束的本能得靠规范长期挂载。这套双端架构的骨架由两件事组成——Spec 端训练阶段人全权沉淀 Story 端交付阶段工程师唯一入口。两件事就是 SDD 在 AI 时代的核心骨架。把它们讲清楚你就看懂了 SDD 在 AI 时代的一半。下面我们按先讲为什么需要它再讲它是什么的顺序拆。整套讲述我用厨房两本手册作主线比喻——这套比喻不是装饰是帮你从厨房的物理直觉直接推出 SDD 的工程结论。一句话故事为什么团队规范会漏我先给你讲一个真实的小故事。有一次我跟一个团队的架构师聊他们的 AI 协作流水线。他说“我们团队规范写得很全——六模块分层、AGENTS.md、coverage-rules、P0/P1/P2文档加起来 200 多页。”我点点头问“那 domain 层 import Spring 这种事AI 还会犯吗”他叹口气“会。”“为什么”“因为 AI 每次新会话都从零开始。规范文档它读一遍就忘下次开工又回到它’印象里’的工程师那套写法。我让团队每个工程师每天提醒 AI 不要 import Spring——可工程师们又不是复读机提醒三遍五遍他们自己也烦最后变成没人提醒AI 该 import 还是 import。”更糟的是团队花了三个月写的规范文档AI 完全不读——它扫一眼就过去了连SSO Cookie 必须 JS 写这种最关键的 P0 红线都没记住。你听出问题在哪了吗规范文档有了可 AI 不读、读了也记不住。规范成了贴墙上的告示AI 路过看一眼、走过去了。传统开发里这种漏靠老员工盯、靠 code review 拦、能磨平。AI 时代磨不平。AI 写代码的速度是人工的几十倍reviewer 看不完AI 不读规范文档reviewer 想拦也拦不住——PR 提上来才发现问题已经晚了。怎么办两本手册Spec 端 Story 端SDD 在 AI 时代的解法是把团队规范 工程师对话切成两个完全独立的端——Spec 端和 Story 端。两端各管一段AI 只跟这两端打交道。我用厨房两本手册作最直觉的比喻。一家像样的餐厅后厨一定有两本手册——第一本手册挂在墙上叫团队操作手册 设备清单——封面印着Spec 端。这本手册长期挂在厨房墙上记录团队的整套技术规范灶具怎么用、刀具怎么选、调料怎么配、菜品有哪些标准做法。新人入职第一天主厨指着手册说“这本先读透后续做菜不用每次问师傅。”这本手册对应 SDD 的Spec 端——AI 工作台前置打底人在训练阶段全权沉淀、AI 训练时吸收记忆。规范不是贴墙上的告示是新人入职必读的入门教材。第二本手册是服务员手里的叫顾客点菜单——封面印着Story 端。这本手册没有技术细节只记录顾客要什么——“我要一份七分熟的牛排”、“我要一碗不要辣的酸辣汤”。服务员工程师拿菜单接单厨师AI看到菜单后自动按 Spec 端手册匹配团队技术规范落地。这本手册对应 SDD 的Story 端——交付阶段工程师唯一交互入口。工程师只聊业务目标、流程、价值、验收不涉及任何团队技术规范、架构细节、Header 命名、P0 红线。AI 看到 Story自动按 Spec 端沉淀的团队规范写代码。两本手册各管一段——Spec 端团队规范手册长期挂在厨房墙上AI 训练时读一次就吸收成自己的团队习惯后续做菜写代码自动按手册规范来做——不用每次提醒用这把刀、这个灶、这个调料。Story 端顾客点菜单服务员只听顾客要什么厨房收到菜单自动按 Spec 端手册匹配团队技术规范做菜。服务员工程师全程没碰过技术细节——他只对顾客说好的七分熟牛排转身交给厨房。这就是 SDD 在 AI 时代的核心创新——双端架构。Spec 端把团队规范长期挂载AI 训练时吸收记忆Story 端把工程师对话聚焦到业务目标——人机分工彻底切分。这一句你记下来。它是 SDD 的核心命题也是 AI 时代工程师给 AI 加的第三道秩序分水岭。两端各管一段互不越界Spec 端和 Story 端不是两件事是一套分工纪律——Spec 端人全责——团队规范由人全权整理、迭代、更新。AI 不参与规范的制定AI 只负责吸收、记忆整套技术范式。人定 Spec、AI 记 Spec规范改了人改、AI 跟着改。Story 端工程师唯一入口——交付阶段工程师只沟通业务目标/用户流程/业务价值/验收场景不涉及任何团队技术规范/架构细节。AI 收到 Story 自动匹配 Spec 基线落地——输出代码、跑测试、提 PR。AI 永远只接收两样东西一是 Spec 端长期挂载的团队规范背景知识二是 Story 端工程师的业务对话任务输入。AI 不需要工程师每次重新告知技术约束也不需要工程师在 Story 里塞技术细节。两端绝不混用——Spec 端不写业务对话Story 端不写技术约束。一旦混用就回到AI 凭印象写代码的旧模式——约束每次都讲一遍、每次都漏一次。到这里你大概有感觉了SDD 双端的核心不是两份文档是人机分工纪律。Spec 端把立规矩这件事长期挂在 AI 训练阶段Story 端把做业务这件事聚焦到工程师唯一入口。两端切分清楚工程师从重复告知约束里彻底解放出来。那 Spec 端具体沉淀什么Story 端具体长什么样下一节我们先讲 Spec 端。三、Spec 端——AI 工作台前置打底我们把 Spec 端摆到桌面上。Spec 端是 SDD 双端里的训练端——AI 工作台前置打底把团队技术规范长期挂载、人全权负责整理、AI 训练时吸收记忆。Spec 端要沉淀的内容不是零散的几条规矩是一整套团队技术范式——技术栈、编码规范、类结构、惯用设计模式、架构方案、最优实践六大类缺一不可。这套范式被 AI 吸收成自己的团队习惯后续写代码自动按这套习惯来。下面我们一段一段拆。Spec 端沉淀什么——六大类团队技术范式Spec 端要沉淀的不是一份几十页的规范大全是AI 读一遍就能照着做的六类核心内容。我把它们列出来你按你团队的实际情况增减第一类团队技术栈——项目用的是什么语言、什么框架、什么版本。比如语言Java 17框架Spring Boot 3.3 / Spring Cloud 2023消息中间件Kafka数据库MySQL 8.0缓存Redis 7工具库Lombok / Guava测试框架JUnit 5 / Mockito / JaCoCoAI 读完这一类下次写代码就默认用 Java 17 Spring Boot 3.3不再写var用 Java 11 风格、不再调RestTemplate该用 WebClient、不再用com.sun.*内部 API。第二类编码规范——团队约定的代码风格、命名规则、注释规则、Header 规范。比如命名UserId / TenantId / OrderId强类型 ID 值对象禁止用 String 或 Long命名UserStatus.ACTIVE / DEACTIVATED / LOCKED枚举禁止魔字符串命名x-user-id / x-tenant-id / x-tenant-ids全小写 Header禁止 X-User-Id格式Google Java Format日志SLF4J 门面 Logback 实现禁止 System.out.println异常单一DomainException类 工厂方法禁止自定义 Exception 子类注释业务方法必须有 Javadoc 中文说明AI 读完这一类下次写代码就默认按团队的命名风格来——不再混用驼峰和下划线、不再到处写 System.out、不再每个 service 造一个自己的 Exception。第三类类结构设计习惯——团队偏好的代码组织方式、分层纪律、模块边界。比如分层六模块bootstrap / interfaces / application /domain⭐零 Spring / infrastructure /common⭐零框架依赖方向bootstrap → interfaces → application → domain → common、infrastructure → domain → common充血模型业务逻辑归聚合根Order.pay()/Order.cancel()service 只编排不实现仓储接口定义在 domain 层实现在 infrastructure 层领域事件NoArgsConstructor 字段禁止 finalJackson 反序列化要求AI 读完这一类下次写代码就默认按分层纪律来——不再把 Spring 注解写进 domain 层、不再让 service 直接调 repository、不再给 DomainEvent 字段加 final。第四类惯用设计模式——团队偏好的模式选择和落地方式。比如聚合根基类AggregateRoot自带private final ListDomainEventregisterEvent()clearDomainEvents()仓储模式BaseRepositoryT, ID通用接口 各聚合根专用接口幂等消费OnEventIdempotentAspect自动幂等业务代码完全无需手写幂等响应包装RTResponseBodyWrapperController 不手动包 RAI 读完这一类下次写代码就默认用团队偏好的模式——不再自己造轮子写 BaseEntity、不再每个 service 手写幂等、不再 Controller 里手动.data(...)包响应。第五类内部架构方案——团队的整体架构选择、技术选型、模块边界。比如双文档体系readme.md人友好 AGENTS.mdAI 友好——同一套秩序两种表达权限模型PBAC 权限码资源:操作规范USER:CREATE / USER:DELETE / ORDER:VIEW网关 Header 透传AppContext请求级 ThreadLocal 异步线程ContextTaskDecorator反应式纪律全 WebFlux Reactor禁绝Mono.block()/RestTemplateSPI 接口ConditionalOnMissingBean让 AI 按需替换默认实现AI 读完这一类下次写代码就默认按团队架构来——不再自己选 WebFlux 还是 MVC、不再自己定义权限模型、不再 Header 透传写 ThreadLocal 还是别的方案。第六类长期最优落地实践——团队踩过的坑、验证过的最佳实践。比如覆盖率门槛common domain 各层 ≥ 90%行/分支双门槛作为 P0 准入Mock 边界禁止 Mock 实体 / ValueObject / Command / Query必须真造真测P0 红线清单domain 层零 Spring / SSO Cookie 必须 JS 写 / Header 全小写不能改Given-When-Then 强制AGENTS.md§6.3 测试方法命名规范AI 读完这一类下次写代码就默认按团队纪律来——不再把覆盖率刷成 60%、不再 mock 实体、不再用 Servlet API 写 Cookie。六类合起来就是 Spec 端沉淀的完整团队技术范式。每一类都不是贴墙上的告示是AI 训练时吸收成自己习惯的入门教材。人全权负责整理、迭代、更新Spec 端的关键纪律只有一条——人全权负责。团队规范不是 AI 写的是人写的。AI 不参与规范的制定、修改、迭代AI 只负责吸收、记忆整套范式。为什么必须人全责因为 AI 一定会改。AI 给数字感觉合理、给命名看着舒服——可它不知道你这个项目的上下文历史痛点不知道以前哪个 P0 红线是因为漏掉出了生产事故。它只看当下的代码和当下的语境把我看着合理当作项目应该这样。所以规范必须由人定、AI 记——人定期 review Spec、更新 Spec、迭代 SpecAI 训练时读一次、按 Spec 写后续所有代码。Spec 端不是一锤子买卖。规范随项目一起演化——新技术栈引入时加进 Spec、老红线不再适用时从 Spec 移除、新的最优实践被验证后写进 Spec。人改 Spec、AI 跟 Spec两端切分清楚。行业案例Spec 端长期挂载省了多少成本Spec 端长期挂载是不是真的能省成本我给你一组行业数据你判断。腾讯云 BMAD 平台把团队的architecture.md永久挂载在 AI 工作台——AI 每次编码自动读取团队架构 Spec不需要工程师每次重复告知架构约束。结果是——上下文重复提示词成本下降 65%。aiXcoder 在某银行做私有化部署时把行内完整技术规范做模型微调 工作台长期挂载——AI 不再凭印象写代码按行内规范落地的代码合规性提升 50%代码生成准确率从 10% 提升到 35%。腾讯云 aiXcoder 两个案例摆在一起看——一个靠 Spec 文档长期挂载BMAD一个靠模型微调 工作台挂载aiXcoder结果都指向同一件事规范长期挂载 工程师重复告知成本暴跌 代码质量跃升。Spec 端不是贴墙上的告示是 AI 工作台的开机启动项。规范在那里AI 就按规范写规范不在那里AI 就按印象写。四、Story 端——FDE 工程师唯一交互入口我们把 Story 端摆到桌面上。Story 端是 SDD 双端里的交付端——交付阶段工程师唯一交互入口。工程师只沟通业务不涉及技术细节AI 收到 Story 自动匹配 Spec 基线落地。Story 端的目标只有一个——让工程师从重复告知技术约束里彻底解放出来只聊业务。下面我们一段一段拆。Story 端工程师只聊什么Story 端的输入是业务对话——工程师跟 AI 说的话只围绕四件事业务目标——这个 Story 要解决什么问题、为谁解决、解决到什么程度。例子“我们 SaaS 平台的客服部门需要一个功能让客服能查询某租户下的所有用户信息包括用户名、手机号、最近登录时间。这是为了处理’租户投诉某用户违规’的场景。”用户流程——用户怎么走到这一步、前置条件是什么、后置效果是什么。例子“客服登录后台 → 进入’租户管理’ → 选择具体租户 → 点击’查看用户列表’ → 输入查询条件用户名/手机号 → 看到用户列表。列表要分页每页 20 条。”业务价值——这个功能上线后业务上有什么变化。例子“上线后客服处理租户投诉的效率从 30 分钟降到 5 分钟用户满意度提升。”验收场景——怎么算做对了。例子“验收场景 1输入手机号前缀 138能查到所有 138 开头的用户验收场景 2用户列表按最近登录时间倒序验收场景 3分页参数 page2size10 返回第 11-20 条。”这四件事讲清楚业务对话就完了。不需要工程师讲用什么语言、“用什么框架”、“Header 怎么写”、“P0 红线有哪些”。这些事 Spec 端已经沉淀好AI 自动按 Spec 落地。Story 端工程师绝不聊什么反过来Story 端工程师绝不聊以下内容——❌ “用 Java 17 写、用 Spring Boot 3.3”❌ “domain 层不要 import Spring”❌ “Header 写 x-user-id 不要写 X-User-Id”❌ “SSO Cookie 必须用 JS 写”❌ “覆盖率达到 90% 才算过”❌ “Mock 不要 mock 实体”❌ “DomainEvent 子类字段禁止 final”这些事都在 Spec 端——AI 训练时已经读过、已经吸收成自己的团队习惯。工程师再讲一遍就是重复告知重复告知在 SDD 双端架构里是冗余、是浪费、是体系失效的征兆。工程师在 Story 端讲技术约束相当于把已经贴在墙上的告示再口头念一遍——告示还在墙上没人去看工程师念完没人记得。两端切分就是要把念告示这件事从工程师的日常工作里彻底拿掉。行业案例Story 端只聊业务提了多少效Story 端只聊业务是不是真的提效我给你两组行业数据。SpecStory Studio在一家海外 SaaS 团队落地 SDD 双端后——澄清轮次仅 1.01 次即 AI 平均只需要被澄清 1 次就能交付远低于传统开发的 5-10 次日均提交代码量是传统开发的 10 倍首次交付通过率达 85.7%即 10 次提交有 8.5 次一次就过剩下的 1.5 次打回改改就过海外某 Fintech 公司 14 人团队用 SDD 双端落地后——9 个月业务 roadmap 压缩到 11 周交付上线故障从 17 个降至 3 个下降 82%两组数据摆在一起看——一个靠澄清轮次 日均提交 首次交付衡量SpecStory Studio一个靠交付周期 故障数衡量Fintech 14 人。两组数据都指向同一件事——Story 端只聊业务AI 自动按 Spec 落地工程师从重复告知里解放出来交付效率和代码质量同时跃升。工程师只聊业务AI 自动匹配技术规范落地——聊天即交付是 SDD 双端的终极目标。这一句你记下来。它是 SDD 双端的最终归宿也是 AI 时代 FDE 工程师的核心工作方式。五、核心创新——留白区把自由还给 AI我们把留白区摆到桌面上。留白区是 SDD 这套方法论的差异化亮点——前三道秩序DDD / TDD / Spec 端把规矩焊死了规矩之间留出来的空间就是留白区。留白区完全交 AI 自主发挥工程师不该再管。留白区不是放任 AI 乱写是在三层刚性约束之间给 AI 留出怎么实现的自由空间。下面我们一段一段拆。三层刚性约束焊死第一层——DDD 锁业务赛道上一篇讲过的边界。业务边界 AI 边界。AI 进了哪个限界上下文就说哪个上下文的术语出上下文就停下来问人。限界上下文、聚合根、统一语言——这三件事焊死业务赛道AI 不会越界。第二层——TDD 卡审计红线上一上篇讲过的试菜员。覆盖率 ≥ 90% Given-When-Then P0/P1/P2 分级阻塞 Mock 边界焊死。AI 写完代码CI/CD 流水线自动试菜——逻辑不对直接打回违规红线直接拦截。审计红线焊死AI 不会逻辑上不对地交付。第三层——Spec 固技术基线这一篇刚讲的。团队技术栈、编码规范、类结构、设计模式、架构方案、最优实践——六大类范式长期挂载AI 训练时吸收、后续写代码自动按规范来。技术基线焊死AI 不会凭印象写代码。三层合起来——DDD 锁赛道 TDD 卡审计 Spec 固技术 三层刚性约束。这三层之外就是留白区。留白区——三层之外的自由空间留白区是菜单没写但厨师可自由发挥的部分——比如非核心中间件适配——比如日志中间件用 Logback 还是 Log4j2、AI 自主选设计模式落地——比如领域事件发布是同步还是异步、AI 自主选类拆分——比如一个 service 该拆成三个还是五个、AI 自主决定工具函数实现——比如字符串处理是用 Apache Commons 还是 Guava、AI 自主选分支算法——比如某种业务分支该用 if-else 还是策略模式、AI 自主决定局部变量命名——比如ListUser叫users还是userList、AI 自主决定注释风格——比如某个方法要不要加 Javadoc、AI 自主决定这些事不影响业务验收、不影响审计红线、不影响技术基线——纯技术实现细节AI 怎么写都对工程师不该再管。工程师管这些事会怎样回归到重复告知的旧模式——工程师告诉 AI “这里用 if-else”、AI 下次又按印象写 “这里用 switch”、工程师再告诉它一遍……无限循环。留白区的设计价值是——既杜绝 AI 篡改业务、越界架构又不束缚 AI 批量生成的灵活性。三层约束守做对的底线留白区让 AI 在底线之上自由发挥。平衡风险管控与交付效率留白区的关键洞察是——风险管控和交付效率不是反义词是同一件事的两面。不留空间——AI 只会抄模板写出来的代码死板、没优化、读着别扭过度发挥——AI 越界业务糊掉、架构腐化、故障满天。只有焊边界 放选择才能让 AI 在风险可控的前提下充分释放产能。我用厨房比喻把这件事讲透——三层刚性 厨房的三道焊死的规矩DDD 后厨工种分区焊死切配不能跑炒锅区TDD 出菜口试菜员焊死不合格不上桌Spec 端 墙上挂的手册焊死团队规范全员遵守留白区 工种区之间的过道、调料台、装盘装饰区——葱花怎么摆——AI 自己决定盘边用什么装饰——AI 自己决定调料配比微调——AI 自己决定这些细节不影响味道对不对DDD TDD 守住、不影响团队规范守没守Spec 端守住纯粹是美感和效率的发挥空间。留白区是这套方法论的差异化亮点——DDD 锁赛道 TDD 卡审计 Spec 固技术这三层之外完全交给 AI 自由发挥。这一句你记下来。它是 SDD 的差异化亮点也是 AI 时代工程师给 AI 的最后一层自由度。适用边界留白区不是万能解药留白区不是放之四海皆准的设计模式——它有严格的适用边界。留白区适用于复杂业务系统——业务跨多个限界上下文、有清晰的领域边界企业业务服务——长期演化的核心系统、团队稳定、规范沉淀成本高FDE 一线交付场景——工程师和 AI 协作密集、效率是核心 KPI留白区不适用于小型工具——一次性脚本、几小时写完的小工具Spec 端沉淀成本远高于收益独立脚本——单文件、单函数的轻量活AI 凭印象写就够探索性原型——业务边界还没定、规范还没沉淀硬上 Spec 端就是过度工程这套方法论仅针对复杂业务系统 / 企业业务服务 / FDE 一线交付场景——不适用小型工具 / 独立脚本。把 SDD 硬套到小工具上就是把杀鸡刀用在蚂蚁上。六、完整四阶段工作流——SDD 怎么落地到日常交付我们把 SDD 的完整落地工作流摆到桌面上。Spec 端 Story 端 留白区是 SDD 的三块拼图。这一节把它们拼成一条完整的、可实操的 FDE 工程师日常工作流。整条工作流分四个阶段——前置工程一次性→ 需求对话Story 端→ AI 自动开发Spec 基线匹配→ TDD 全流程审计自动拦截→ 上线交付。下面我们一段一段拆。阶段一前置工程——平台搭建一次性前置工程是 SDD 的造厨房环节——一次性投入把 Spec 端的基础设施搭好。责任人架构师 / 平台工程师产出物framework 工程骨架——六模块分层铁律、双文档体系readme.mdAGENTS.md、覆盖率门槛、P0 红线清单、Given-When-Then 规范、Mock 边界规范Spec 端知识库——团队技术栈、编码规范、类结构、设计模式、架构方案、最优实践——按六大类整理成结构化文档CI/CD 流水线——Maven 配置、JaCoCo 配置、P0 阻断脚本、GitHub Actions 触发器、PR 模板关键工具framework 仓库开源工程底座 Spec 端整理工具前置工程的产出物就是 SDD 的基础设施——它一旦搭好新服务 clone 下来就自带团队规范、AI 训练时直接读、不用从零搭。阶段二需求对话——Story 端工程师唯一入口需求对话是 SDD 的接单环节——工程师只聊业务把 Story 端的输入讲清楚。责任人FDE 工程师产出物业务 Story 卡片——业务目标、用户流程、业务价值、验收场景按上一节讲的四件事结构化整理用例规约可选——如果业务复杂把每个动作展开成输入/输出/边界/异常路径的结构化描述关键工具工程师的嘴 纸笔 / 任务卡工具需求对话的关键纪律——只聊业务不聊技术。工程师不讲用什么语言、“用什么框架”、“Header 怎么写”。这些事 Spec 端已经写好AI 自动按 Spec 落地。阶段三AI 自动开发——Spec 基线匹配AI 自动开发是 SDD 的做菜环节——AI 收到 Story 自动按 Spec 端团队规范落地。责任人AI产出物代码——controller / service / domain / repository / dto / tests单元测试——Given-When-Then 结构、真造真测、覆盖率门槛满足领域事件如需要——NoArgsConstructor 字段禁止 finalPR——提交流水线关键工具AI Spec 端知识库 framework 工程骨架AI 自动开发的关键纪律——按 Spec 写、按留白区发挥。技术栈、命名、分层、Header、P0 红线——这些都按 Spec 来非核心中间件、设计模式、类拆分、工具函数——这些在留白区自由发挥。阶段四TDD 全流程审计——自动拦截TDD 全流程审计是 SDD 的试菜环节——CI/CD 流水线自动跑单元测试 集成测试 覆盖率检查 P0 红线扫描。责任人CI/CD 流水线产出物测试结果——单元测试绿/集成测试绿/E2E 测试绿覆盖率报告——JaCoCo 统计的 LINE / BRANCH 覆盖率P0 检查报告——domain 层零 Spring / SSO Cookie JS 写 / Header 全小写 / Mock 边界等拦截 / 通过——任意一项不达标PR 打回 AI 重做全绿PR 进主分支关键工具JaCoCo P0 阻断脚本 GitHub ActionsTDD 全流程审计的关键纪律——流水线 24 小时在线、不累、不跳着看、不走神。AI 写得再快流水线跟得上。阶段五上线交付——灰度 / 监控 / 回滚上线交付是 SDD 的出菜环节——代码进生产、灰度发布、监控告警、故障回滚。责任人FDE 工程师 运维产出物可上线版本——每个上下文独立版本号、独立发版灰度策略——按上下文粒度灰度auth-center 先灰 10%、观察稳定后 50%、最后 100%监控指标——每个上下文独立 QPS / 错误率 / 响应时间回滚预案——事务回滚 / 事件反向补偿关键工具CI/CD 流水线 监控告警 配置中心上线交付的关键纪律——版本化、灰度化、可回滚、可监控。AI 部署按规矩发版、按规矩灰度、按规矩回滚、按规矩监控不出格、不翻车。五个阶段合起来的全景图五个阶段连成一条流水线——前置工程一次性→ 需求对话Story→ AI 自动开发Spec 匹配→ TDD 审计拦截→ 上线交付灰度。每个阶段有明确的产出物 责任人 关键工具。FDE 工程师拿到这条流水线日常工作就两件事——业务对话Story 端——跟业务方聊清楚做什么、为什么、验收什么平台复用Spec 端 framework——直接用前置工程搭好的基础设施不用从零搭剩下的活代码怎么写、测试怎么跑、规范怎么守、审计怎么过、上线怎么发——AI 自动按 Spec 端团队规范 TDD 审计红线落地FDE 工程师不需要重复告知。七、写在最后——SDD 双端 留白区AI 时代工程师的第三道秩序回到开头那个反直觉的判断——AI 协作的最大痛点不是 AI 不够聪明是工程师每次都要重复告知技术约束。你可能还在想以前没这么麻烦啊。规范写进文档、onboarding 带一遍不就够了吗这是把 SDD 当文档备查了。SDD 在 AI 时代不是文档备查是给 AI 立一套它开机就读得到的技术规范基础设施。规范不长期挂载在 AI 工作台AI 就每次从零开始规范挂在那里AI 就按规范写——这就是Spec 端打底的真正含义。所以 SDD 在 AI 时代的角色不是教你写更全的规范文档是给 AI 立一套它能照着走的团队规范基础设施。这套基础设施我们用厨房两本手册这个最日常的比喻串了一整篇——Spec 端 厨房的团队操作手册 设备清单。长期挂在墙上新人AI 训练读一遍就吸收成自己的团队习惯后续做菜写代码自动按手册规范来做——不用每次提醒用这把刀、这个灶、这个调料。Story 端 厨房的顾客点菜单。服务员工程师只听顾客要什么七分熟牛排、不要葱厨房AI收到菜单自动按 Spec 端手册匹配团队技术规范做菜。服务员全程没碰过技术细节。留白区 菜单没写但厨师可自由发挥的部分。DDD 锁赛道 TDD 卡审计 Spec 固技术三层刚性之外完全交 AI 自主——葱花怎么摆、盘边怎么装饰AI 决定。完整四阶段工作流 FDE 工程师日常交付的标准化流水线。前置工程一次性搭基础设施→ 需求对话只聊业务→ AI 自动开发按 Spec 匹配→ TDD 审计流水线拦截→ 上线交付按规矩发版。Spec 端把团队规范长期挂载AI 训练时吸收记忆Story 端把工程师对话聚焦到业务目标——人机分工彻底切分。这一句你记下来。它是 SDD 的核心命题也是 AI 时代工程师的第三道秩序分水岭。你可能会问DDD TDD SDD 三件套听起来都是给 AI 立规矩规矩立完了 AI 哪还有发挥空间有的——就是留白区。留白区是这套方法论的差异化亮点——DDD 锁赛道 TDD 卡审计 Spec 固技术这三层之外完全交给 AI 自由发挥。三层约束守做对的底线留白区让 AI 在底线之上自由发挥。这就是 AI 时代工程师给 AI 的最后一层自由度——既杜绝 AI 篡改业务、越界架构又不束缚 AI 批量生成的灵活性。DDD 锁赛道、TDD 卡审计、Spec 固技术、留白区让 AI 飞——这四层加在一起才是 AI 时代工程师的完整秩序。这一句你记下来。它是这一篇的收束也是 29-32 四篇一组的总结。光说不练假把式。下一篇我们到 framework 仓库里去看一份完整的乐谱怎么谱出来——DDD / TDD / SDD 三件套在 framework 里怎么长成可跑可用的工程骨架怎么让 AI 在四层秩序里真正飞起来。你会在 framework 里看到——六模块分层铁律、零 Spring 依赖、JaCoCo 90% 强制覆盖率、P0 / P1 / P2 分级、双文档体系、SPI 软秩序——这套工程骨架把 DDD / TDD / SDD 三件套从方法论落到代码新服务 clone 下来第一天就有完整秩序。这就是 32 篇要讲的——framework 是一座已经搭好的厨房。关于 ArchAIHarness这篇文章是「看懂 AI 与智能体」专栏的一部分由ArchAIHarness持续输出。ArchAIHarness 是一套面向 AI 时代软件工程的人机协同架构哲学与公开工程资产主张架构师定义秩序AI 在秩序中生长。人立法AI 执行体系审计。如果你也希望 AI 在明确的架构边界内协作而不是在混沌中碰运气欢迎到 GitHub 上看看我们在做什么组织主页github.com/ArchAIHarness — 了解完整理念与资产全景本专栏zhuanlan-ai-and-agents— 所有文章的源码与发布记录实践指南docs— 架构哲学、工程方法和落地指南开源工具agent-workflows— 可复用的 AI 协作 Agents、Skills 与 Tools工程样例framework— DDD AI 协作的工程底座展示如何在开发中融合 AIEngineered by Architects · Empowered by AI · Audited by Discipline
