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）コーディングエージェントが実際のコードベースで作業できるようにする、非常に小さなリポジトリネイティブなフレームワーク。人間が目標、境界、承認、証拠を管理する役割を保持する。これはプロンプトを置き換えるものではなく、エージェントのワークフローを明確なチェックポイント、仕様、検証ステップ、プロジェクトへの元に戻せる同期に構造化する軽量な「ハーネス」を追加する。

なぜ重要か – 現代のLLMはファイルを変更し、ツールを実行し、結果を検証できるようになった。ボトルネックはコードの作成から活動の制御へと移行した。SDD‑RIPERは、重い仕様駆動プロセスを強制せずに、その制御を提供する。

コアコンセプト

コンセプト	役割
人間が所有	目標、境界、権限、チェックポイント、受容基準、完了の証拠
エージェントが所有	探索、実装、反復、ツールの使用
プロジェクトが保持	仕様、コンテキストインデックス、検証証拠、回復状態、再利用可能な知識

このフレームワークは4つの「スキル」（小さな自己完結型スクリプトまたはプロンプト）を中心に構築されており、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）として使用可能。
4つのスキルディレクトリには、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 を呼び出す。

詳細情報を探す場所

skills/sdd-riper-one-light/README.md – 動作するハーネスへの最短距離。
docs/code-is-cheap.md – フレームワークの哲学的動機。
docs/ai-coding-harness-guide.md – タスクのスライス、検証、回復に関する詳細ハウツー。
docs/general-purpose-agents-are-a-trap.md – なぜ専門的で制御されたエージェントは、曖昧な「汎用」ボットよりも優れるのか。

まとめ

SDD‑RIPER Light は新しいLLMモデルではない。既存のコーディングエージェントが実際のリポジトリ上で安全かつ透明に動作できるようにするコントロールプレーンである。明示的な目標、仕様、承認、証拠を強制することで、エンジニアリングの価値は単なるコード生成からAI駆動作業のオーケストレーションへとシフトする。