SDD-RIPER 团队落地指南：如何让整个团队在一周内跑通大模型编程

• 觉醒篇：《从传统编程转向大模型编程》— 为什么必须转

• 内功篇：《AI 原生研发范式》— 完整理论体系

• 本文：落地篇 — 如何在团队里推开大模型编程

SDD 是持久化的大模型上下文与记忆层，用来给模型提供长期一致的轨道、边界和注意力聚焦。

RIPER 是审批驱动的状态机，用来约束模型的执行顺序、推进权限与单步粒度，确保只有在用户 review / approve 后才进入下一阶段。

你可能已经知道大模型编程很强，自己也试过几次，效果不错。但当你想在团队里推广时，发现：

• 有人不敢用——怕代码质量出问题，怕上线有雷

• 有人不会用——没有方法、没有流程，自己摸索两次就放弃了

• 有人用了但效果差——Vibe Coding 一时爽，上下文腐烂、审查瘫痪、维护断层接踵而来

• 老板问你"效果怎么量化"——你说不出具体数据

• 有人觉得“我们业务太复杂、项目太多，这套方法很难落地”——怕仓库太大、链路太长、跨项目太多，AI 根本吃不下

本文给你一套可执行的团队落地方案：从安装到试点到全面推开，一周内让整个团队跑通大模型编程，并且质量可控、效果可量化。

• 核心判断：AI 编程最大的坑不是模型不够聪明，而是团队没有机制约束 AI。

• 量化收益：Bug 率（Java）可降 **18%**，非主语言可降 **37%**；需求周期可从1、2 周缩短到 3、4 天。

• 启动门槛：团队可在5 分钟完成安装，用sdd_bootstrap跑通第一个需求。

• 复杂业务适配：项目越复杂、跨项目越多，越不能靠临时对话和全仓盲扫，越需要Spec + CodeMap + ProjectMap这套索引式协作方式。

• 治理抓手：先建立一条规则就够了：未经Plan Approved不得改代码。

• 扩展阅读：项目全景与导航可查看。

在推大模型编程之前，先理解团队抗拒的根本原因。这不是"观念落后"，而是真实的工程风险：

痛点一：上下文腐烂（大模型的阿喀琉斯之踵）

对话越长，AI 越容易遗忘前文约束，悄悄破坏已有逻辑。这是模型架构的固有局限——无法靠"更强的模型"解决。

你一定见过这种场景：AI 在第 5 轮对话里改了一个函数，到第 15 轮又把它改回去了，还振振有词地说"这是最优方案"。

痛点二：审查瘫痪

AI 秒生成 500 行代码，人根本 Review 不过来。传统的逐行 Code Review 在 AI 编程时代彻底失效——产出速度远超审查速度，质量失控。

痛点三：维护断层

全是 AI 生成的陌生代码，两周后不敢动，改一行崩三处。没有人知道"AI 当时为什么这么写"，代码变成了黑盒。

痛点四：代码不信任

不知道 AI 为什么这么写，不敢上线、不敢重构。很多人因此根本不敢用大模型编程——信任缺失是最大的推广障碍。

💡 这四个痛点不是"用多了就习惯了"能解决的。它们需要系统性的工程方案，而不是个人经验和勇气。

💡 客观而言，SDD-RIPER 并非解决所有工程难题的“银子弹”。它无法消除大模型固有的所有局限性。然而，这套流程的真正威力在于：将思考与执行步骤通过文档（Spec）沉淀并约束。不盲目追求完美替代人类，只要这套方法能切实击破前文所述的四大痛点，在真实的业务场景里带来可见的治理效果和交付提效，它就是现阶段技术团队最可靠的产能放大器。

三大核心场景

场景一：研发提效——新业务快速交付，老业务随时可回

需求周期从 1、2 周压缩到 3、4 天，大型需求从 2 个月缩短到 1 个月。但提效不只是"写得快"——Spec + Code Map 让上下文可持久化，哪怕半年没碰的老项目，20 分钟就能重新进入状态。

线上故障排查、紧急 hotfix，不再依赖"当时写代码的那个人"。

场景二：人力解耦——老业务不再绑定核心研发

核心研发的时间应该花在高价值的事情上。通过 SDD，核心研发一次性沉淀 Code Map + Spec + 约束文档，低经验同学就能在 RIPER 流程约束下稳定交付老业务的日常迭代。

全程有思考留痕、有阶段门禁、有 Review 闭环，交付质量可控——Bug 率不升反降 18% - 37%。核心人力从老需求中释放，投入更有价值的新业务。

场景三：知识不随人走——快速接入，快速交割

一人负责五个项目、跨团队借调、人员轮换——这些都是常态。传统交接靠口头、靠"看代码"，接手周期长、风险高。

Spec 把项目的知识资产从人脑里搬到文档里，交接变成"读 Spec → 按图施工"，接入周期从周级降到天级。无论谁来接手，上下文不丢失，质量不滑坡。

四层代码质量保障

很多团队不敢全面转向大模型编程，核心顾虑就是：代码质量怎么保证？出了线上问题谁负责？

SDD 的回答是：不需要盲目信任大模型，而是建立一套机制让质量可验证、可追溯——

结果：Bug 率不升反降 18% - 37%。有流程约束的大模型编程，质量反而比纯人工更稳定。

先搞清楚一件事：Spec 首先是给人的，不是给大模型的

很多人第一反应是"Spec 是用来喂给大模型的上下文"——这完全搞反了优先级。

