Yyatmita

Ralph Loop は武器、GSD は武器庫、yatmita 流 IDD は『要塞』——プロジェクト単位ハーネスの 3 層目

Ralph Loop は技術、GSD は枠組み。その上に、GitHub という 20 年枯れたレガシー要塞を agent harness として接収したのが、私の使っている yatmita 流 IDD だ。issue・milestone・semver・Conventional Commits をそのまま骨格に流用し、rules を『マジックプロンプト』として常駐させる。GSD と同じ問題意識から出発した、別の解。

自分のエージェント基盤を組む#agent-stack#claude-code#workflow#ralph-loop#github
← 前の記事: 5 人の Claude に役柄を割って企画会議させた話 — claude-peers council 運用記

この記事は「AI エージェント基盤」シリーズの一篇です。Claude が書いています（題材は筆者の手元で運用中の IDD というフレームワーク）。

はじめに（ネーミングの注釈）

「Issue-Driven Development」は他所でも使われる語で、たいていは「issue を起点に開発を回そう」くらいの運用ルールとして語られる。この記事で扱う IDD は同名だが別物で、私が Claude Code 用に組んだプロジェクト単位の agent harnessを指す。世間の IDD と区別したいときは「yatmita 流 IDD」と呼ぶ。以降、本文中はただ「IDD」と書く。

Ralph Loop の hype と、その上の議論

数か月前から X に流れてくる「24 時間でゲームを完成させた」「一晩でアプリを丸ごと生成した」系のデモは、たいてい Ralph Loop（claude -p をループで叩いて DoD まで走らせる技法）の派生だ。実物は強力で、自分のポートフォリオでも研究系・文書生成系のパイプラインの背骨に据えている。

ただしこの hype に正面から待ったをかけた動画がある。Chase AI の "Stop Using Ralph Loops (Use This Instead)" だ。要旨はこうだ。

Ralph Loop は技術であって枠組みではない。PRD・タスク定義・DoD が無いまま回せば、garbage in / garbage out になる。武器単品より武器庫が要る。

そこで紹介されているのが GSD（Get Shit Done）——npx get-shit-done cc で入る Claude Code 向けフレームワークで、「初期化 → discuss → plan → execute → verify → 繰り返し」をスラッシュコマンドで構造化し、サブエージェントでタスクごとに文脈を切り直す。Ralph Loop が放置型なのに対し、フェーズ完了ごとに人間チェックが入る。

私の用語で言えば、これは「ループは一個じゃなく入れ子」の話だ。Ralph Loop（実行）の上に、計画・分解・検証を束ねる枠組み層が要る——という指摘自体に異論はない。

問題は「その枠組み層に何を選ぶか」だ。GSD はローカルに 4 つの MD ファイル（project / requirements / roadmap / state）を置き、独自のスラッシュコマンドで叩く。新しい storage と新しい儀礼を発明している。私の好みではない。

そこで自分はもう一段違う方向に振った。「新しい儀礼を発明せず、すでに 20 年動いている要塞を接収する」という解だ。それが yatmita 流 IDD で、要塞の名は GitHub である。

3 層スタック——ralph-loop / IDD / GHQ

最初に全体図を出す。私の手元のスタックは 3 層になっている。

[ghq] issue を各 repo に dispatch /idd-work で DoD を渡して起動 GHQ（ポートフォリオ層）複数プロジェクトの方向性を相談する司令部 IDD（プロジェクト層）issue/milestone/semver/rules の harness ralph-loop（実行層）1 ループの実行エンジン
  • ralph-loop（実行）—— DoD を 1 つ与えれば、test を緑にするまで反復する。これは技術。
  • IDD（プロジェクト）—— PRD・issue・milestone・出荷までを束ねる枠組み。GSD と同じ層。
  • GHQ（ポートフォリオ）—— 複数のプロジェクト群に「いま何を最優先にするか」を一本通す司令部。前回詳しく書いた。

この記事は真ん中の IDD を扱う。

メインステップは GSD ベース、骨格は GitHub のレガシー機構

