1. 项目概览#

sdd-riper 是一套给 AI coding agent 使用的 Harness / 工作流技能包。它的核心目标是：让模型负责探索、实现和推进任务，让人类控制目标、边界、权限、checkpoint、验证证据和最终验收。

该项目主要包含 4 个 skills：

• sdd-riper-one-light
  日常默认入口。适合普通 coding、文档、bugfix、轻量重构。它强调低打扰控盘：先复述目标、形成 micro-spec、checkpoint、获批后执行、验证后 reverse sync。

• sdd-riper-one
  重型版本。适合高风险、多文件、跨模块、审计、训练、交接密集任务。它会更严格地走 Research -> Plan -> Execute -> Review，并要求更完整的 spec、checkpoint、验证和留痕。

• codemap
  代码地形索引 skill。用于陌生代码库、大模块、遗留系统或跨仓任务。它不负责直接实现功能，而是帮 agent 找到入口、调用链、风险点、验证入口，让后续任务不用把整个代码库塞进上下文。

• new-chat-ready
  交接与恢复 skill。用于新对话、上下文压缩、handoff、长任务暂停、恢复旧会话，以及把可复用知识同步到项目文档候选中。

工作流概览：

1
日常任务
2
  -> sdd-riper-one-light
3
      -> 必要时引用 new-chat-ready 做 handoff / resume
4
      -> 陌生代码时可先让用户或 agent 切到 codemap
5

6
复杂/高风险任务
7
  -> sdd-riper-one
8
      -> Pre-Research 阶段可调用/采用 codemap 建代码地图
9
      -> 执行闭环后可调用 new-chat-ready 做交接或恢复包
10
      -> 任务清晰后，风格上可降噪接近 light，但门禁仍更严格
11

12
陌生代码任务
13
  -> codemap
14
      -> 产出代码地形索引
15
      -> 供 sdd-riper-one-light 或 sdd-riper-one 后续读取
16

17
长对话/换会话/暂停
18
  -> new-chat-ready
19
      -> 读取当前 spec、codemap、验证结果、git 状态等
20
      -> 产出 handoff 和下一轮 prompt

2. sdd-riper-one 概览#

sdd-riper-one 的完整工作流分为两个阶段：

1. Pre-research：进入正式开发前的上下文准备

这一阶段主要是降低混沌，不着急改代码。主要环节包括：

• create_codemap：
  • 建立代码地形图，搞清楚入口、模块边界、调用链、风险点、验证入口。
• build_context_bundle：
  • 整理需求文档、聊天记录、日志、截图等输入，压缩成可研究上下文。
• sdd_bootstrap：
  • 启动 SDD/RIPER 流程，形成第一版 spec，明确目标、边界、当前任务单元和验证方式。

2. RIPER：正式执行闭环

核心阶段为：

1
Research -> Innovate (可选) -> Plan -> Execute -> Review

• Research：
  • 研究需求、代码、约束和风险，补齐事实，不急着定方案。
• Innovate：
  • 当方案不唯一或风险较高时，提出 2-3 个可选方案并比较取舍。
• Plan：
  • 生成可执行计划，通常要写清文件路径、改动点、检查清单、验证方式。
• Execute：
  • 只有用户明确批准后才进入执行。项目里强调精确门禁：没有 Plan Approved，不进入实现。
• Review：
  • 执行后对照 spec、plan、实际改动和验证结果做复核；如果不通过，要回到 Research 或 Plan 修正。

整体的流程就是：

1
澄清最终目标
2
-> 判断当前任务是否是最小可执行单元
3
-> 建 codemap / context bundle（按需）
4
-> 生成或更新 spec
5
-> Research 补事实
6
-> 可选 Innovate 比方案
7
-> Plan 写执行清单
8
-> 等用户 Plan Approved
9
-> Execute 修改
10
-> Validation 验证
11
-> Review 复核
12
-> Reverse Sync 回写 spec
13
-> 必要时 handoff / archive / new-chat-ready

1
spec = 任务真相源
2
plan = 本轮执行清单

1
Spec:
2
用户登录失败时，需要区分密码错误、账号冻结、验证码过期。
3
不能改变现有成功登录流程。
4
完成证据是相关单测通过，并手测三种失败场景。
5

6
Plan:
7
1. 修改 auth/error.ts，新增错误码映射。
8
2. 修改 login/service.ts，让冻结账号分支返回 ACCOUNT_FROZEN。
9
3. 修改 login/ui.tsx，按错误码展示提示文案。
10
4. 补 login.service.test.ts 三个失败场景。
11
5. 运行 auth/login 相关测试。

3. sdd-riper-one-light 概览#

作为 sdd-riper-one 的轻量实现，它不强调完整的 Research -> Plan -> Execute -> Review 阶段展开，而是强调 checkpoint-driven：用少量关键校准点保证 Agent 不跑偏。

下面是 sdd-riper-one-light 大致的完整工作流：

1
理解任务
2
-> 轻量风险判断
3
-> 建立 micro-spec / 最小 spec
4
-> 写清 Done Contract
5
-> 输出 checkpoint
6
-> 等待批准
7
-> 执行
8
-> 验证
9
-> Reverse Sync
10
-> 必要时留下 resume / handoff

并且内置了几个档位：

1
zero      纯机械小改动，可跳过正式 spec
2
fast      1-3 句 micro-spec
3
standard  默认模式，适合普通多文件任务
4
deep      复杂但还没重到必须用 sdd-riper-one

1. 理解任务

Agent 先用自己的话复述任务，确认目标、范围和已知约束。

官方参考 prompt：

1
请使用 sdd-riper-one-light 处理这个任务。
2
先不要直接改文件。
3

4
请先给我：
5
- 你对任务的理解
6
- 本轮核心目标
7
- 最小 spec / summary
8
- Done Contract：什么算完成，由什么证明
9
- 下一步动作
10
- 风险
11
- 验证方式
12

13
我批准后再执行。

遇到陌生代码时，先建 codemap：

1
请使用 codemap。
2
先创建 feature 级或 project 级代码地形索引，再进入计划。
3
重点关注入口、调用链、风险点、验证入口，以及下一步最小回读代码片段。

2. 轻量风险判断

判断任务是否：

• 过大
• 边界不清
• 高风险

如果明显复杂，就建议升级到 deep 或切换到 sdd-riper-one.

3. 建立 mico-spec 或最小 spec

一般包含：

1
Goal
2
Context
3
Boundary
4
Validation
5
Risk

4. 写清 Done Contract

明确什么算完成，以及由什么证据证明完成。比如测试通过、日志符合预期、截图、人工验收等。

5. 输出 Checkpoint

1
当前目标是什么
2
已确认什么
3
下一步做什么
4
风险是什么
5
怎么验证

6. 等待批准

硬门禁，未获用户明确批准前，不进入实现或高影响变更。

7. 执行

获批后执行改动。light 默认相信强模型能自行拆分局部步骤，所以不会强制写很重的阶段计划。

8. 验证

跑最小有意义的验证，完成必须有证据。

9. Reverse Sync

把实际改动、偏差、验证结果、剩余风险回写到 spec / summary / handoff 中。

10. Project Sync Scan

收尾时判断有没有稳定、可复用的项目知识需要沉淀。没有就说明没有。

11. Resume Ready

如果任务长、要暂停或换对话，留下最小恢复锚点；必要时转给 new-chat-ready.