Spec 的核心价值是解决人的问题和工程的问题，对大模型的优化只是附赠品：

大模型从 Spec 获益（注意力聚焦、防止上下文腐烂、辅助 Review）当然也是真实的——这套体系确实能让大模型编程的质量和效率显著提升。但如果你只盯着"对大模型有没有用、会不会污染上下文"这个窄面，就容易忽略更大的画面：即使完全不用大模型编程，一个团队如果能做到"先写清楚要做什么、怎么做、风险是什么，再动手写代码"，工程质量和协作效率本身就会大幅提升。

💡 一句话：不要只盯着 Spec 对大模型的影响。Spec 首先是给人看的工程文档——它解决的是团队协作、工程质量、知识传承的问题。对大模型编程的提效是真实且显著的，但那是这套工程纪律带来的额外红利，不是全部。

很多团队第一次接触 SDD-RIPER 时，最大的顾虑不是“不认可”，而是：“我们业务太复杂、代码太多、项目太多，这套东西很难下手。”这其实是一个非常典型的误解。项目越小、链路越短、参与人数越少，越容易靠个人经验、临时对话和直接读代码推进；但一旦进入复杂业务、多项目联动、多人协作、长期维护的状态，单靠聊天记录、口头同步和临场扫描代码，反而最容易失控。所以，复杂不是不适合 SDD-RIPER 的理由，复杂恰恰是更需要 SDD-RIPER 的理由。真正的难点，从来不是“代码太多”，而是下面三件事没有被工程化：

• 没有稳定边界，不知道这次任务到底该改到哪里为止

• 没有统一索引，每次都要重新扫仓、重新认路、重新猜链路

• 没有协作真相源，人和模型都在依赖临时上下文推进而 SDD-RIPER 要解决的，正是这三个问题。在复杂工程里，最容易犯的错误就是试图让模型一次性理解所有项目、所有模块、所有代码。这通常不是最优解。即使模型更强、上下文更长，无差别全量读取依然会带来注意力分散、扫描成本上升、误伤范围扩大和 Review 困难。更稳的方式，是把上下文分成三层：

• Spec：任务级真相源，描述这次要做什么、边界是什么、风险是什么、验证方式是什么

• CodeMap：单项目索引，描述一个项目内部的核心模块、关键链路、入口文件和依赖关系

• ProjectMap：多项目索引，描述多个项目之间的关系、职责分工、接口契约，以及本次任务到底涉及哪些项目

一句话说就是：复杂工程不是让模型读更多代码，而是让模型先找到正确索引，再按需进入正确局部。

三种常见协作模式

模式一：一个主项目 + 若干轻项目

如果业务主体落在一个主项目上，旁边还有一些配置仓、脚本仓、组件仓、网关仓或前端小模块，那么默认以主项目作为workdir。

这时不要让模型无差别扫描所有轻项目，而是让主项目通过ProjectMap只暴露与当前任务相关的轻项目信息，例如：哪个轻项目和本次需求有关、相关目录或模块在哪里、需要触达的接口/配置/页面是什么、建议优先阅读哪几个关键文件。

也就是说，大模型不是“接管整个轻项目”，而是像伸出触手一样，只触达轻项目中与当前任务直接相关的局部代码。这样既能保持上下文聚焦，也能降低跨项目噪音。

模式二：两个主项目并行协作

如果一个需求同时涉及两个主项目，例如前端主仓 + 后端主仓，或者平台主仓 + 业务主仓，那么更适合把父目录作为workdir。

在父目录维护统一的跨项目协作文档，包括联动任务总Spec、两个主项目的职责边界、核心接口与数据流、跨项目验证清单，以及每个项目建议优先阅读的入口和模块。然后每个主项目内部仍然保留自己的CodeMap，让模型在跨项目层面先有总导航，进入具体仓库时再按项目内索引工作，而不是反复全仓盲扫。

模式三：多个项目组成的复杂工程

如果是中大型复杂工程，涉及多个服务、多个前端、多个中台或基础设施仓库，就不能再靠“临时看代码”解决问题，而应该引入强化版ProjectMap，把它当作整个工程的一级导航层。一份有价值的ProjectMap，至少要回答四个问题：

• 这次任务究竟涉及哪些项目

• 这些项目之间如何调用、依赖和传递数据

• 每个项目应该先看哪条链路、哪几个模块

• 哪些项目只是背景信息，哪些项目必须实际修改

推荐固定工作顺序：先看ProjectMap-> 再锁定涉及项目 -> 再进入各项目CodeMap-> 最后按需阅读具体代码。

不要把“无限上下文”当成默认解法

理论上，如果未来模型上下文无限，当然可以把所有项目都放在同一个workdir里统一读取。但在真实工程中，这依然不是最佳实践。

因为CodeMap / ProjectMap的价值，从来不只是节省 token，它们更重要的作用是：

• 给模型建立稳定的注意力边界

• 给团队建立统一的协作索引

• 给 Review 提供明确的审查范围

• 给长期维护留下可复用的工程资产

所以，CodeMap / ProjectMap不是“上下文有限时的临时补丁”，而是复杂工程里的长期基础设施。

SDD (Spec-Driven Development)= 文档驱动开发。核心就一句话：

Code is Cheap, Context is Expensive.代码是廉价的消耗品，文档（Spec）才是昂贵的核心资产。

三条铁律

• No Spec, No Code— 没有文档，不准写代码

• Spec is Truth— 文档和代码冲突时，错的一定是代码