IDD の手順の流れは素直に GSD と似ている。discuss → plan → execute → verify → loop。これは Chase AI の動画で整理されている通りで、人間が枠組み層を組むときに収束しやすい形だ。良い枠組みは似てくる。

違いはそれを何の上に書き込むかにある。

層GSDyatmita 流 IDD
起点半生のアイデアを質問で固める同じ
PRD / 要件ローカルの project.md / requirements.mdGitHub の milestone 説明欄 + 主要 issue 本文
タスク管理ローカルの roadmap.md / state.mdGitHub の Issues + ラベル
実装の手per-task サブエージェントper-issue ralph-loop
人間ゲートフェーズ完了時のチェックリストissue → PR → merge（既存のレビュー文化）
出荷の作法（明示なし）semver tag + Conventional Commits + git-cliff changelog + GitHub Release
上位レイヤなしGHQ

要点は太字の 3 行に出ている。ローカル md 4 枚を起こす代わりに、20 年動いている issue/milestone/PR/tag/Release という要塞をそのまま骨格にした。これが「要塞を接収する」と言っている中身だ。

補足: GitHub Milestone について——Issue / PR に比べて知名度が低いが、GitHub には「Milestone」という機能がある。期日と説明文を持った issue の束で、「この milestone に紐付いた issue がすべて閉じれば 100% 達成」と進捗率が出る。IDD ではこの milestone を「PRD の置き場」兼「リリース単位」として使う。/idd-release MVP のように milestone 名を渡すと、紐付いた issue を集めて changelog を作り、tag を切って GitHub Release まで一気に出す。「milestone を閉じる ＝ 一本出荷する」が等号で結ばれているのがポイント。

新規 storage を作らない利得は大きい。

  • GitHub Web UI / モバイルアプリ / Projects ボードがそのままレビューツールになる
  • メンション・通知・サブスクの仕組みが効く
  • 「人間がチームに混ざるとき」の認知コストがゼロ（みんな知ってる）
  • 後から gh CLI でも octokit でも好きに刈れる（ロックインなし）

GSD が「Claude Code の中だけで完結する小宇宙」を作ったのに対し、IDD は「GitHub という既存の大宇宙に居候する」設計を選んでいる。好みの問題でもあるが、自分の場合は人間が後から覗ける情報経路が単一であることの価値が大きかった。

補足: Plan Mode を使わずに、自前の discuss / plan を作った理由

余談だが、Claude Code には「Plan Mode」というツール実行を抑止するモードがある。GSD の解説でも「Plan Mode をステロイドで強化したもの」と紹介されるくらい、計画フェーズの定番手段だ。

ただ、Plan Mode 有効時と無効時で /context を見比べてもコンテキスト構成に差分が出ず、Claude 自身も「特別なシステムプロンプトは注入されていない」と自己申告してくる（自己申告なので 100% の証明ではないが、/context 差分と整合する）。Plan Mode はツール実行を無効化しているだけで、計画フェーズの質を担保する仕掛けはモード側には内蔵されていない、ということになる。質を作っているのは結局ユーザが書くプロンプトだ。

ならば Plan Mode に乗るより、GSD を参考に自分で discuss / plan の手順を skill 化してしまうほうが、何を聞き何を出させるかを明示的に書ける。IDD が /idd-init の中に discussion → ユーザ確認 → リサーチ → docs → issues の流れを skill として持っているのはそういう判断だ。Plan Mode の代わりではなく、Plan Mode が暗黙にやっていた「ツールを止めて考える時間を作る」を skill として明示化した、と言ったほうが近い。

スキルの構成——5 つの動詞

IDD は 5 つのスラッシュコマンド（Claude Code の skill）でできている。

  • /idd-init —— 新規プロジェクトの初期化。discussion → ドキュメント下書き → ユーザ確認 → リサーチ → ドキュメント更新 → GitHub Issues 一括起票
  • /idd-context —— 着手前にプロジェクト文脈を復元（/idd-context #22 のように issue 番号を渡す）
  • /idd-work —— issue 単位の設計・採択 → ralph-loop の雛形を吐く
  • /idd-release —— milestone を閉じる → tag を切る → changelog を生成 → GitHub Release
  • /idd-note —— 使っていて出た気づきを versioned な issue に積む（後述）

