sdd-riper-one

Category: Development & Coding | Uploader: huisezhiyin | Downloads: 0 | Version: v1.0（Latest）
将 SDD-RIPER 方法论落地为严格可执行流程的技能。用于代码/架构任务中的“功能级与项目级 CodeMap 生成、全模态需求上下文打包、Spec 驱动研发、RIPER 阶段门禁推进”，适用于 Claude/Codex/其他 CLI Agent 的多轮协作开发。
Changelog: Source: GitHub https://github.com/huisezhiyin/sdd-riper
Directory Structure

Current level: skills/sdd-riper-one/
📁 agents/
- 📄 openai.yaml 870 B
📁 references/
- 📄 archive-template.md 1.7 KB
- 📄 sdd-riper-one-protocol.md 28.9 KB
- 📄 spec-template.md 8.7 KB
- 📄 usage-examples.md 12.9 KB
- 📄 workflow-quickref.md 6.6 KB
📁 scripts/
- 📄 archive_builder.py 15.3 KB
📄 README.md 9.1 KB
📄 SKILL.md 13.3 KB
SKILL.md

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

# SDD-RIPER-ONE Skill

## 核心定位

- 先读：`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`

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

- 标准流（中大型任务）：
  - `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` 修正

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

- 目标：多项目场景下保持"局部理解 + 局部执行 + 显式边界"，**用户零额外配置**。
- 详细协议：`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}]`

## 30 秒上手（首页可直接复制）

```text
create_codemap: mode=project, scope=<项目名>, goal=输出项目总图与主流程
build_context_bundle: <需求资料目录路径>
sdd_bootstrap: task=<任务名>, goal=<目标>, requirement=<需求文档或描述>
```

- 小任务可直接从第 3 条开始（先 `sdd_bootstrap`，后补 codemap/context）。

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

### 1) `create_codemap`

- 用途：生成代码索引地图，支持 `feature` / `project`（默认 `feature`）
- **本质**：CodeMap 不只是一张"地图"，而是**上下文的索引与切片**。它把庞大的代码库压缩为可按需加载的局部上下文，让后续对话不必每次全仓扫描，而是通过索引精准定位到相关代码片段。对于老项目/大项目，建议按功能切片逐步沉淀 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 再推进阶段
- `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`
Comments 0
Latest | Hot
Please login before commenting.
No comments yet. Be the first one!
sdd-riper-one

Directory Structure

SKILL.md

Report

Notice