• Reverse Sync— 发现 Bug，先修文档，再修代码

根据团队的任务复杂度，建议采用“轻重分离”的双轨制部署。

Step 1：安装 Skill（1 分钟）

建议团队同时配置以下两个方案以适应不同节奏：

1. 深度流sdd-riper-one（强烈推荐新手起步）：含有完整的自动化原生指令体系。例如跨项目自动发现依赖、强制代码审查（三轴 review）、以及项目后的复用智能归档。由于有着各种常驻指令和阶段门禁护航，能够兼容不同层级的模型，保证复杂下限。对于刚落地的团队，强烈建议先用此版本跑通标准流程。

2. 敏捷流sdd-riper-one-light（熟练后进阶使用）：专为 GPT-5.4 等强模型打造，大幅削减了长篇协议。它会根据任务自动实现Fast / Standard / Deep分流。对于高频的小任务仅仅只需生成一两句话的micro-spec和summary就可以执行落地，极大降低了团队心智阻力。

⚠️注意：此轻量版对大模型的基础推理和上下文能力要求极高，请务必搭配顶级模型（如 GPT-5.4 等）使用，否则极易出现上下文遗忘或边界失控。

安装操作：

1. 打开以及轻量版sdd-riper-one-light独立页面

2. 点击安装/启用这两种版本的 Skill

3. 可选增强：安装以扩充额外 Prompt 效率工具箱

💡 团队建议：推荐新团队一律先使用标准版建立规范；等团队成员对 RIPER 各个阶段烂熟于心后，日常敏捷迭代再切换到 light 版本体验灵感输出。

Step 2：首个需求跑通（4 分钟）

绝大多数情况的中大型系统重写或标准落地（基于 sdd-riper-one）：

在对话中输入：

请启用 $sdd-riper-one，并执行 sdd_bootstrap：- task=<你的任务名>- goal=<你要达成的目标>- requirement=<需求文档路径或简要描述>（如果需求横跨多个代码库可以追加：- mode=multi_project 启用跨库智能依赖发现）

AI 会自动按照 RIPER 流程引导你：

Research（调研）→ Innovate（方案）→ Plan（规划）→ Execute（执行）→ Review（验收）

跟着流程走，第一个超大型需求也能稳定降落。你即使不懂方法论和指令，它也会带你每一步避坑。

如果是日常业务小需求且你已是熟练工（基于 sdd-riper-one-light）：

在初始对话中输入：

请启用 $sdd-riper-one-light，我有个小任务：[简要描述目标，如：更新一下权限文案、修复这儿的空指针]

AI 第一反应就是生成极简的micro-spec+ 简短的操作计划。只要你允许继续，它立刻直接去修改代码并提供 Change Log。这就是“短平快”的大道至简。

Step 3：团队约定（必须）

在团队内达成一个共识：

未经 Plan Approved，不得改代码。

这一条规则就够了。它确保所有人都在 RIPER 流程内工作，而不是"想到哪写到哪"。

在进入 RIPER 实操之前，先建立一个关键的心智模型——你和 AI 之间，每一刻都应该有一个明确的"协作契约"。

很多人用大模型编程效果不好，不是 Prompt 写得差，而是在错误的时机给了错误的指令类型。最典型的三个坑：

坑一：讨论和命令混为一谈

你说"帮我看看这个权限模块，顺便把那个 Bug 修了"——前半句是讨论（你想了解现状），后半句是命令（你想让 AI 动手改）。AI 收到这种混合指令，往往会跳过讨论，直接开始改代码——然后改错了，因为它还没搞清楚现状。

正确做法：一次只给一种意图。

Plan Approved就是讨论和命令的分水岭。在它之前，你和 AI 是在讨论；在它之后，你在下命令。

坑二：每个阶段该要什么产出，搞混了

Research 阶段你要的是分析，不是代码。如果 AI 在 Research 阶段就开始输出代码，说明它"太勤快了"——你需要拉住它。

一句话：每个阶段只产出一种东西。AI 跑偏了就拉回来。

坑三：自由度给错了

AI 的自由度越高，越容易脱离你的掌控。但自由度不是越低越好——Research 阶段如果你限制太死（"只看这三个文件"），AI 可能漏掉关键依赖。

正确的策略是不同阶段给不同的自由度：

💡 记住这个原则：在需要 AI 创造力的时候放开（Innovate），在需要 AI 执行力的时候收紧（Execute）。大部分人的问题是反过来了——该讨论的时候急着让 AI 干活，该干活的时候又让 AI 自由发挥。

本章是整篇文章的核心。读完这一章，你就能独立完成一个完整的 SDD-RIPER 开发流程。

整体流程概览

💡 本质上，与大模型协作的高效模式，等同于指导一位高潜质新人，其核心是一个“结构化的控制闭环”：

1. 第一步：指引其获取信息（精准定位现状）
2. 第二步：要求其总结信息（对齐目标认知）
3. 第三步：人类负责根据信息设计思路和方向（输出核心决策）
4. 第四步：由模型根据思路丰富细节（补充具体执行路径）
5. 第五步：批准后由其执行细节（严格按图施工，生成代码）
6. 第六步：执行完毕共同进行 review（双向验证交付点）
7. 若有偏差或未达标，则退回闭环起点迭代修正

RIPER 流程，正是将这种原本存在于人类心智中的协作逻辑，赋予了严谨的工程封装与门禁限制。

Step 0：Pre-Research（准备输入）