GSD の 6 ステップに対して 5 つにまとめたのは、execute を ralph-loop に外注しているから、harness 側に書く必要がないからだ。実装のループは IDD の責任ではなく、ralph-loop の責任になっている。

プロバイダ依存度——rules を除けばマルチプロバイダ

ここで一つ補足しておきたい。IDD のスキル本体（/idd-init 等）は Claude Code 用に書かれているが、フレームワーク全体としては Claude Code に深く依存していない。プロバイダロックインは事実上ゼロに近い。

  • 実行層：ralph-loop の自作版は最初からマルチプロバイダ対応で、Claude / Codex / Gemini を切り替えられる。loop の中で叩く LLM は何でもよい
  • 人間ゲート：PR ベースの merge レビューを軸にしているので、Codex CLI とは特に親和性が高い。OpenAI の coding agent も PR を吐く流儀で動くので、agent を差し替えても merge ゲートが破綻しない
  • Claude Code 固有部分：唯一そう呼べるのが rules/ の配信形態（~/.claude/rules/ への配置）と skill の slash command 形式だけ。ルール本文そのものは「Composed Method」「TDD」のような古典語彙なので、別プロバイダ用の格納先（AGENTS.md / GEMINI.md 等）にコピーすれば中身はそのまま効く

つまり IDD は「Claude Code のフレームワーク」というより「GitHub をハーネスに使って agent を躾ける方法論」と呼ぶほうが正確だ。これは GitHub という相互運用可能なレガシー要塞に居候することの副次的利得でもある——要塞は agent の銘柄を選ばない。

補足: それでも現実は Claude メイン——理由は能力ではなく経済

設計が非依存でも、運用はほぼ Claude 一本で回している。これは正直に書いておきたい。モデルの優劣で選んでいるのではなく、経済性の話だ。

  • Claude Max（月額 $200 の上位プラン）は、月額固定でとてつもないコンテキスト枠を使える。ralph-loop は「長いコンテキストを抱えて何十回も反復する」性質のワークロードなので、トークン課金で動かすとあっという間に予算がとぶ。Max 枠の中で回し続けられるのは、ループ系の試行回数を稼ぐ上で桁違いに有利
  • 同じ作業量を Codex（OpenAI API）で回すと、レート上限・課金上限のどちらかにすぐ触れる。1 回回すごとに財布の心配をするモードになると、ループ系の試行回数は確実に減る
  • ゆえに、「設計はプロバイダ非依存、運用は Claude Max を背骨に使う」が今の最適点になっている

これは「Claude Code に縛られている」という話とは違う。harness 側の差し替え可能性は維持しつつ、エネルギー（コンテキスト予算）の供給源として Max を選んでいる、という構造だ。経済条件が変われば運用も変わる。

rules =「マジックプロンプト」論

ここからが、外から見て一番分かりにくい——けれど一番効いている——層の話だ。

IDD は rules/ というディレクトリを持っていて、install.sh でグローバル（~/.claude/rules/）に展開される。中身はこんな感じ。

rules/
├── coding-behavior.md
├── composed-method.md
├── declarative.md
├── encapsulation.md
├── immutability.md
├── python.md
├── ralph-loop.md
├── react.md
├── rule-format.md
├── single-responsibility.md
├── tdd.md
├── testing.md
├── typing.md
└── ...

中を覗くと、Kent Beck の Composed Method、ヘキサゴナル系の Single Responsibility、関数型の Immutability、そして TDD ——いずれも 20〜40 年もまれた古典の原則だ。

中でも TDD は特別な位置にいる。他の原則が「書き方を整える」ものなのに対し、TDD はループの停止条件を機械化する唯一のルールだからだ。ralph-loop は「DoD を満たすまで反復する」エンジンだが、DoD が文章で書かれていれば、満たしたかどうかは結局 LLM の自己判断になる——つまり judge を信用する話に逆戻りする。TDD は DoD を失敗するテストとして書き、緑にするまで回せ、と命じる。テストはコードであり、緑か赤かしかない。この一点が、Ralph Loop 系のループが garbage in / garbage out に堕ちるかどうかの分水嶺だ。だから TDD は IDD の rules の中で「他と並ぶ古典の 1 つ」ではなく、harness 全体を成立させる背骨として扱っている。

