从Vibe Coding到Spec Coding：一套可落地的AI-SDD企业级研发实战工程

写在前面

---

2025年，Andrej Karpathy提出“Vibe Coding”时，描述的是一种近乎直觉的编程方式：用自然语言描述意图，AI直接生成代码，开发者只需“感受”结果并不断调整。这种方式在原型阶段确实快得惊人——我见过有人一个下午就用AI搓出了一个完整的管理后台。

但当你试图把它搬到团队协作和生产环境时，问题很快浮现：代码风格混乱、边界条件遗漏、架构漂移，以及那个被反复提及的 “90天墙” ——三个月后，代码库变成了一团没人敢动、难以理解和维护的代码。

Spec Coding 正是为了解决这些问题而生的。

但你可能已经发现了另一个问题：现在市面上的Spec Coding工具——比如GitHub的Spec Kit、开源的OpenSpec——它们解决的是“规范化”问题，但真实企业场景的痛点远不止于此。

腾讯后端团队的技术负责人rickyshou在用了三个月Speckit后总结道：

另外一个场景你一定不陌生： 你花了2个小时，让AI生成了一个完整的登录模块。代码能跑、测试能过，一切看起来很完美。然后你说：“接下来我们做支付功能。”

AI开始写支付代码。写到一半，你发现它用的异常处理方式跟登录模块完全不一样——明明登录时用了统一的 BusinessException，支付代码里却开始 throw new RuntimeException。

你问它：“为什么不沿用登录模块的异常处理方式？”

AI沉默了一下，然后说：“抱歉，我忘了……我来修正。”

这不是AI不聪明，而是它没有持续记住整个项目的上下文。每个新任务对它来说，都像是一次“重启”。而那些你花时间建立的规范、约定、模式，随着对话窗口的滚动，也随之流失了。

---

一、当前AI开发中的三个核心痛点

---

在AI辅助开发被广泛使用的今天，团队面临三个普遍问题：

痛点1：上下文窗口爆满，AI“做完就忘”

表现	后果
规范文档随项目规模增长，AI一次性加载不全	任务做到一半断片
复杂项目的技术约束、业务规则无法完整进入AI上下文	AI忘记前面的约束，前后代码风格不一致
长对话中，早期的重要决策被滚动出上下文窗口	同一个功能，不同时间写的代码像两个人写的

腾讯技术工程团队的实践文章明确指出了这个问题：

这不是个别现象，而是当前AI辅助开发在复杂项目中的普遍困境。

痛点2：知识不沉淀，每次都是重新开始

表现	后果
这次做“用户登录”花2小时，下次做“支付认证”又花2小时	团队能力无法积累
AI每次从零开始理解需求，无法复用过往的经验	每个人都是“新手”
踩过的坑、解决过的问题，随着对话结束而消失	同样的坑反复踩

团队的“知识”散落在每个人的对话记录里，而不是沉淀在项目中。

痛点3：流程太死，需求一变就推倒重来

表现	后果
流程是线性的，但企业需求是动态的、会反复的	需求一变，整个流程推倒重来
AI生成的代码“一次性”强，缺乏回溯和修正机制	变更成本极高
口头需求变更后，AI直接改代码，但规范文档没更新	文档与代码迅速脱节，规范形同虚设

越规范的流程，面对变化时越脆弱——这是开源SDD工具在真实企业场景中“水土不服”的根本原因。

二、我们的解法：一套可落地的AI-SDD工程框架

---

上面这三个痛点，指向同一个结论：AI开发不能只靠对话，需要一套工程化的机制来管理上下文、沉淀知识、应对变化。

这套框架的核心思想是：“宪法进规则，流程进技能，数据放项目”。

2.1 三条铁律

在展开具体设计之前，先明确三条不可妥协的铁律：

铁律一：No Spec, No Code ——没有文档，不准写代码。AI在没有约束的情况下生成代码，其试错成本远高于你写几行规范的时间。

铁律二：Spec is Truth ——当文档和代码冲突时，错的一定是代码。Spec是唯一的权威来源。

铁律三：Reverse Sync（反向同步） ——发现Bug或需求变更时，先修文档，再修代码。如果每次都直接改代码，Spec会迅速腐烂，失去对AI的约束能力。

2.2 目录结构：前后端分离 + 资产独立

这是整套框架的物理基础。每个Feature都是一个独立的原子单元，自带完整上下文。

 复制代码期次-2026-07-月报功能/
├── 00-项目总览/
│   ├── CONSTITUTION.md              # 全局宪法（技术栈、命名、异常码）
│   ├── PROJECT_GRAPH.md             # 依赖图谱与状态看板
│   ├── PATTERNS/                    # 经验模式库（只增不减）
│   │   ├── README.md
│   │   └── auth-pattern.md          # 用户认证模式（含踩坑记录）
│   └── RULES/
│       └── conflict-resolution.md   # 代码与Spec冲突裁决规则
│
└── Feature-001-用户登录/
    ├── _shared/
    │   ├── API_CONTRACT.yaml        # OpenAPI 契约（唯一事实源）
    │   └── business-rules.md
    ├── backend/                     # 后端专属目录
    │   ├── REQ.md                   # 后端需求
    │   ├── prototypes/              # 逻辑参考图
    │   └── TASK.md                  # 原子任务（流程、产出、验收）
    └── frontend/                    # 前端专属目录
        ├── REQ.md                   # 前端需求
        ├── prototypes/              # UI设计稿
        └── TASK.md                  # 原子任务
 