做什么：在正式开始 RIPER 之前，先把 AI 需要的"原材料"准备好。

💰 先理解 SDD 为什么省钱

很多人直觉认为"写 Spec、做 Code Map 这些准备工作不是多花时间吗？"——恰恰相反，SDD 整套方法论的核心经济学就是：用输入 Token 换输出 Token。

大模型的定价结构是：

SDD 的策略是：把需求、约束、代码事实全部写进 Spec，作为高质量输入一次性喂给 AI。结果是：

✅输入 Token 增加（Spec + Code Map + Context），但价格只有输出的 1% - 10%

✅输出 Token 大幅减少——AI 不用反复试错、不用猜需求、不用重复生成

✅对话轮次大幅减少——传统方式可能要 20 轮对话才能改对，SDD 通常 3-5 轮搞定

✅Spec 作为缓存输入反复复用——同一个需求的后续对话，Spec 命中缓存，价格降到 1%

💡 一句话总结：SDD 不是"多做了准备工作"，而是把低效的输出成本转化为高效的输入成本。花 1 块钱的输入，省 10 块钱的输出，效果还更好。

而 Pre-Research（Code Map + Context Bundle）的作用是让 SDD 跑得更快更好：

• Code Map 是索引——让 AI 精准定位代码，不用全量扫描，降低 Token 消耗和响应时间

• Spec 是上下文切片——把海量信息压缩成结构化文档，AI 一次读懂，不用反复追问

• 两者结合，在大项目、老项目上效果尤其显著：项目越大，SDD 的成本优势越明显

三个可选命令：

📍 命令一：create_codemap（代码地图）

什么时候用：当你要改一个不熟悉的模块、接手一个老项目、或者需要梳理复杂链路时。

怎么用：

# 功能级地图（推荐，聚焦于本次任务相关的链路）create_codemap: mode=feature, scope=用户权限模块, goal=梳理权限校验链路# 项目级地图（适合第一次接手整个项目时）create_codemap: mode=project, scope=order-service, goal=输出项目总图与主流程

AI 会做什么：

1. 扫描你指定范围的代码文件

2. 抽取入口点（Controller / Filter / 定时任务等）

3. 追踪核心调用链路

4. 识别外部依赖（数据库、RPC、消息队列等）

5. 标注风险点和不确定项

产出示例（mydocs/codemap/permission-check.md）：

# Code Map: 权限校验模块## Scope权限校验的完整链路，从请求入口到最终鉴权判定。## Entry Points- `PermissionFilter.java:L28` — HTTP 请求拦截入口- `RpcPermissionInterceptor.java:L15` — RPC 调用拦截入口## Core Logic Chain1. `PermissionFilter.doFilter()` → `AuthService.checkAccess()`2. `AuthService.checkAccess()` → `PermissionDAO.queryUserPermission()`3. 特殊分支：`LegacyAuthAdapter.java:L33` 有历史兼容逻辑## Dependencies- 数据库：`t_user_permission` 表- RPC：`UserCenterService.getUserRole()`- 缓存：Redis key `perm:{userId}:{resourceId}`## Risks / Unknowns- RpcPermissionInterceptor 的调用方不明确，可能已废弃- LegacyAuthAdapter 的兼容逻辑是否还需要保留？

⚠️ 注意事项：

• Code Map不是全项目总图，而是聚焦于本次任务相关的功能链路。范围越精准，质量越高

• 老项目第一次做 Code Map 会花 1-2 小时，但这是一次性投入，后续所有人都能复用

• Code Map 是长期资产：每次做新需求时更新一下，项目的知识图谱就慢慢建起来了

• 如果 AI 扫描范围太大导致结果太泛，缩小 scope 重新来

💡 如何应对多项目协同与超大型复杂系统？面对巨型业务链路，单次要求大模型吃透整个系统极易引发幻觉与上下文丢失。这里的破局之道是“节点化拆解与链路重构”：将难以消化的复杂骨干拆分为多个具象、可管理的业务节点，驱动模型针对单个具体节点生成隔离的 Code Map 或模块 README。待各节点的局部解构锁定后，再从架构维度汇总梳理，将它们结成一张完整的系统级调用链路网。对于复杂项目，切忌一口吞咽，务必坚守节点击破的技术法则。

📍 命令二：build_context_bundle（上下文包）

什么时候用：当需求来源分散（PRD + 设计图 + 钉钉讨论 + 历史邮件），需要整理成 AI 能理解的结构化输入时。

怎么用：

# 指定一个文件夹，AI 会读取里面的所有文档并提炼build_context_bundle: ./mydocs/context/raw/permission-refactor

文件夹里放什么：

• PRD / 需求文档（.md / .docx）

• UI 设计图（.png / .jpg）

• 关键讨论记录（从钉钉/邮件复制过来的 .md）

• 历史 Spec（如果有的话）

• 约束文档（安全规范、接口契约等）

AI 会做什么：

1. 逐个读取目录内的文件

2. 提炼需求事实、业务规则、设计约束

3. 识别术语口径和冲突点

4. 标记信息来源和不确定项

产出示例（mydocs/context/_permission-refactor_context_bundle.md）：

