出海数字营销宝典 Logo
出海数字营销宝典evaoo.com

AI 编程工作流实践:用规格驱动开发(SDD)提升编码效率

2026-11-06程序员Left @coder_left约 18 分钟阅读

作者: 程序员 Left @coder_left(AI Coding / 独立开发者)•发布日期: 2026-09-01•SDD 规范驱动开发实战

SDD 规范驱动开发工作流示意图SDD 规范驱动开发工作流示意图

高强度用 AI 写代码时,你大概率遇到过这种情况:今天的 AI 推翻昨天写的代码,下一轮对话的 AI 改掉上一轮刚定好的逻辑。

明明三小时前刚和它定好接口规范,换个会话窗口或者连聊十几轮后,它突然擅自换了一套写法,把前面跑通的逻辑全部改乱。这种前后矛盾的问题,重度用 AI 写代码的人几乎都会踩坑。

AI 编码前后冲突:今天的 AI 否定昨天的 AIAI 编码前后冲突:今天的 AI 否定昨天的 AI

要根治 AI 编码前后冲突的问题,需要把依赖临时聊天记录的开发方式,切换为规范驱动开发(Spec-Driven Development,简称 SDD)。


一、AI 编码前后冲突的三个原因

AI 写代码容易前后冲突,主要有三个原因:

1. 上下文注意力随轮次衰减

代码实现阶段依赖前期讨论的结论,但模型注意力有限。对话越拉越长,早期关键决策越容易漏掉,写出来的代码就会跑偏。

2. 关闭窗口后历史决策丢失

每次新建会话窗口,上一轮的技术取舍就清空了。AI 拿不到当时的背景与设计意图,很容易按默认习惯乱改。

3. 缺少统一的长期编码规范

长期迭代中没有固定的代码规范文件做参照,AI 每次生成都自由发挥,项目代码风格很快就会失控。

规范驱动开发(Spec-Driven Development,简称 SDD)正是用来解决这三个问题的。

AI 编码前后冲突的三个原因AI 编码前后冲突的三个原因


二、SDD 规范驱动开发的原理

普通 AI 编码以临时聊天记录为准,SDD 规范驱动开发以本地规范文档为准。

规范文档最终虽然也要读入模型上下文,但它和纯聊天记录有本质区别。纯聊天记录混杂了大量试错对话,聊久了很容易把关键约束冲掉;Spec 文档则是人工确认后落盘的结构化文件,就算单轮跑偏,重开窗口读取文档就能立刻拉回正轨。

SDD 把散落在海量聊天记录里的临时约定,改成了落盘保存、按需读取的白盒规范文件。

对比两种开发方式:

  • 普通对话模式:每次发消息都要重复叮嘱*“用 TypeScript 写、错误用 AppError 包装、禁止写 any”*。连聊十轮后早期指令淡化,第十一轮它又开始写 any。
  • SDD 模式:输入框只写业务需求*“新增一个登录接口”*,AI 自动读取项目里的 code-style.md,从第一行代码起就按规范实现。

Thoughtworks 等工程团队在 AI 研发实践中测算过:把规范前置写成文档后,返工和反复沟通的时间大幅减少,交付效率比纯对话式开发提升了 30%~50%。

普通 AI Coding 与 SDD 规范驱动开发对比普通 AI Coding 与 SDD 规范驱动开发对比

普通对话流 vs SDD 规范驱动流对比模拟器

三、SDD 四步开发流程

日常落地 SDD 只需要走完四步:

1需求澄清

先给 AI 一句话需求,让它站在产品经理角度反问:“指出这段逻辑里所有模糊或冲突的边界条件”。讨论清楚后,由 AI 整理成结构化需求文档,你只需通读确认。

2技术方案

把需求文档发给 AI,让它结合项目现有架构列出影响范围与潜在技术风险,输出技术方案与改动文件清单。

3精准编码

明确限定编码边界:“严格按上述文档执行,只允许修改清单内的文件,禁止擅自重构未提及的模块”。

4对照验收

让 AI 按照需求文档与技术文档自检,逐条核对验收项并生成交付报告。

在这套分工里,你只需把精力放在前两步的文档把关和最终验收上,具体编码与逐项自检交给 AI 对照文档完成。

SDD 四步开发流程SDD 四步开发流程


四、两类 Spec 文档的划分

项目里的规范文档按生命周期分为两类:

  1. 事实来源(长期规范)

