读完本文你将获得一套经过验证的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都是一个独立的原子单元自带完整上下文。期次-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.yamlopenapi:3.0.3info:title:用户认证APIversion:1.0.0paths:/api/v1/auth/login:post:summary:用户登录requestBody:required:truecontent:application/json:schema:required:[phone,password]properties:phone:type:stringpattern:^1[3-9]\d{9}$password:type:stringminLength:6responses: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 4012.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.yamlFeature-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 后端”Qcoderfeature-backend-dev 开发 Feature-001Trae/feature-backend-dev 开发 Feature-001四、三大创新机制深度剖析4.1 反向同步Reverse Sync— 开创新范式传统模式: 需求变更 → 直接改代码 → 文档滞后 → 知识丢失 MySDD: 需求变更 → 先更新 Spec → 记录变更履历 → 再改代码Hotfix 例外流程允许紧急修复跳过反向同步30 分钟内止血24 小时内强制补录图谱标记⚠️ 待反向同步不可签署完成4.2 原子任务按需加载对比实验数据自述模式Token 消耗上下文完整性复杂项目可行性普通 AI 对话5K~20K/次❌ 杂乱❌ 容易爆MySDD 按需加载2K~5K/次✅ 精准✅ 稳定4.3 模式驱动Pattern-Driven传统 AI 编码第 11 次做登录和第 1 次一样从零开始。MySDD每次 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 文件都有变更履历表审计友好六、总结一个框架三个答案回到开头提出的三个问题问题答案如何让AI不“失忆”原子任务按需加载每个任务只加载5~7个必要文件如何让知识不消失PATTERNS模式库持续沉淀每次开发都是团队的成长如何让前后端AI不打架API契约锚定各司其职并行开发这套框架的定位是“一套面向AI原生团队的、基于规范驱动的、包含多个可复用模式的企业级研发工程框架。”它不是最重的方案也不是最轻的而是在团队协作性、知识复用性和流程灵活性三者之间找到了最佳平衡点的生产级AI研发基座。核心理念让AI在正确的时刻拿到正确的信息让知识持续沉淀、持续复用。框架还在持续演进中欢迎在评论区交流你的实践经验和改进建议。相关资源腾讯技术工程认知重建——Speckit用了三个月我放弃了AI 原生研发范式从代码中心到文档驱动的演进OpenSpec - 规范驱动开发工具Spec Kit - GitHub官方仓库本项目github地址 本项目gitee地址