这个结构如何解决三个痛点？

痛点	对应的解法	具体机制
上下文爆满	原子任务按需加载	每个 TASK.md 自带“上下文加载清单”，AI只加载当前任务必需的5~7个文件
知识不沉淀	PATTERNS模式库	每个Feature完成后AI自动总结可复用模式，下次直接复用+避坑
流程太死	反向同步 + 灵活Skill	需求变更时先改Spec再改代码，不受固定流程限制

2.3 核心文件示例

全局宪法：CONSTITUTION.md

 复制代码 # 项目全局宪法
 
 ## 1. 技术栈强制规范
 - **后端框架**: Spring Boot 3.2.5 (Java 17)
 - **ORM**: MyBatis-Plus 3.5.5
 - **数据库**: MySQL 8.0，字符集 utf8mb4
 - **缓存**: Redis 7.0
 - **前端框架**: Vue 3.4 + TypeScript + Vite
 
 ## 2. 命名铁律
 - **Java类**: 驼峰命名 (如 `UserController`)
 - **数据库表**: 小写+下划线 (如 `sys_user`)
 - **接口路径**: 复数名词，如 `/api/v1/users`
 
 ## 3. 异常码区间
 | 区间 | 含义 |
 | :--- | :--- |
 | 1000-1999 | 参数校验错误 |
 | 2000-2999 | 认证授权错误 |
 | 3000-3999 | 业务逻辑冲突 |
 | 5000-5999 | 系统内部错误 |

接口契约：API_CONTRACT.yaml

 复制代码openapi: 3.0.3
info:
  title: 用户认证API
  version: 1.0.0
paths:
  /api/v1/auth/login:
    post:
      summary: 用户登录
      requestBody:
        required: true
        content:
          application/json:
            schema:
              required: [phone, password]
              properties:
                phone:
                  type: string
                  pattern: '^1[3-9]d{9}$'
                password:
                  type: string
                  minLength: 6
      responses:
        '200':
          description: 登录成功

原子任务：backend/TASK.md

 复制代码 # 原子任务：后端 - 用户登录接口
 
 ##  变更履历
 | 日期 | 版本 | 变更摘要 | 作者 |
 | :--- | :--- | :--- | :--- |
 | 2026-06-29 | v1.0 | 初始创建 | 架构师 |
 
 ## 1. 上下文加载清单（AI开发前必须逐项读取）
 - [ ] `../../00-项目总览/CONSTITUTION.md`
 - [ ] `../../00-项目总览/PROJECT_GRAPH.md`
 - [ ] `../_shared/API_CONTRACT.yaml`（最高优先级）
 - [ ] `./REQ.md`
 
 ## 2. 产出物清单（AI完成后填写）
 | 类型 | 预期路径 | 实际生成路径 | 状态 |
 | :--- | :--- | :--- | :--- |
 | Controller | `AuthController.java` | ___________ | ⬜ |
 | Service | `AuthService.java` | ___________ | ⬜ |
 | 单元测试 | `AuthControllerTest.java` | ___________ | ⬜ | ## 3. 验收标准（AC）
 - [ ] AC-01: 接口响应时间 < 200ms
 - [ ] AC-02: 单元测试覆盖率 ≥ 90%