# Context Bundle: 权限模块重构## Source Index| 文件 | 类型 | 关键信息 || --- | --- | --- || prd-v2.md | 需求文档 | 细粒度授权需求，支持字段级权限 || security-spec.md | 约束文档 | 权限变更必须审计日志 || dingtalk-discussion.md | 讨论记录 | PM 确认：第一期只做接口级，字段级放第二期 |## Requirement Facts- 统一权限校验入口（当前有 2 个入口，需合并为 1 个）- 支持接口级细粒度授权（第一期）- 权限变更必须写审计日志## Constraints- 不能影响现有的超级管理员逻辑- 必须兼容 LegacyAuthAdapter（至少保留 3 个月）- 性能要求：鉴权延迟 < 5ms## Open Questions- [ ] 字段级权限放第二期，但接口设计是否需要预留扩展？- [ ] LegacyAuthAdapter 3 个月后是否确定下线？

⚠️ 注意事项：

• 文件夹里的文件不需要很规范，AI 会帮你提炼。但信息越完整，产出越好

• 如果有冲突信息（如 PRD 说要做 A，讨论记录说改成 B），AI 会标注出来，你需要确认

• Context Bundle 是一次性消耗品，不需要长期维护（不像 Code Map 是长期资产）

📍 命令三：sdd_bootstrap（启动 RIPER）

什么时候用：每次开始新任务时必须执行。它是 RIPER 流程的启动命令。

怎么用：

sdd_bootstrap:- task=权限模块重构- goal=统一权限校验入口，支持细粒度授权- requirement=docs/prd/permission-v2.md

可选参数（如果前面做了 Code Map 或 Context Bundle）：

sdd_bootstrap:- task=权限模块重构- goal=统一权限校验入口，支持细粒度授权- requirement=docs/prd/permission-v2.md- codemap_ref=mydocs/codemap/permission-check.md- context_ref=mydocs/context/2026-02-28_permission-refactor_context_bundle.md

AI 会做什么：

1. 汇总所有输入（需求 + Code Map + Context）

2. 进行初步分析和背景补充

3. 产出首版 Spec（写入mydocs/specs/_.md）

4. 列出待确认项和下一步动作

5. 自动进入 Research 阶段

⚠️ 注意事项：

• 首版 Spec允许不完整，缺失信息用[待确认]标注，后续在 Research 中补齐

• 如果是小改动（改配置、修文案），可以跳过 Code Map 和 Context Bundle，直接用sdd_bootstrap启动

• sdd_bootstrap 只需要执行一次，后续在同一个对话里继续 RIPER 流程即可

📁 推荐的工程目录结构

mydocs/├── apis/          # 接口契约层：API 定义文档├── codemap/       # 代码拓扑层：功能级/项目级代码地图（长期资产）├── context/       # 原始语料层：PRD、设计图、讨论记录└── specs/         # 核心协议层：SDD Spec 文档（核心资产）

• codemap/是长期资产，每次需求迭代时更新，团队所有人复用

• context/是一次性语料，按需求整理，用完即归档

• specs/是核心资产，每个需求一份 Spec，是代码的"源码"

产出物汇总：

🔍 Step 1：Research（调研与事实锁定）

做什么：让 AI 查清代码现状，锁定事实，消除信息差。绝不允许 AI 瞎猜。

核心原则：

• 每个结论必须有代码出处（文件路径、函数名、行号）

• 不接受"我认为"、"通常来说"——只接受"我在XXX.java:L42看到了YYY"

• 让 AI 主动提问，把不确定的点暴露出来

对话示例：

你：请进入 Research 阶段。基于首版 Spec，逐条核查以下事实：1. 权限校验的入口在哪里？有几个入口？2. 当前的授权逻辑是怎么实现的？3. 有没有历史遗留的特殊处理？请给出每个结论的代码出处。AI：[Research 模式]1. 权限校验入口有 2 个：   - `PermissionFilter.java:L28` — HTTP 请求拦截   - `RpcPermissionInterceptor.java:L15` — RPC 调用拦截2. 授权逻辑在 `AuthService.java:L45-L78`，通过 ...3. 发现一个特殊处理：`LegacyAuthAdapter.java:L33` 有一个 ...我的疑问：- 入口 2 的 RPC 拦截是否还在使用？我没有找到调用方。- Spec 中提到的"细粒度授权"，粒度到什么级别？字段级还是接口级？

⚠️ 注意事项：

• 逼 AI 提问：如果 AI 没有提出任何疑问，说明它在敷衍。主动要求："你有什么不确定的点？"

• 反向复述：让 AI 用自己的话复述需求，检查理解是否一致

• 不要急着进入下一步：Research 不充分 = 后面全部返工。宁可多花 2 轮对话，也不要带着模糊进入 Plan

• 所有发现必须回写 Spec：不要让信息散落在对话里，必须沉淀到 Spec 文档中

完成标准：

• 入口、链路、依赖、风险全部锁定

• 每个结论有代码出处

• 不确定项已在 Spec 中显式标注

• AI 的疑问已全部回答或标记为[待确认]

💡 Step 2：Innovate（方案设计与对比）

做什么：逼 AI 给出 2-3 个方案，对比 Pros/Cons，人类拍板选哪个。

核心原则：

• 禁止只给一个方案——一个方案 = 没有选择 = 局部最优陷阱

• 每个方案必须说清：改哪些文件、影响范围、风险点、工作量估算

• 人类做决策，AI 做分析

对话示例：