用来定义系统当前的真实状态与全局规则,例如代码风格、数据库表结构和路由约定。每类事实只维护唯一一份文档,长期有效,后续开发新功能都以它为准。

  1. 历史决策(单次迭代文档)

对应单次迭代的需求文档和技术方案,用来记录当时为什么这样设计。功能上线后即可归档,后续维护时供 Agent 查阅历史背景,避免误改旧逻辑。

Spec 分类:事实来源与历史决策Spec 分类:事实来源与历史决策


五、用渐进式披露管理 Spec

单个会话窗口一次塞入的规则不能太多,否则模型的指令遵循率会明显下降。项目积累的规范与历史方案变多后,需要靠渐进式披露(Progressive Disclosure) 按需加载。

渐进式披露常见于各类 Agent Skill 设计:会话启动时不把所有规则全文塞进上下文,只加载一层简短的目录索引。执行具体任务时,Agent 先看索引判断需要哪份规范,再去读取对应的子文件。

SDD 目录结构同样按这个思路组织:入口规则文件只写路由索引,具体规范拆分到独立子文档中。

推荐的项目目录结构如下:

TEXT9 行
1docs/
2├── specs/ # 事实来源(长期有效的全局规则)
3│ ├── code-style.md # 代码风格与架构约束
4│ └── database.md # 数据库设计与现有表结构
5├── requirements/ # 历史决策(按需求方案归档的时效文档)
6│ └── 2026-03-01-auth/ # 某次具体迭代的需求方案
7└── technicals/ # 历史决策(按技术方案归档的时效文档)
8 └── 2026-03-01-auth/ # 某次具体迭代的技术方案
9AGENTS.md # 根索引:告诉 AI 什么时候该去读哪份规则

根目录的 AGENTS.md 只需写明触发条件与文件路径:

• 在修改数据库相关代码前,必须先完整读取 docs/specs/database.md
• 在开启新功能开发前,必须先在 docs/requirements/、docs/technicals/ 目录下生成本次的需求和技术文档

渐进式披露目录结构渐进式披露目录结构

根目录的 CLAUDE.md 或 AGENTS.md 会在每次新建会话时自动注入系统提示词,优先级很高。AI 准备修改代码前,会按根文件里的路由要求先读取对应的 Spec 子文档,既节省上下文空间,又能保证改到关键模块时规则准确生效。

AGENTS.md 渐进式路由调度台

六、开源 Spec 管理工具 agents-spec

纯靠手工维护这套目录也有麻烦:规范改名后索引路径容易失效,多份规则可能互相冲突,每次开新项目还得重搭一遍目录。

我把这套目录结构与检查脚本封装成了开源 Skill:agents-spec。

它主要包含四项功能:

1. 规范结构审计:扫描项目现有的规则文件与文档,找出散落的规则和失效索引,先输出迁移方案再执行调整。

2. 初始化标准目录:自动生成根目录 AGENTS.md,并在 docs/ 下建好 specs/(长期规范)、requirements/(需求文档)和 technicals/(技术方案)。

3. 本地与 CI 合规校验:内置零第三方依赖的 Python 校验脚本,可在本地或 CI 流水线中检查 AGENTS.md 的链接与格式完整性。

4. 多工具兼容:按通用 Agent Skills 规范编写,支持接入 Claude Code、Cursor 和 Codex。

在终端运行下面一行命令即可安装,也可以把仓库链接发给 AI 代为安装:

npx skills add https://github.com/leftzzzz/agents-spec-skill

安装完成后,直接在 Agent 对话框输入指令即可启动:

"用 agents-spec 帮我审计一下当前项目的规范索引,整理出迁移计划"

开源仓库地址:
https://github.com/leftzzzz/agents-spec-skill


七、新老项目接入建议

如果你准备新建项目,可以先在根目录建好 AGENTS.md 和 docs/specs/code-style.md,写清楚技术栈、错误处理与命名规范,再开始写业务代码。

如果已经在维护存量老项目,建议先装好 agents-spec 跑一次目录体检,把散落在各处的规则收拢归档。后续每次开发新需求,统一按“需求澄清、技术方案、限定范围编码、对照验收”四步执行即可。

SDD 工作流

觉得本文有启发?一键复制标准引用摘要

自带原文归因链接与核心摘要,可直接粘贴至团队飞书/Slack 知识库、技术周报或大模型上下文。