huisezhiyin/sdd-riper

Lightweight AI Agent Harness for agentic coding: let strong models explore while humans steer with minimal specs, checkpoints, approval, validation, and reverse sync.

SDD‑RIPER Light – 编码代理的控制平面

是什么 – 一个极小、原生于仓库的框架，让大型语言模型（LLM）编码代理能够在真实代码库中工作，同时保持人类对目标、边界、审批和证据的掌控。它不试图取代提示；而是添加一个轻量级的“ harness”，将代理的工作流结构化为明确的检查点、规格、验证步骤和可逆地同步回项目。

为何重要 – 现代 LLM 现在可以修改文件、运行工具并验证结果。瓶颈已从编写代码转向控制这一活动，以确保工作保持可观测、可恢复和可审计。SDD‑RIPER 在不强加重型、以规格驱动流程的前提下，提供了这种控制。

核心概念

概念	角色
人类拥有	目标、边界、权限、检查点、接受标准、完成证据
代理拥有	探索、实现、迭代、工具使用
项目保留	规格、上下文索引、验证证据、恢复状态、可复用知识

该框架围绕四种“技能”（小型、自包含的脚本或提示）构建，LLM 可以调用它们：

sdd‑riper‑one‑light – 日常编码、文档编辑、错误修复或普通重构的默认低摩擦框架。它强制执行相同的底层规则（重述任务、要求规格、等待审批、证明完成），但设置最少的关卡。
sdd‑riper‑one – 用于高风险工作、多文件重构、审计就绪追踪或训练数据收集的更严格版本。增加更丰富的规格和更密集的产物。
codemap – 为不熟悉或大型代码库生成代码地形索引。代理会生成一个功能级地图，包含入口点、调用链、风险点以及下一步应阅读的最小代码片段。
new‑chat‑ready – 为交接、长时间暂停或新聊天会话打包一个简洁的“简历包”。它将仓库快照到受保护分支，清理敏感数据，并可选地创建直接的 Codex 线程。

典型会话流程

读取上下文 – 代理加载当前循环所需的最小仓库片段。
重述目标与风险 – 代理重复任务，识别核心目标，概述最小规格和“完成契约”（何为完成，如何证明）。
检查点 – 人类审查重述、规格和验证计划；在任何文件更改前必须明确批准。
执行 – 代理进行更改，运行工具/测试，收集证据。
验证 – 证据（测试、日志、截图、手动检查）与“完成契约”进行比对。
反向同步 – 经验证的结论被写回规格、交接文档或项目记忆中。

所有步骤都保持活跃上下文小，并将持久状态保存在聊天之外，从而实现恢复和审计能力。

快速启动提示（日常任务用）

使用 sdd-riper-one-light 完成此任务。
不要立即更改文件。

首先提供：
- 你对任务的理解
- 本次循环的核心目标
- 最小规格 / 概要
- 完成契约：何为完成，以及如何证明
- 下一步行动
- 风险
- 验证方法

在执行前等待我的批准。

其他技能也采用相同模式，只需替换技能名称并调整请求（例如，让 codemap 创建代码地形索引）。

仓库布局（需添加到任何项目中）

<repo>/
  AGENTS.md                # 项目特定的代理规则
  skills/
    codemap/
    new-chat-ready/
    sdd-riper-one-light/
    sdd-riper-one/

AGENTS.md 可以是项目本地的，也可以是系统级模板（examples/global-agents.md）。
四个技能目录包含 LLM 所需的提示、模板和参考文档。

何时使用哪个技能

技能	理想场景
`sdd‑riper‑one‑light`	日常编码、文档、错误修复、低风险重构
`sdd‑riper‑one`	高风险、多文件变更、审计或训练数据收集
`codemap`	首次处理大型或遗留代码库
`new‑chat‑ready`	交接给其他工程师或 LLM、长时间暂停、上下文重置

安全与卫生规则（来自 README）

无规格 → 无代码 – 在任何实现前，必须存在最小的真相源。
无审批 → 无执行 – 人类必须明确批准每个检查点。
基于证据的完成 – 测试、日志、截图或手动检查必须证明“已完成”。
反向同步 – 已验证的结果写回规格或项目记忆。
永远不要提交运行时数据、密钥或私有日志 – 将 .agent-memory/、.expcap/、.env 等加入 .gitignore。
提交任何捕获的会话前先清理示例。

谁可能受益？

希望利用 LLM 进行真实代码变更，同时保留控制权的个人开发者。
构建内部“编码代理”且需要审计追踪和清晰交接协议的团队。
希望在不采用重型规格驱动流程的前提下，正式化 AI 增强开发工作流的组织。

快速入门

克隆仓库并将 skills/ 文件夹复制到自己的项目中。
创建 AGENTS.md（或使用提供的模板）以定义项目特定规则。
使用 LLM（如 Claude、Codex、GPT‑4）运行快速启动提示，并遵循检查点循环。
对于不熟悉的代码，先调用 codemap；对于交接，调用 new‑chat‑ready。

总结

SDD‑RIPER Light 不是新的 LLM 模型；它是一个控制平面，让现有编码代理能够在真实仓库中安全、透明地运行。通过强制执行明确的目标、规格、审批和证据，它将工程价值从原始代码生成转向协调AI驱动的工作。