读完本文，你将获得一套经过验证的AI研发工程框架，以及可在Qcoder、WorkBuddy、Trae中直接运行的完整配置。
写在前面
2025年，Andrej Karpathy提出"Vibe Coding"时，描述的是一种近乎直觉的编程方式：用自然语言描述意图，AI直接生成代码，开发者只需"感受"结果并不断调整。这种方式在原型阶段确实快得惊人------我见过有人一个下午就用AI搓出了一个完整的管理后台。
但当你试图把它搬到团队协作和生产环境 时，问题很快浮现：代码风格混乱、边界条件遗漏、架构漂移，以及那个被反复提及的 "90天墙" ------三个月后，代码库变成了一团没人敢动、难以理解和维护的代码。
Spec Coding 正是为了解决这些问题而生的。
但你可能已经发现了另一个问题：现在市面上的Spec Coding工具------比如GitHub的Spec Kit、开源的OpenSpec------它们解决的是"规范化"问题，但真实企业场景的痛点远不止于此。
腾讯后端团队的技术负责人rickyshou在用了三个月Speckit后总结道：
"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的约束能力。
改一行Spec的成本，远低于改一百行代码。
2.2 目录结构：前后端分离 + 资产独立
这是整套框架的物理基础。每个Feature都是一个独立的原子单元，自带完整上下文。
bash
期次-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
markdown
# 项目全局宪法
## 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
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
markdown
# 原子任务：后端 - 用户登录接口
## 📝 变更履历
| 日期 | 版本 | 变更摘要 | 作者 |
| :--- | :--- | :--- | :--- |
| 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
markdown
# 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配置（始终生效）
markdown
---
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）--- 开创新范式
makefile
传统模式: 需求变更 → 直接改代码 → 文档滞后 → 知识丢失
SpecCore: 需求变更 → 先更新 Spec → 记录变更履历 → 再改代码Hotfix 例外流程：
- 允许紧急修复跳过反向同步（30 分钟内止血）
- 24 小时内强制补录
- 图谱标记
⚠️ 待反向同步，不可签署完成
4.2 原子任务按需加载
对比实验数据（自述）：
| 模式 | Token 消耗 | 上下文完整性 | 复杂项目可行性 |
|---|---|---|---|
| 普通 AI 对话 | 5K~20K/次 | ❌ 杂乱 | ❌ 容易爆 |
| SpecCore 按需加载 | 2K~5K/次 | ✅ 精准 | ✅ 稳定 |
4.3 模式驱动（Pattern-Driven）
传统 AI 编码：第 11 次做登录，和第 1 次一样从零开始。
SpecCore：每次 Feature 完成后自动沉淀模式，下次 AI 会主动检索：
"这个登录功能我们之前做过，上次踩了 Redis 超时的坑，这次我帮你加上重试机制和降级策略。"
五、设计亮点总结
5.1 架构优势
- 三层分治：全局 / 期次 / Feature 的清晰职责边界，长期规范和短期任务不互相污染
- 原子任务自包含：每个 TASK.md 是完整 AI 执行单元，不依赖外部记忆
- API 契约锚定：OpenAPI 3.0 YAML 作为前后端唯一事实源，消除口径不一致
- 反向同步铁律：L1/L2/L3 分级裁决，AI 行为边界清晰
- 模式库 Auto-沉淀：每个 Feature 完成后 AI 自动提取可复用模式
- 技术参考三级制：全新实现 / 参考实现 / 代码复用的显式区分
5.2 工程实践
- 纯 Markdown + YAML 驱动：无运行时依赖，Git 即可版本管理
- Skill/Rules 分离：「宪法进规则，流程进技能」--- 兼顾 Token 效率和纪律性
- 全员可读：中文优先，降低团队沟通成本
- scaffold 代码骨架：每个 Feature 带可直接运行的工程骨架
- 验收标准量化：10 条精确 AC + 产出物清单 + 签名 --- 彻底消除"差不多"
- 变更履历：每个 Spec 文件都有变更履历表，审计友好
六、部分功能演示
markdown
## 快速开始
# 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-会议预定
markdown
/spec 进度怎么样了
markdown
/spec 开发 Task-001 用户登录/spec 是 SpecCore 的智能入口命令------用户只需输入 /spec 加上自然语言描述，AI 自动识别意图并执行对应的命令。用户不需要记忆框架内的所有命令名称，只需要像聊天一样表达意图。
七、总结：一个框架，三个答案
回到开头提出的三个问题：
| 问题 | 答案 |
|---|---|
| 如何让AI不"失忆"？ | 原子任务按需加载，每个任务只加载5~7个必要文件 |
| 如何让知识不消失？ | PATTERNS模式库持续沉淀，每次开发都是团队的成长 |
| 如何让前后端AI不打架？ | API契约锚定，各司其职，并行开发 |
这套框架的定位是：
"一套面向AI原生团队的、基于规范驱动的、包含多个可复用模式的企业级研发工程框架。"
它不是最重的方案，也不是最轻的，而是在团队协作性 、知识复用性 和流程灵活性 三者之间找到了最佳平衡点的生产级AI研发基座。
核心理念：
让AI在正确的时刻拿到正确的信息，让知识持续沉淀、持续复用。
框架还在持续演进中，欢迎在评论区交流你的实践经验和改进建议。
相关资源：