by huisezhiyin
The Constitution for Human-AI Collaboration: Spec-Driven Development protocol that transforms AI from code generator to reliable builder. Includes RIPER workflow and ready-to-use skills.
# Add to your Claude Code skills
git clone https://github.com/huisezhiyin/sdd-riperThe Constitution for Human-AI Collaboration. 像指挥军团一样指挥 AI，而不是像保姆一样修补代码。
SDD (Spec-Driven Development) 是一套为大模型编程量身定制的研发协议。它将程序员的角色从“代码产出者”重定义为**“意图定义者”**。
Spec (Truth) + AI (Execute) = Software 2.0
大模型有四个绕不开的工程痛点：
| 🚫 痛点 (Without SDD) | ✅ SDD 解法 | | --- | --- | | 上下文腐烂：AI 聊着聊着就忘了前文约束，破坏旧逻辑。 | Spec 锚点：强制 AI 每次行动前读取 Protocol，状态永久"满血"。 | | 审查瘫痪：AI 秒生成 500 行代码，人类根本 Review 不过在这里。 | RIPER Loop：先审 Plan 再写 Code。审逻辑代替审代码。 | | 不可维护：全是 AI 生成的陌生代码，两周后不敢动。 | 文档即源码：代码是消耗品，Spec 才是资产。修 Bug 先修文档。 | | 代码不信任：不敢用大模型写的代码上线，怕有雷。 | 三角定位：Spec + 执行日志 + 代码三方交叉验证，需求是否完成、Bug 出在哪里一目了然，增强信心，让人敢用 |
AI 编程最大的坑不是"AI 不够聪明"，而是"人管不住 AI"。
你一定遇到过：AI 聊着聊着就忘了之前的约束，改着改着就把旧逻辑搞坏了，生成 500 行代码你根本审不过来，两周后再看全是"AI 写的陌生代码"不敢动……
SDD-RIPER 就是为了解决这些问题而生的——一套让 AI 围绕文档干活的研发协议，配套可一键安装的 Skill，让你从"被 AI 带着跑"变成"指挥 AI 按图施工"。
No comments yet. Be the first to share your thoughts!
| 场景 | 痛点 | SDD-RIPER 怎么解 | | --- | --- | --- | | 老业务交接与持续维护 | 遗留系统无人敢动，交接靠口头、靠"看代码"；核心研发不应长期困在老需求里 | Code Map 20 分钟梳理核心链路，Spec 固化业务上下文，低代码经验的同学也能接手老业务的日常迭代和维护，释放核心研发投入新业务 | | 低经验人员交付核心业务 | 新人/跨团队支援不熟悉代码库，上手周期长 | 有 Spec + Code Map 就能按图施工，零 Java 经验也能完成复杂需求 | | 人力紧张时的并行交付 | 核心研发不够用，但需求排不完 | 核心人员只写 Spec + 审 Plan，执行交给 AI + 非核心研发人力，一人指挥多路并行 | | 高敏感代码安全合规 | 核心代码不敢用外部模型 | 先在受控环境中整理抽象接口与约束 Spec，再让外部模型基于抽象 Spec 做设计，原始代码不外发 |
sdd-riper-one-light + sdd-riper-one）Skill 是什么？ 将 SDD-RIPER 协议封装为可执行命令的配置文件，让 AI 自动遵循相应工作流。
| Skill | 定位 | 适用场景 | 目录 |
| --- | --- | --- | --- |
| sdd-riper-one-light | 强模型优化版：checkpoint-driven + 强控制内核 | GPT-5.4、高输入、多轮、高频 coding；核心工作流是先复述任务理解、再强调核心目标、持续总结进度，并保留 No Spec, No Code 与 No Approval, No Execute | skills/sdd-riper-one-light/ |
| sdd-riper-one | 标准版：完整 RIPER 阶段门禁 | 架构设计、复杂重构、跨项目协作、复杂迁移、严格评审 | skills/sdd-riper-one/ |
sdd-riper-one-light：适合强模型时代的主力工作流。sdd-riper-one：需要完整 Research -> Innovate -> Plan -> Execute -> Review 时使用。选择你的 AI 平台
SKILL.md 到 Custom Instructions
skills/sdd-riper-one-light/SKILL.mdskills/sdd-riper-one/SKILL.mdSKILL.md 复制为项目根目录的 .cursorrules 文件验证安装
在 AI 对话中输入：create_codemap
或直接要求先复述任务理解，再建立/更新最小 spec，并输出 checkpoint。
如果 AI 识别并按协议执行，说明安装成功 ✅
开始第一个任务
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=实现完整的登录流程
| 命令 | 用途 | 示例 |
|------|------|------|
| create_codemap | 生成代码地图（功能级/项目级） | create_codemap: mode=feature, scope=登录模块 |
| build_context_bundle | 整理需求上下文 | build_context_bundle: ./docs/requirements/ |
| sdd_bootstrap | 启动 SDD 任务 | sdd_bootstrap: task=用户认证, goal=... |
| FAST | 快速修改（小改动） | FAST: 修改按钮颜色为蓝色 |
| DEBUG | 日志驱动排查 | DEBUG: log_path=./logs/error.log |
📖 完整文档：Light 使用指南 ｜ Standard 使用指南
如果你不想安装 Skill，也可以手动引导 AI 遵循 RIPER 流程：
选择协议文件（根据任务复杂度）
SDD-RIPER-ONE.mdRIPER-DOC.mdRIPER-5.md在对话开始时发送
请阅读并严格遵循以下协议：
[粘贴协议文件内容]
手动推进阶段
现在进入 Research 阶段，请调研代码库现状...
现在进入 Plan 阶段，请输出详细的实施计划...
Plan Approved，现在进入 Execute 阶段...
我们强制 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
| 协议文件 | 适用场景 | 对应模型建议 |
| --- | --- | --- |
| SDD-RIPER-ONE.md | 标准版：主力协议，包含完整闭环。 | Claude 4.5 / GPT-5.1 / Qwen3 |
| RIPER-DOC.md | 文档专家：专门用于生成 README/API 文档。 | DeepSeek V3 / Gemini Pro |
| RIPER-5.md | 严格版：上一代状态机，适合复杂逻辑重构。 | o3 / o4-mini |
| 文档 | 适合人群 | 核心内容 | |------|---------|---------| | 🧠 从传统编程转向大模型编程 | 个人开发者 | 思维转型：如何从工匠变为建筑师 | | 📜 AI 原生研发范式 | 架构师/技术负责人 | 理论体系：为什么 Spec 是新时代的源代码 | | 🚀 团队落地指南 | TL/主管/团队负责人 | 实战指南：如何在一周内让团队跑通大模型编程 |