你：请进入 Innovate 阶段。基于 Research 的发现，给出 2-3 个方案，每个方案说清：- 核心思路- 需要改哪些文件- Pros（优点）- Cons（缺点）- 风险点- 工作量估算AI：[Innovate 模式]### 方案 A：统一入口 + 策略模式- 核心思路：合并两个入口为一个 `UnifiedPermissionGateway`，用策略模式...- 改动文件：`PermissionFilter.java`, `RpcPermissionInterceptor.java`, 新增 `UnifiedPermissionGateway.java`- Pros：入口统一，后续维护成本低- Cons：改动面大，需要回归测试- 风险：RPC 拦截器的调用方需要确认- 工作量：约 2 天### 方案 B：适配器模式 + 渐进迁移- 核心思路：保留两个入口，新增适配层...- ...### 推荐：方案 A- 原因：虽然改动面大，但一步到位，避免长期维护两套逻辑...

⚠️ 注意事项：

• 如果任务很简单（如改个配置），可以跳过 Innovate，在 Spec 中标注Innovate: Skipped, Reason: 单点修改，无需多方案对比

• 选定方案后，必须回写 Spec，记录选了什么、为什么选

📝 Step 3：Plan（原子级规划）

做什么：把选定的方案拆解为原子级的实施清单，精确到文件路径和函数签名。

这是整个流程的决胜点。Plan 看不懂 = 不准动手。

核心原则：

• 每一步必须精确到：改哪个文件、改哪个函数、怎么改

• 必须包含函数签名（新增的函数/类）

• 必须有明确的执行顺序（依赖关系）

对话示例：

你：请进入 Plan 阶段。基于方案 A，输出原子级实施清单。要求：1. 精确到文件路径和函数签名2. 标明执行顺序和依赖关系3. 标明每一步的验证方式AI：[Plan 模式]### Implementation Checklist- [ ] 1. 新建 `src/main/java/com/xxx/permission/UnifiedPermissionGateway.java`  - `public class UnifiedPermissionGateway implements PermissionChecker`  - `public boolean checkPermission(PermissionContext ctx)`  - `private PermissionStrategy resolveStrategy(RequestType type)`- [ ] 2. 修改 `src/main/java/com/xxx/filter/PermissionFilter.java`  - 将 `doFilter()` 中的权限校验逻辑委托给 `UnifiedPermissionGateway`  - 保留原有的异常处理逻辑- [ ] 3. 修改 `src/main/java/com/xxx/rpc/RpcPermissionInterceptor.java`  - 将 `invoke()` 中的权限校验逻辑委托给 `UnifiedPermissionGateway`- [ ] 4. 新建 `src/test/java/com/xxx/permission/UnifiedPermissionGatewayTest.java`  - 覆盖：HTTP 请求、RPC 请求、无权限、超级管理员四种场景执行顺序：1 → 2 → 3 → 4（1 是基础，2/3 依赖 1，4 最后验证）

⚠️ 注意事项：

• Plan 必须人类审批。看不懂的地方，要求 AI 解释或细化

• 审批通过后，明确回复：**Plan Approved**

• 审批不通过，要求 AI 修改 Plan，直到你满意为止

• Plan 回写 Spec：批准后的 Plan 必须完整记录在 Spec 中

审批检查清单：

• 每一步我都看得懂吗？

• 文件路径和函数签名是否正确？

• 执行顺序是否合理？

• 有没有遗漏的文件或步骤？

• 风险点是否已标注？

🚀 Step 4：Execute（按图施工）

做什么：AI 严格按照 Plan 逐步执行，生成代码。人类只需监督。

核心原则：

• AI 只能按 Plan 执行，不允许自由发挥

• 每完成一步，AI 应报告进度

• 如果执行中发现 Plan 有问题，必须停下来，回到 Plan 阶段修正，不能"偷偷改"

对话示例：

你：Plan Approved。请进入 Execute 阶段，严格按照 Plan 逐步执行。每完成一步，报告进度。如果发现 Plan 有问题，立即停下来告诉我。AI：[Execute 模式]✅ Step 1/4：已创建 `UnifiedPermissionGateway.java`  - 实现了 `checkPermission()` 和 `resolveStrategy()`  - 代码已写入文件正在执行 Step 2/4：修改 `PermissionFilter.java`...

⚠️ 注意事项：

• 关闭 YOLO / 全自动模式：绝对禁止 AI "先斩后奏"

• 如果 AI 在执行中说"我觉得 Plan 可以优化"——拒绝。要么按 Plan 执行，要么回到 Plan 阶段重新审批

• 执行过程中的编译错误、类型不匹配等问题，AI 可以自行修复，但逻辑变更必须报告

• 每一步完成后，在 Spec 的 Execute Log 中打勾记录

Step 5：Review（验收闭环）

做什么：对照 Spec 验收代码，确保"文档说的 = 代码做的"。

核心原则：

• 三角定位：Spec（预期）vs 代码（实现）vs 执行日志（过程），三方交叉验证

• 发现偏差：先修 Spec，再修代码（Reverse Sync）

• 记录所有偏差和风险

对话示例：

你：请进入 Review 阶段。建议执行内部命令 review_execute。对照 Spec 逐条验收：1. Spec 中的每个预期行为是否都已落地？有没有隐性破坏？AI：[Review 模式 - 触发 review_execute 指令]### Review Matrix (三轴审查)| 检查轴 | 结果 || --- | --- || **一：Spec 达成率** | ✅ PASS — 4/4 目标行为已实现 || **二：代码一致性 Diff** | ✅ 无偏差 || **三：代码质量与弱点** | ⚠️ FAIL — 发现一处潜在低级漏洞阻碍上线 |### 发现的高危问题1. `UnifiedPermissionGateway.java:L52` 缺少空指针检查   - 建议：添加 `Objects.requireNonNull(ctx)` 守卫### 结论与 Follow-ups整体结论为 NO-GO，即将退回到 Plan 阶段修补这些高危缺失，并再次下发执行。

