⚡️ SDD-RIPER: AI-Native Development Protocol

The Constitution for Human-AI Collaboration.
像指挥军团一样指挥 AI，而不是像保姆一样修补代码。

📖 30秒读懂 SDD-RIPER

SDD (Spec-Driven Development) 是一套为大模型编程量身定制的研发协议。它将程序员的角色从“代码产出者”重定义为**“意图定义者”**。

核心公式

Spec (Truth) + AI (Execute) = Software 2.0

⚡️ 为什么你需要它？

大模型有四个绕不开的工程痛点：

• 🧠 上下文腐烂（大模型的阿喀琉斯之踵）：对话越长，AI 越容易遗忘前文约束，悄悄破坏已有逻辑——这是模型架构的固有局限，无法靠"更强的模型"解决
• 👀 审查瘫痪：AI 秒生成 500 行代码，人根本 Review 不过来，质量失控
• 🔌 维护断层：全是 AI 生成的陌生代码，两周后不敢动，改一行崩三处
• 🤔 代码不信任：不知道 AI 为什么这么写，不敢上线、不敢重构——很多人因此根本不敢用大模型编程

🎯 一句话：这个项目解决了什么问题？

AI 编程最大的坑不是"AI 不够聪明"，而是"人管不住 AI"。

你一定遇到过：AI 聊着聊着就忘了之前的约束，改着改着就把旧逻辑搞坏了，生成 500 行代码你根本审不过来，两周后再看全是"AI 写的陌生代码"不敢动……

SDD-RIPER 就是为了解决这些问题而生的——一套让 AI 围绕文档干活的研发协议，配套可一键安装的 Skill，让你从"被 AI 带着跑"变成"指挥 AI 按图施工"。

真实场景验证（数据来自团队真实交付统计）

• ✅ 在百万行 Java 代码的遗留系统上，用 Code Map 战术 20 分钟梳理清楚核心链路
• ✅ 零 Java 经验的情况下，靠 SDD 协议完成复杂业务需求开发
• ✅ Bug 率显著下降：主语言 -18%，非主语言（Go/Python/Node.js）-37%
• ✅ 日常需求周期：12 周 → 34 天；大型需求：2 个月 → 1 个月
• ✅ 大客户交付人力：节省 40%，团队整体效率 +55%
• ✅ 30 天 10.8 亿 Token 重度实战，四窗口并行，核心人员只做阶段性 Review

典型应用场景

组织影响力

• 📦 提供可复用的双版本 Skill（sdd-riper-one-light + sdd-riper-one）
• 📚 提供配套协议、方法论文章与落地教程，形成完整学习路径
• 🧩 支持从个人试用到团队推广的渐进式落地
• 🔐 文档以仓库内可审阅内容为主，便于统一治理与脱敏维护

🚀 快速开始

方式一：使用 Skill（推荐 - 开箱即用）

Skill 是什么？ 将 SDD-RIPER 协议封装为可执行命令的配置文件，让 AI 自动遵循相应工作流。

先选版本

• 默认推荐 sdd-riper-one-light：适合强模型时代的主力工作流。
• 复杂任务升级到 sdd-riper-one：需要完整 Research -> Innovate -> Plan -> Execute -> Review 时使用。

安装步骤

1. 选择你的 AI 平台

   • Claude Desktop / Claude.ai：复制选定版本的 SKILL.md 到 Custom Instructions
     • Light: skills/sdd-riper-one-light/SKILL.md
     • Standard: skills/sdd-riper-one/SKILL.md
   • Cursor：将选定版本的 SKILL.md 复制为项目根目录的 .cursorrules 文件
   • 其他 AI Agent：查看对应安装指南
     • Light: README
     • Standard: README

2. 验证安装

   在 AI 对话中输入：create_codemap
   或直接要求先复述任务理解，再建立/更新最小 spec，并输出 checkpoint。
   如果 AI 识别并按协议执行，说明安装成功 ✅
   

3. 开始第一个任务

   Light 示例：

   请启用 $sdd-riper-one-light，并先用你自己的话复述对任务的理解，明确核心目标、边界和暂不处理项；然后建立/更新最小 spec，给我 checkpoint；获批后再执行：
   - task=用户登录功能
   - goal=实现完整的登录流程
   - requirement=docs/requirements/login.md
   

   Standard 示例：

   create_codemap: mode=project, scope=my-project
   build_context_bundle: ./docs/requirements/
   sdd_bootstrap: task=用户登录功能, goal=实现完整的登录流程
   

核心命令速查

📖 完整文档：Light 使用指南 ｜ Standard 使用指南

方式二：手动遵循协议

如果你不想安装 Skill，也可以手动引导 AI 遵循 RIPER 流程：

1. 选择协议文件（根据任务复杂度）

   • 标准任务：SDD-RIPER-ONE.md
   • 文档生成：RIPER-DOC.md
   • 复杂重构：RIPER-5.md

2. 在对话开始时发送

   请阅读并严格遵循以下协议：
   [粘贴协议文件内容]
   

3. 手动推进阶段

   现在进入 Research 阶段，请调研代码库现状...
   现在进入 Plan 阶段，请输出详细的实施计划...
   Plan Approved，现在进入 Execute 阶段...
   

🔄 The RIPER Loop (标准作业流)

我们强制 AI 遵循以下五步状态机，拒绝"一发入魂"的幻觉代码：

graph LR
    R[🔍 Research<br>调研/事实锁定] --> I[💡 Innovate<br>方案设计]
    I --> P[📝 Plan<br>原子级规划]
    P -->|Human Sign-off| E[🚀 Execute<br>按图施工]
    E --> V[👀 Review<br>反向验收]
    V -->|Fix Spec| P

1. Research: 拒绝瞎猜，先查代码库现状。
2. Innovate: 审讯式设计，寻找最优解。
3. Plan: 核心环节。输出详细步骤，人类批准后才准动手。
4. Execute: 无脑执行，不仅是 Coder，更是 Builder。
5. Review: AI 自查 + 生成验收报告。

📂 协议资产清单

📚 深度阅读 (Deep Dive)