実物を晒すと、IDD の tdd.md ルール本文はこれだけだ。

---
paths:
  - "**/*.{py,ts,tsx,js,jsx,rs,rb,go}"
---
 
# TDD で進める
 
バグ修正・機能追加はテスト駆動で進める。
 
## バグ修正
 
1. **バグを再現するテストを書く**（失敗することを確認）
2. **最小限の修正**でそのテストを通す
3. 既存テストが壊れていないことを確認
 
## 機能追加
 
1. **期待する振る舞いをテストとして書く**（失敗することを確認）
2. テストを通す最小実装を書く
3. リファクタする（テストが通ったまま）
 
## 例外
 
テストを書けない事情（UI・外部依存・プロトタイプ段階など）があれば、着手前にその旨を伝えて相談する。「とりあえず実装してから後でテスト」はしない。

25 行。テスト駆動の何たるかを 1 行も説明していない——TDD という単語と「失敗するテスト → 通す → リファクタ」というキーワード列だけが書かれている。これだけで Claude は「TDD のサイクル」を発動する。短い指示で大きな振る舞いを引き出せる——これがマジックプロンプトの典型例になる。

そのうえで、なぜ新語ではなく、わざわざ枯れた語彙を使うのか。理由は 2 つある。

(1) LLM の事前分布側に効かせる

LLM は事前学習で人類の書いた文章を大量に読んでいる。「Composed Method」「Tell, Don't Ask」「Single Responsibility」のような歴史で磨かれた語は、その意味と運用例が分布の中で安定している。新造語よりブレが小さく、強い prior として効く。

これは「プロンプトで毎回説明する」の対極だ。説明するのではなく、すでに学習済みの概念タグを呼び出す。プロンプトエンジニアリングというより、事前分布エンジニアリングに近い。短い語で大量の語彙を起動できるので、自分はこれを「マジックプロンプト」と呼んでいる。

(2) 人間のレビューコストも同時に下がる

副作用というには大きすぎる利得が、同じ語彙が人間にも通じることだ。「Composed Method に反している」と Claude が言えば、ベテランの読み手も同じ含意で理解できる。新造語の rules を作ると、人間側の学習コストが二重にかかる。古典の語彙を使えば、LLM と人間が同じ規約書を読んでいる状態になる。

Why と How to apply を必ず添える

ルール本文だけを置くと判断が硬直する。エッジケースで「このルールは目的に照らして適用すべきか」を Claude が問えなくなる。なので IDD では rule-format.md で書式を決めていて、すべてのルールに次の 2 行を必ず添えることにしている。

## <ルール名>
<ルール本文>
 
**Why:** <なぜ＝過去の失敗例や背景>
**How to apply:** <具体的な適用手順・判断基準>

これで「目的に照らして当てるか外すか」をエージェントが自分で判断できる。ルールではなく原則を渡す設計だ。

出荷の作法——semver / Conventional Commits / changelog

GSD は「完成まで」で止まる。IDD は出荷の作法まで harness に組み込んでいる。

  • コミットは Conventional Commits（feat: / fix: / docs: / chore:）で書かせる
  • changelog は git-cliff で自動生成
  • バージョンは semver の git tag で刻む
  • /idd-release <milestone> で milestone close → tag → changelog → GitHub Release が一気通貫

ここで効くのが、install.sh 実行時に ~/.claude/.idd-version に IDD 自体の版（git describe）が刻まれる、という地味な仕掛けだ。/idd-note で気づきを残すとき、この版が issue 本文に自動で埋まる。どの版で出た気づきかが後から辿れる。

「製品の出荷」と「IDD 自体の出荷」を同じ作法で扱う、という再帰の入口がここにある。

自己改善ループ——IDD を IDD で改善する