模式沉淀：PATTERNS/auth-pattern.md

 复制代码 # P-001: 用户认证与JWT生成模式 ## 适用场景
 新项目需要用户登录功能
 
 ## 核心实现片段
 ```java
 public String generateToken(Long userId) {
     return Jwts.builder()
         .setSubject(userId.toString())
         .signWith(getSignKey(), SignatureAlgorithm.HS256)
         .compact();
 }

踩坑记录（️ 必读）

• 坑点: 未处理 ExpiredJwtException，返回HTTP 500
• 解决: 全局异常处理器统一捕获，返回HTTP 401

2.4 冲突裁决规则

当代码与Spec冲突时，AI不能“瞎猜”。我们设计了三级裁决机制：

级别	场景	处理方式
L1 - 明确冲突	Spec有明确定义，代码违反	AI立即修正代码，无需人工
L2 - Spec缺陷	Spec定义不清或自相矛盾	AI暂停并提问，不得自行脑补
L3 - 环境不可行	Spec方案在当前环境不可行	AI升级至架构评审

---

三、实战：在Qcoder/WorkBuddy/Trae中落地

---

3.1 文件放哪里？

内容类型	存放位置	说明
CONSTITUTION.md、PATTERNS/	项目目录 期次-xxx/00-项目总览/	数据资产，AI按需读取
各Feature的 REQ.md、TASK.md、API_CONTRACT.yaml	Feature-xxx/ 子目录	原子任务数据
核心宪法与裁决规则摘要	Qcoder: .qoder/rules/ Trae: .trae/rules/ WorkBuddy: IDE界面创建	始终生效的刚性约束
后端/前端开发流程	Qcoder: .lingma/skills/ Trae: .trae/skills/ WorkBuddy: .codebuddy/skills/	按需加载的标准化流程

3.2 Rules配置（始终生效）

 复制代码 ---
 ruleType: always-apply
 ---
 
 # 项目核心宪法与冲突裁决规则
 
 ## 1. 核心原则
 - **反向同步铁律**: 代码与Spec冲突时，必须先更新Spec，再修改代码
 - **Spec是唯一事实源**: 文档和代码冲突时，错的一定是代码
 
 ## 2. 冲突裁决规则
 - L1 - 明确冲突 → 立即修正代码
 - L2 - Spec缺陷 → 暂停，提交裁决
 - L3 - 环境不可行 → 升级至架构评审

3.3 启动开发任务

工具	启动方式
WorkBuddy	直接说“开发 Feature-001 后端”
Qcoder	@feature-backend-dev 开发 Feature-001
Trae	/feature-backend-dev 开发 Feature-001

---

四、三大创新机制深度剖析

---

4.1 反向同步（Reverse Sync）— 开创新范式

 复制代码传统模式:  需求变更 → 直接改代码 → 文档滞后 → 知识丢失
SpecCore:     需求变更 → 先更新 Spec → 记录变更履历 → 再改代码

Hotfix 例外流程：

• 允许紧急修复跳过反向同步（30 分钟内止血）
• 24 小时内强制补录
• 图谱标记 ️ 待反向同步，不可签署完成

4.2 原子任务按需加载

对比实验数据（自述）：

模式	Token 消耗	上下文完整性	复杂项目可行性
普通 AI 对话	5K~20K/次	杂乱	容易爆
SpecCore 按需加载	2K~5K/次	精准	稳定

4.3 模式驱动（Pattern-Driven）

传统 AI 编码：第 11 次做登录，和第 1 次一样从零开始。
SpecCore：每次 Feature 完成后自动沉淀模式，下次 AI 会主动检索：

---

五、设计亮点总结

---

5.1 架构优势

1. 三层分治：全局 / 期次 / Feature 的清晰职责边界，长期规范和短期任务不互相污染
2. 原子任务自包含：每个 TASK.md 是完整 AI 执行单元，不依赖外部记忆
3. API 契约锚定：OpenAPI 3.0 YAML 作为前后端唯一事实源，消除口径不一致
4. 反向同步铁律：L1/L2/L3 分级裁决，AI 行为边界清晰
5. 模式库 Auto-沉淀：每个 Feature 完成后 AI 自动提取可复用模式
6. 技术参考三级制：全新实现 / 参考实现 / 代码复用的显式区分

5.2 工程实践

1. 纯 Markdown + YAML 驱动：无运行时依赖，Git 即可版本管理
2. Skill/Rules 分离：「宪法进规则，流程进技能」— 兼顾 Token 效率和纪律性
3. 全员可读：中文优先，降低团队沟通成本
4. scaffold 代码骨架：每个 Feature 带可直接运行的工程骨架
5. 验收标准量化：10 条精确 AC + 产出物清单 + 签名 — 彻底消除"差不多"
6. 变更履历：每个 Spec 文件都有变更履历表，审计友好

---

六、部分功能演示

---

 复制代码## 快速开始# 1. 全局安装 CLI
npm install -g speccore# 2. 初始化项目
speccore init# 3. 导入存量项目（可选）
speccore import --project=user-service --path=./user-service# 4. 在 IDE 中开始开发
/spec-iteration-create --name=2026-07-会议预定

 复制代码/spec 进度怎么样了

 复制代码/spec 开发 Task-001 用户登录

/spec 是 SpecCore 的智能入口命令——用户只需输入 /spec 加上自然语言描述，AI 自动识别意图并执行对应的命令。用户不需要记忆框架内的所有命令名称，只需要像聊天一样表达意图。

---

七、总结：一个框架，三个答案

---

回到开头提出的三个问题：

问题	答案
如何让AI不“失忆”？	原子任务按需加载，每个任务只加载5~7个必要文件
如何让知识不消失？	PATTERNS模式库持续沉淀，每次开发都是团队的成长
如何让前后端AI不打架？	API契约锚定，各司其职，并行开发

这套框架的定位是：

它不是最重的方案，也不是最轻的，而是在团队协作性、知识复用性和流程灵活性三者之间找到了最佳平衡点的生产级AI研发基座。

核心理念：

---

本项目开源地址 github 本项目开源地址 gitee

---

框架还在持续演进中，欢迎在评论区交流你的实践经验和改进建议。