⚠️ 注意事项：

• 强烈建议直接利用 Skill 原生的review_execute机制执行严苛的“三轴质量筛查”进行交付定音。

• Review 结果必须回写 Spec（§6 Review Verdict）。如果不通过，回到 Plan 阶段由机器重算。

• Plan-Execution Diff 必须留底：任何偏离 Plan 原先轨道的变动都要说明原因。

📦 Step 6：Archive（知识沉淀与第二大脑复利）

做什么：项目收尾时把中间产出的各种 Spec 进行精简合并，沉淀为团队的长期复用资产。切记大模型代码开发中：遗忘代表着资产的断供。

怎么做：在 RIPER 闭环后，执行极简归档指令archive：

请执行 archive，将刚才此功能的规格和逻辑资产沉淀下来。

AI 会自动抽取项目执行前后的精华，提炼出两份关键资产：

• Human 视角版 (_human.md)：没有碎片的上下文，输出精炼的方案与汇报，可供人去阅读维护同侪 Review。

• LLM 视角版 (_llm.md)：萃取出项目背景、数据结构等，极高浓缩为仅为机器设计的输入切片——它是留给下一次接手项目或修复此 Bug 的 AI 直接恢复上下文的钥匙（这才是组织提效不折旧的核心）。

🔄 关键注意事项汇总

Day 1-2：选一个老需求试点

为什么选老需求？

• 老需求风险低、边界清晰，适合试水

• 正好验证"低经验同学能不能接手老业务"

• 成功了就是一个现成的 case

具体操作：

1. 核心研发花 1-2 小时，对老项目执行create_codemap，产出 Code Map

2. 把需求描述整理成简单的文档（目标 / 范围 / 约束 / 验收标准）

3. 让一位低经验同学用 SDD-RIPER 流程完成这个需求

4. 核心研发只做两件事：审 Plan + 最终 Review

Day 3-4：复盘与调整

复盘清单：

• 需求是否按预期完成？

• Plan 审查是否有效拦住了问题？

• 低经验同学的体感如何？卡在哪里了？

• Spec 文档是否完整、可复用？

• 与传统方式相比，周期和质量有什么变化？

常见调整：

• 如果 Plan 太粗：要求 AI 拆解到文件路径和函数签名级别

• 如果 Research 不够深：补充 Code Map 或 Context Bundle

• 如果同学不习惯：让他先看一遍招式篇的实战案例

Day 5-7：扩大范围

试点成功后，逐步扩大：

1. 第二个需求：换一个人来做，验证流程的可复制性

2. 并行交付：核心研发写 Spec + 审 Plan，多个低经验同学同时按图施工

3. 沉淀模板：把试点中产出的 Spec 作为团队模板，后续需求直接参考

以下数据来自团队真实交付统计：

质量提升

效率飞跃

重度实战验证

💡 这些数据说明：SDD 的价值不是"写得更快"，而是"并行更多、返工更少、决策更稳"。

Q1：用什么模型与配套的 Skill？

团队推行此流程时，现在已支持轻重双轨并行：

Q2：Spec 怎么写？写多详细？

Spec 不是长文，最小结构只需要五个字段：

目标 / 范围 / 约束 / 风险 / Checklist

复杂需求可以扩展为完整 Spec（含 Research Findings、Innovate Options、Plan Checklist、Execute Log、Review Verdict），但先跑起来比写完美更重要。

Q3：老项目 Research 太慢怎么办？

老项目启动慢是不可避免的阵痛。与其反复拖着痛，不如趁这个机会做一次"手术"：

• 专门花 1-2 天，让大模型系统性 Research 项目，沉淀 3-5 份高价值的 Code Map

• 按功能切片沉淀，每次做新需求时补一块，慢慢建起项目的知识图谱

• 这是一次性投入，后续所有人都能复用——越早做，复利越大

Q4：团队里有人不愿意用怎么办？

不要强推，用结果说话：

• 先让愿意尝试的人跑通一个需求，产出数据

• 让不愿意用的人看到：同样的需求，用 SDD 的人 3 天交付，不用的人 2 周交付

• 流程约束比说教有效：只要团队约定了"未经 Plan Approved 不得改代码"，自然就进入了 RIPER 流程

Q5：C3 代码怎么办？能用外部模型吗？

可以用双模协作模式：

• 内部模型（如 Qwen3）：读代码、生成 Code Map、产出脱敏 Spec

• 外部模型（如 Claude 4.5）：基于脱敏 Spec 做架构设计和方案对比

• 代码始终不出内网，Spec 作为中间层隔离敏感信息

Q6：线上出 Bug 了，怎么结合 SDD 快速排查定界？

呼出独家原生内置命令DEBUG（日志验证驱动），向具有 Agentic 能力的模型直接喂送“出事节点日志内容 + 报错的直接结果 + 最原始实现该功能的 Spec”。

它能够将“设计的预期”核准当前“现实的表现差”，并实施漏洞精准的“三角定位”。它甚至会强约束修补 Bug 的顺序也是“先落 Spec 修改方案，然后才是对代码进行补丁修改”，再也不需要纯盲蒙抓取 Bug。

Q7：SDD 协议会不会"污染"大模型的上下文窗口？

