# Sdd Riper One

> 将 SDD-RIPER 方法论落地为严格可执行流程的技能。用于代码/架构任务中的“功能级与项目级 CodeMap 生成、全模态需求上下文打包、Spec 驱动研发、RIPER 阶段门禁推进”，适用于 Claude/Codex/其他 CLI Agent 的多轮协作开发。

- Skill: `hiboys/sdd-riper-one` (Agent Skill, multi-file: 12 files)
- Install (CLI): `npx skillmds@latest add hiboys/sdd-riper-one`
- Raw SKILL.md: https://api.skillmd.com/api/skills/hiboys/sdd-riper-one/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: AI & ML
- Author: hiboys (https://skillmd.com/u/hiboys)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/hiboys/sdd-riper-one

---


# SDD-RIPER-ONE Skill

## 全局行为与安全底线 (Global Safeguards)

- **高危操作阻断**：永远不要静默或提议执行 `git clean`（包含任何参数，特别是 `-fdx`），防止用户未提交的工作区数据不可逆丢失。
- **研发纪律**：
  - `No Spec, No Code`：未形成并持久化 Spec 前，不进入代码实现。
  - `No Approval, No Execute`：未得到执行许可前，禁止进行环境修改或高风险变更。
  - `Spec is Truth`：任何聊天决议或最新改动必须回源到 Spec，Spec 是唯一真相源。

## 核心定位

- 先读一次：`references/sdd-riper-one-protocol.md`
- 总纲：`Pre-Research -> RIPER`，全程遵循 SDD 并持续维护 Spec
- 三条底线：`No Spec, No Code`、`Spec is Truth`、`Reverse Sync`
- `create_codemap` / `build_context_bundle` 是 Pre-Research 输入准备；`sdd_bootstrap` 是 RIPER 启动命令（进入 Research 第一步，同时完成 Pre-Research 收口）
- RIPER 主流程：`Research -> (Innovate, 可选) -> Plan -> Execute -> Review`
- 不要在每轮对话里重载整份 Skill / Spec；默认只回读当前阶段需要的小节
- **Spec 受众分层与上下文保护**：Spec 的第一受众是人类（持久化的任务上下文与组织记忆），第二受众才是模型。协议对模型的核心价值是四件事：**注意力聚焦**（让模型在当前阶段只关注该关注的）、**信息索引**（需要时按路径回读，而非全量常驻）、**防止上下文腐烂**（用落盘的 Spec 对抗长对话中的遗忘与漂移）、**辅助 Review**（提供 Spec vs 代码的交叉验证基准）。协议绝不应导致上下文被塞满挤爆——RIPER 管流程，Spec 管记录，模型按需取用。

## 推荐流程（直接执行）

- 标准流（中大型任务）：
  - `create_codemap -> build_context_bundle -> sdd_bootstrap -> Research -> (Innovate, 可选) -> Plan -> Execute -> Review`
- 快速流（小任务/需求模糊）：
  - `sdd_bootstrap -> （按需补）create_codemap/build_context_bundle -> Research -> Plan -> Execute -> Review`
- 门禁：
  - 首版 spec 落盘前，不进入实现
  - 未收到精确字样 `Plan Approved`，禁止进入 `Execute`
  - `Review` 不通过，回到 `Research/Plan` 修正

## 上下文装配规则

- `SDD` 是完整持久化上下文与记忆层：必须完整落盘、持续维护，但不要求每轮整份常驻输入
- `RIPER` 是审批驱动状态机：必须在每轮保持当前 `phase`、当前批准状态与下一步动作清晰可见
- 裁剪目标是减少重复重放，不是减少约束或弱化门禁

### 热上下文（每轮必带）

- 当前 `phase`
- 当前 `approval status`
- 当前 `spec path`
- 当前 `Goal`
- 当前 `In Scope / Out of Scope`
- 当前活跃 `Checklist`
- 当前 `Open Questions`
- 当前风险与 `Next Action`
- 热上下文只用于当前轮聚焦，不替代完整 spec；与 spec 冲突时，永远以 spec 为准

### 温上下文（切阶段或高风险动作前加载）

- `Research -> Plan`：`Research Findings`、关键事实、方案结论
- `Plan -> Execute`：`File Changes`、`Signatures`、原子 `Checklist`
- `Execute -> Review`：`Validation`、实际改动摘要、偏差说明
- 执行 `review_spec` / `review_execute` 时，回读对应评审区块

### 冷上下文（默认不带，命中再加载）

- 全量 `Change Log`
- 历史 `Research` 细节
- 完整 `codemap`
- 完整 `context bundle`
- `MULTI` / `DEBUG` / `ARCHIVE` 的完整扩展规则
- 长示例、长模板、长 quick reference

### 硬门禁（不可因裁剪而削弱）

- 没有 spec，不进入代码实现
- `phase` 与 `approval status` 必须是显式状态，不允许根据语气、倾向或不完整表述推断
- 没有精确字样 `Plan Approved`，不进入 `Execute`
- phase 切换前，必须回读对应 spec 区块；不能只靠热上下文跨阶段推进
- `Review` 时必须基于 plan 与 validation，而不是只看聊天摘要
- 发现冲突、字段缺失、摘要过期或记忆不确定时，立即回读完整 spec 或相关原文区块

### 回读触发规则

- **每轮必带**：`phase`、`approval status`、`spec path`、`Goal`、当前活跃 `Checklist`、`Next Action`
- **切阶段时**：回读目标阶段对应的 spec 区块（Research Findings / File Changes / Validation 等）
- **执行 review 时**：`review_spec` 回读 Plan 区块，`review_execute` 回读 Plan + Validation + Review 区块
- **触发全量回读**：阶段切换有争议、摘要与 spec 冲突、长对话出现遗忘迹象、高风险改动
- **禁止**：不能用热上下文替代 spec 原文跨阶段推进，不能根据模糊语气推断 `Plan Approved`

## 多项目协作（自动发现 + 作用域隔离）

- 目标：多项目场景下保持"局部理解 + 局部执行 + 显式边界"，**用户零额外配置**。
- 详细协议：`references/sdd-riper-one-protocol.md` → `MULTI-PROJECT PROTOCOL` 段
- Spec 模板：`references/spec-template.md` → 多项目模板

### 自动发现（Auto-Discovery）

- 触发：`sdd_bootstrap: mode=multi_project` 或触发词 `MULTI / 多项目`
- Agent 自动扫描 `workdir` 下子目录，通过标志文件识别子项目：
  - JS/TS: `package.json` | Java/Kotlin: `pom.xml`, `build.gradle` | Go: `go.mod` | Python: `pyproject.toml`, `setup.py` | Rust: `Cargo.toml` | 通用: `.git`
  - Monorepo: 额外检查 `workspaces`、`settings.gradle`、`pnpm-workspace.yaml`
- 产出 `Project Registry`（`§0.1`），报告给用户确认后继续
- 用户也可显式提供 `projects=[...]` 跳过自动发现
- 智能降级：仅 1 个子项目 → 自动降级为单项目模式；0 个子项目 → workdir 本身作为单项目

### 自动 Codemap

- 发现项目后，自动为每个子项目检查/生成 `create_codemap(project)`
- 产物路径：`mydocs/codemap/YYYY-MM-DD_hh-mm_<project_id>项目总图.md`

### 作用域隔离规则（必须）

- 每轮先声明 `active_project` 与 `active_workdir`
- 默认 `change_scope=local`，只允许修改 `active_project` 下的文件
- 仅在显式 `change_scope=cross`（或触发词 `CROSS / 跨项目`）时允许跨项目改动
- 始终 `codemap-first`：切换到任何项目前，必须先加载该项目的 codemap/context
- 跨项目执行后，在 spec `§6.1 Touched Projects` 记录改动项目、文件、原因

### 跨项目依赖与契约

- 跨项目改动时，必须在 spec `§4.4 Contract Interfaces` 记录：Provider → Interface → Consumer → 是否 Breaking Change → 迁移方案
- 跨项目 Plan 的 checklist 按项目分组，Provider 优先于 Consumer 执行
- 修改前检查目标项目是否有活跃 Spec，有冲突则 STOP 等待用户决策

### 多项目 Review（扩展）

- 校验跨项目契约一致性（Provider 与 Consumer 接口匹配）
- 校验 Touched Projects 完整性
- 校验无孤立改动（所有改动文件都在已注册项目内）
- 按项目分别评估回归风险

### 触发词

- `MULTI / 多项目` → 进入多项目模式，运行自动发现
- `CROSS / 跨项目` → 当前轮 `change_scope=cross`
- `SWITCH <project_id> / 切换 <project_id>` → 切换 `active_project`，自动加载 codemap
- `REGISTRY / 项目列表` → 显示当前 Project Registry
- `SCOPE LOCAL / 回到本地` → 重置为 `change_scope=local`

### 最小启动示例

```text
sdd_bootstrap: mode=multi_project, task=<任务名>, goal=<目标>, requirement=<需求文档或描述>
```

- 无需手动列项目，Agent 自动发现并确认。
- 也可显式指定：`projects=[{id:web-console,path:./web-console},{id:api-service,path:./api-service}]`

## 原生命令动作（可直接输入）

### 1) `create_codemap`

- 用途：生成代码索引地图，支持 `feature` / `project`（默认 `feature`）
- 本质：CodeMap 是代码上下文索引，用于后续按需加载，而不是每轮全仓扫描。
- 输入：`scope`（建议明确）；`mode` 可选；`goal` 可选
- 输出：
  - `feature`：`mydocs/codemap/YYYY-MM-DD_hh-mm_<feature>功能.md`
  - `project`：`mydocs/codemap/YYYY-MM-DD_hh-mm_<project>项目总图.md`
- 要点：
  - `feature` 关注入口、核心链路、依赖、风险
  - `project` 关注架构层、核心模块、跨模块流程、外部依赖；图示建议优先 Mermaid（受限可降级为结构化文字图）

### 2) `build_context_bundle`

- 用途：整理需求上下文，替用户读资料并提炼细节
- 输入：目录路径
- 解析策略：best effort，支持文本/文档/图片；不可解析文件进入 `Unparsed Sources`，不阻塞产出
- 输出：`mydocs/context/YYYY-MM-DD_hh-mm_<task>_context_bundle.md`
- 输出级别：
  - `Lite`：`Source Index`、`Requirement Snapshot`、`Open Questions`、`Next Actions`
  - `Standard`：`Requirement Facts`、`Business Rules`、`Acceptance Criteria`、`Constraints`、`Conflicts & Ambiguities` 等

### 3) `sdd_bootstrap`

- 用途：RIPER 启动命令（进入 Research 第一步，并产出第一版 spec）
- 输入：只要是“有意义且真实的需求”即可（口述/文档/聊天记录/context bundle 均可）
- 执行动作：
  - 汇总用户输入 + 代码事实 + 历史资产（codemap/context/spec）
  - 冲突处理：先落首版 spec 标记冲突，再给 `Option A/B` 和推荐决策
  - 形成首版研究结论与下一步动作
- 输出：`mydocs/specs/YYYY-MM-DD_hh-mm_<TaskName>.md`
- 首版最小内容：`Context Sources`、`Codemap Used`、`Research Findings`、`Open Questions`、`Next Actions`

### 4) `review_spec`

- 用途：在 `Plan` 完成后、`Execute` 前进行 spec 质量评审（建议性，不阻塞执行）
- 输入：
  - `spec`：spec 文件路径（可选，默认当前活跃 spec）
  - `scope`：`plan_only`（默认）或 `full`
- 评审重点：
  1. 目标/范围/验收标准是否清晰且可验证
  2. `Plan` 是否可执行（文件、签名、checklist 是否原子化）
  3. 风险、回滚、跨项目契约（如有）是否充分
- 分阶段原则：
  - 仅评审“当前阶段应当具备”的章节，不要求一次性覆盖全 spec
  - 对尚未到阶段的章节只做 `Reminder`，不计入 `NO-GO`
- 输出：
  - `Spec Review Matrix`（逐项 `PASS/FAIL/PARTIAL` + 证据）
  - `Readiness Verdict`：`GO/NO-GO`（**建议性结论**）
  - `Risks & Suggestions`（若继续执行需关注项）
  - `Phase Reminders`（按阶段待补齐项）
- 约束：
  - `NO-GO` 不构成硬阻塞；若用户坚持执行，允许继续
  - 用户选择继续时，必须在 spec 记录 `User Decision: Proceed despite NO-GO`

### 5) `review_execute`

- 用途：在 `Execute` 后执行结构化评审，输出可回写 spec 的审查结论
- 输入：
  - `spec`：spec 文件路径（可选，默认当前活跃 spec）
  - `scope`：`changed_only`（默认）或 `full`（全量评审）
- 评审三轴（必须全部输出）：
  1. **Spec 质量与目标达成**：spec 是否写清目标、范围、验收标准；需求是否完成
  2. **Spec-代码一致性**：代码是否忠实执行 `Plan`（文件、签名、checklist、行为）
  3. **代码自身质量**：脱离 spec 后，代码在正确性、鲁棒性、可维护性、测试、风险上的质量
- 输出：
  - `Review Matrix`（三轴逐项 `PASS/FAIL/PARTIAL` + 证据）
  - `Overall Verdict`（`PASS/FAIL`）与 `Blocking Issues`
  - `Plan-Execution Diff`（偏差与原因）
- 门禁：
  - 轴 1 或轴 2 任一 `FAIL` -> `Review FAIL`，回到 `Research/Plan`
  - 轴 3 存在高风险问题 -> `Review FAIL`，回到 `Plan`

### 6) `archive`

- 用途：对指定 spec/codemap（或目录）做归档沉淀，将“中间产物”提炼为可复用知识
- 输入：
  - `targets`：文件或目录路径（支持多个）
  - `kind`：`spec` / `codemap` / `mixed`
  - `audience`：`human` / `llm` / `both`（默认 `both`）
  - `mode`：`snapshot`（单任务归档，默认）/ `thematic`（跨任务主题归档）
  - `topic`：归档主题名（可选，默认从 targets 推断）
- 输出：
  - `human`：`mydocs/archive/YYYY-MM-DD_hh-mm_<topic>_human.md`（汇报视角）
  - `llm`：`mydocs/archive/YYYY-MM-DD_hh-mm_<topic>_llm.md`（后续开发参考视角）
  - 每个归档文档必须包含 `Trace to Sources`（结论 -> 来源文件）避免失真
- 门禁：
  - 有活跃执行中的 spec（未完成 Review）时，禁止归档该 spec
  - 默认只归档不删除原文件；删除/移动需用户显式授权
- 自动化脚本（推荐）：
  - `python3 scripts/archive_builder.py --targets mydocs/specs mydocs/codemap --kind mixed --audience both --mode thematic --topic <主题>`
  - 如需强制归档活跃 spec：追加 `--allow-active-spec`（仅在用户明确确认后使用）

## 阶段约束（最小集合）

- 每轮先同步 spec 再推进阶段
- 默认不在每轮对话中重载整份 spec；优先回读当前阶段区块、活跃 checklist、`Open Questions`、最近一次 `Change Log / Validation`
- 仅在切换阶段、执行 `review_spec/review_execute`、发现冲突或明显遗忘时，全量回读 spec
- `codemap` / `context bundle` 按需读取，不作为每轮固定输入
- `Innovate` 可选：复杂任务建议 2-3 方案；小任务可跳过但要写原因
- `Plan` 必须可执行：文件路径 + 签名 + 原子 checklist
- `Plan` 后建议执行 `review_spec`；其 `NO-GO` 为建议项，不是强制门禁
- `Review` 必须按三轴评审并回写结论：`Review Matrix`、`Overall Verdict`、`Plan-Execution Diff`
- 任务闭环后建议执行 `archive`，沉淀 human/llm 双视角知识

## Debug 模式（日志驱动排查与功能验证）

- 用途：基于日志 + Spec + 代码三角定位 Bug，或用全链路日志验证功能是否正常
- 触发词：`DEBUG / 排查 / 日志分析 / 验证功能`
- 输入：
  - `log_path`：日志文件或日志目录路径（必须）
  - `issue`：发现的问题描述 / 报错信息（可选，排查模式时建议提供）
  - `spec`：关联的 Spec 文件路径（可选，验证模式时建议提供）
- 两种子模式：
  - **排查模式**（默认）：用户提供日志 + 问题描述，Agent 结合 Spec 和代码定位可能的 Bug 根因
  - **验证模式**：用户提供全链路日志 + Spec，Agent 逐条比对 Spec 中的预期行为与日志中的实际行为，确认功能是否正常
- 工作流：
  1. 读取日志文件/目录，提取关键错误、异常、调用链信息
  2. 加载关联的 Spec 和 CodeMap（如有），建立"预期行为 vs 实际行为"的对照
  3. 定位代码中的可疑逻辑（结合 CodeMap 索引精准跳转）
  4. 输出结论：Bug 根因分析 / 功能验证报告
  5. 如需修复，自动进入 RIPER 流程（Research → Plan → Execute → Review）
- 约束：
  - Debug 模式本身不直接改代码，只做分析和定位
  - 需要改代码时，必须走 RIPER 流程（或 FAST 通道处理小修复）
  - 分析结论回写到 Spec 的 `§ Debug Log` 段（如有活跃 Spec）

## 触发词

- `MAP / Code Map / 链路梳理 / 只看代码` -> `create_codemap(feature)`
- `PROJECT MAP / 全局地图 / 项目总图 / MAP ALL` -> `create_codemap(project)`
- `MULTI / 多项目` -> 多项目轻量模式（父目录 workdir + 局部执行）
- `CROSS / 跨项目` -> 允许跨项目改动（强制记录 `Touched Projects`）
- `FAST / 快速 / >>` -> 小改快速通道（改后同步 spec）
- `REVIEW SPEC / 评审规格 / 计划评审` -> 执行 `review_spec`（建议性预审）
- `REVIEW EXECUTE / 代码评审 / 实现复盘` -> 执行 `review_execute`（三轴审查）
- `ARCHIVE / 归档 / 沉淀` -> 执行 `archive`（总结、合并、精炼）
- `DEBUG / 排查 / 日志分析 / 验证功能` -> Debug 模式（日志驱动排查与功能验证）
- `EXIT SDD / 退出协议` -> 退出状态机

## 命名规则（统一时间前缀）

- 时间前缀：`YYYY-MM-DD_hh-mm_`
- `create_codemap(feature)`：`mydocs/codemap/YYYY-MM-DD_hh-mm_<feature>功能.md`
- `create_codemap(project)`：`mydocs/codemap/YYYY-MM-DD_hh-mm_<project>项目总图.md`
- `build_context_bundle`：`mydocs/context/YYYY-MM-DD_hh-mm_<task>_context_bundle.md`
- `sdd_bootstrap`：`mydocs/specs/YYYY-MM-DD_hh-mm_<TaskName>.md`
- `archive(human)`：`mydocs/archive/YYYY-MM-DD_hh-mm_<topic>_human.md`
- `archive(llm)`：`mydocs/archive/YYYY-MM-DD_hh-mm_<topic>_llm.md`

## 参考

- `references/sdd-riper-one-protocol.md`
- `references/spec-template.md`
- `references/workflow-quickref.md`
- `references/usage-examples.md`
- `references/archive-template.md`
- `references/multi-project.md`（多项目协作详细规则）
- `references/commands.md`（原生命令动作详细参数）