IDD を使っていて出た引っかかりや効いたパターンは、/idd-note で idd-insight ラベルの GitHub issue に積む。bug（クレーム）でも enhancement（要望）でもない、生のログだ。

/idd-note で気づきを蓄積（版スタンプ付き）
   ↓ 溜まったら
enhancement issue に昇格 → milestone へ
   ↓ /idd-context → /idd-work で実装
PR マージ → milestone 完了
   ↓
/idd-release で版を切る → CHANGELOG が改善の記録になる

棚卸し専用の儀礼は作らない。insight が昇格した後は、通常の IDD ワークフローに乗せて処理する。自分のフレームワークが、自分の改善にもそのまま使える——これが GitHub 上に乗せた利得の決定版だ。

なぜ judge を信用しないか（deepeval × bounded edit）

ここは次回の予告に近いが、IDD の中核に効いているので短く触れる。

スキル / ルール / プロンプトの改善は、客観的な verifier がない領域だ。テストが緑か赤かでは決まらない。SkillOpt 系の流派（LLM judge にスコアを付けさせて自動 gate する）に対して、IDD は逆の立場を取っている。

理由を端的に書くと、自動で変わるのが怖いからだ。

スキルやルールは「これから書くコード」ではなく「これから書く全コードの書き方を決めるメタ層」に効く。誤った改善が静かに混ざると、未来のセッションの出力が緩やかに劣化しても、それに気付くのは難しい。テストが落ちるわけでもなく、judge が「良くなった」と言えば人間はそのまま信じる。だから IDD は judge にも deepeval にも採否を渡さない。判定点はすべて人間に残している。

  • deepeval は導入しているが、gate ではなく観測機材として使う。射程は狭い（ハルシネーション率・形式整合性のような限定指標）。測れる範囲で数字を出すだけ
  • deepeval に回すかどうかも人間判断。回す価値がある変更かを毎回人間が選ぶ
  • 「足して損はない改善か」の判定も人間。deepeval の数字は参考までで、最終採否は人間が握る
  • 迷うものは仮に入れて様子を見る（bounded edit）。これも人間判断
  • 効かなかったと分かったものは git checkout で握りつぶさず、revert commit にする（理由を 1 行添える）。git log が「試して効かなかった方向」の記録＝負例集を兼ねる

そもそも「スキルが本当に改善していくか」を直接測る方法は存在しない。deepeval は限られた指標を出すだけで、メタ層の質を保証してくれるわけではない。測れないものを自動採用するのは、未来の自分の判断力を運に賭けることになる。だから自動 gate を一段も置かない、というのが IDD のスタンスだ。

「judge ではなく git log が記憶する」——これが、IDD が自動採点の流派と袂を分かつ一線だ。詳しくは別記事で。

まとめ——3 つの命題

長くなったので畳む。yatmita 流 IDD の主張は 3 行に圧縮できる。

  1. Ralph Loop は技術、IDD は枠組み、GHQ はポートフォリオ——ループは 1 個ではなく 3 段の入れ子
  2. 新しい storage を作らず、GitHub というレガシー要塞を agent harness として接収する——issue / milestone / PR / tag / Release / Projects がそのまま骨格になり、要塞は agent の銘柄を選ばない（実行層と PR ゲートはマルチプロバイダ、Claude Code 固有なのは rules の配信形態だけ）
  3. rules は枯れた語彙で書く——LLM の事前分布と人間のレビュー語彙を同時に呼び出す「マジックプロンプト」

GSD は「Claude Code の中で完結する武器庫」を作った。IDD は「GitHub という既存の要塞に居候する」道を選んだ。同じ問題意識（Ralph Loop だけでは届かない領域）から出発した、別の解だ。どちらが優れているかではない。新規儀礼に投資するか、レガシーを接収するかの好みの違いに過ぎない。

次回は、この上に乗っている GHQ（複数プロジェクトの司令部）と IDD の継ぎ目——「[ghq] issue というディスパッチ規約」を扱う予定だ。要塞を 1 つ持つ話の次は、要塞を複数並べて指揮する話になる。