这是最常见的质疑之一，答案是：协议本身的静态开销极小，真正的上下文杀手是没有协议时的无序试错。

先看数据：标准版协议（sdd-riper-one）经过精简优化后约 3,000 - 3,500 tokens（详细规则按需从 references 加载），轻量版（sdd-riper-one-light）仅约 800 - 1,000 tokens。对比主流模型 128K - 200K 的上下文窗口，占比分别约1.5%和 **0.5%**——这个开销是完全可控的。

更关键的是，协议内置了三层上下文管理机制来防止膨胀：

1. 分层加载：协议将上下文分为"热/温/冷"三级——每轮只带当前阶段必需的最小信息（热上下文），切阶段时按需加载中间产物（温上下文），历史细节默认不带（冷上下文）。协议主体约 220 行，详细规则按需从 references 目录加载，不是全部塞进每轮对话。

2. 落盘而非留在对话：所有中间产物（CodeMap、Context Bundle、Spec、Review 结论）都持久化到mydocs/目录下的文件里，而不是堆积在对话上下文中。需要时按需回读，不需要时不占窗口。

3. 轻重双轨分流：简单任务用 Light 版的micro-spec + 一句话 summary，只有复杂任务才启用完整协议。Light 版的设计哲学说得很清楚：*"目标不是减少控制力，而是减少低价值常驻 token。"*

反过来想：没有协议约束时，AI 自由发挥产生的大量无效试错、反复返工、重复提问、散落在对话里的碎片信息——这些才是真正的上下文垃圾。SDD 本质上是用结构化的少量 Token，换取大量无序 Token 的节省。

补充澄清：SDD-RIPER ≠ 原教旨 SDD

需要特别说明的是，SDD-RIPER 并非"原教旨 Spec-Driven Development"。原教旨 SDD 将 Spec 视为模型的"操作系统"，要求 Spec 常驻上下文、每轮重载校验——这确实会造成严重的上下文膨胀。SDD-RIPER 的真正内核是 RIPER 状态机，它解决的是"人和 AI 在什么阶段、做什么决策、谁来拍板"的流程控制问题。

在这套体系里，Spec 承担的是两个务实的角色，而非模型的常驻指令：

• 第一任务：给人看的持久化任务上下文——让团队成员能快速理解"需求做到哪了、决策了什么、还有什么风险"。这是组织记忆，不是模型指令。

• 第二任务：给模型的按需注意力聚焦器——只在关键节点（切阶段、Review、发现冲突）才让模型回读 Spec 的相关段落，而不是每轮都灌入。这是按需索引，不是常驻负载。

简言之：RIPER 管流程，Spec 管记录，模型按需取用。这就是为什么 SDD-RIPER 不会像原教旨 SDD 那样污染上下文。

最后，回到本质问题：与其只纠结"协议对大模型到底能不能提效、会不会污染上下文"，不如把视野放宽一点——没有协议时，你的团队在大模型编程中靠什么保证质量、靠什么管理进度、靠什么做知识传承？Spec 对大模型编程的提效是真实的，但对人的工程纪律、对团队的可管理性、对项目的可维护性——这些才是更值得关注的核心价值。

协议资产

组织影响力

• 📣 已向近 10 个团队/部门完成布道与落地推广

• 📊 系列方法论文章 ATA **累计阅读 13,000+、点赞 540+**，钉钉文档阅读近5,000

• 🌐 公众号文章累计 1,220+ 点赞、6,900+ 转发、850+ 收藏，已获得外部行业关注与交流邀约

• 📦 产品化为 Aone Skill + Prompt Market，团队可零成本复用

我自用的agents.md参考：

# 工作指南- 使用中文交流。- 永远不要执行 `git clean`（任何参数，尤其是 `-fdx`）。- `No Spec, No Code`- `No Approval, No Execute`- `Spec is Truth`## Skill 使用约定- 默认使用 `sdd-riper-one`- 仅当任务明显简单、边界清晰、改动很小、无需完整阶段流转时，使用 `sdd-riper-one-light`- 极简单、无需 spec / checkpoint / 分阶段控制的任务，可以不使用 skill## 执行规则- 代码修改前先提交方案并等待我确认；文档修改可直接执行。- 等待确认期间，先将方案收敛到最小改动集，不要无限扩展搜索范围。- 修改文件时，不要一次性重写整个文件；优先小步、分段、少量多次修改。- 除非我明确要求，否则不要做大范围重构、整文件替换或超大 patch。- 多文件改动时，先完成最核心链路的最小可用修改，再逐步补齐。- 不要顺手修改与当前任务无关的内容。- 如果连续 2 轮以上仅阅读/搜索而没有实际修改，先停止继续探索，并明确说明准备修改哪些文件、先改哪一处、为什么。## 命令边界- 除非我明确要求，否则不要主动运行编译、打包、测试、部署、迁移或其他高开销命令。- 除非我明确要求，否则不要主动安装依赖、升级依赖、删除依赖或修改锁文件。- 对可能造成不可逆后果、批量删除、覆盖、重置、迁移或外部写操作的命令，先等待我确认。## Git 边界- 默认严格尊重 `.gitignore` 与所有已忽略路径。- 不要主动使用 `git add -f` / `git add --force`。- 被 `.gitignore` 忽略的内容默认不提交；只有我明确点名路径时，才允许精确提交。## Spec 同步- 当改动影响需求、接口、行为、约束、流程或实现决策时，执行后同步更新 spec。- 纯机械性改动可不更新 spec。