ralphify-spec

ralphify-spec

平易な英語で記述された反復タスクを、適切な YAML フロントマター、有用なコマンドブロック、Ralph Wiggum メソッドに沿ったプロンプト本文を備えた、有効かつ実行可能な ralphify の ralph ディレクトリ（RALPH.md）に変換します。

ユーザーが ralphify の仕組みを知っている必要はありません。フロントマター、プレースホルダー、shlex の癖について説明しないでください。ユーザーの目標を動作する ralph に変換し、推奨する実行コマンドを提示してください。

これが適している場合

各反復で少しずつ進捗し、停止条件によってループを止められる作業では、ralph が効果を発揮します。

• テストカバレッジをしきい値まで引き上げる
• lint や型チェックのエラーを減らす
• ファイルを別の言語／フレームワークに移植する
• PR のレビューコメントを1件ずつ解決する
• 項目がなくなるまでキューを処理する

タスクが一度きりのもの（「このページにボタンを追加する」「この関数を説明する」など）なら、ralph を使っても効果はありません。1回限りの実装を勧めて、そこで終わりにしてください。

ワークフロー

1. 意図を把握する（質問は最大2～3個）

会話や cwd から推測できないことだけを尋ねてください。ユーザーがすでに回答している質問は省略してください。

1. 1回の実行で、どのような状態になれば完了ですか？（カバレッジが90%を超える、clippy の警告がゼロになる、すべてのレビューコメントを解決するなど）。停止条件と、各反復で ralph が提示するコマンドを決めるために使います。
2. 言語とツールは何ですか？ まず pyproject.toml、Cargo.toml、または package.json を確認し、曖昧な場合にだけ質問してください。
3. 厳守すべき制約はありますか？ 変更しないファイル、コミット形式、スタイルガイドなどです。明確でない場合にだけ質問してください。

コマンドブロック、フロントマターのフィールド、プレースホルダー、YAML については質問しないでください。 変換はあなたの役目です。

2. 名前と配置場所を決める

• ユーザーが名前を指定していない場合は、kebab-case の名前を考えます（coverage-climber、ts-porter、clippy-burndown など）。バリデーター（手順7）で、ralphify が受け付ける正確な文字セットが適用されます。
• デフォルトの配置場所は、現在のリポジトリ内の ralphs/NAME/ です。cwd が適切な配置場所でない場合にだけ確認してください。

3. 正規のテンプレートを使ってひな形を作成し、その後書き換える

ファイルが正しく解析されるよう、ralphify 自身のテンプレートから始めてください。

ralph init ralphs/NAME

ralph が PATH にない場合は、~/.local/bin/ralph（uv tool install ralphify によって配置される場所）を使ってください。ひな形を作成したら、ユーザーのタスクに合わせてファイルを書き換えてください。標準テンプレートのまま提供してはいけません。

4. フロントマターを設計する

references/schema.md が正式なスキーマリファレンスです。正確なルールが必要な場合は読み、このスキルの本文から独自に推測しないでください。

デフォルトのエージェントは、コンテキストから判断します。claude -p --dangerously-skip-permissions（Claude Code）、gemini -p --yolo（Gemini CLI）、または cursor-agent -p（Cursor）を使います。どのハーネスを使うか明確でない場合は、ユーザーに尋ねてください。

リポジトリで自動コミットトレーラーが禁止されている場合は、credit: false を設定してください。

デフォルトの commands は、技術スタックに応じて選びます。

• すべてのリポジトリ：git-log → git log --oneline -10
• Python：tests → uv run pytest、lint → uv run ruff check .
• Rust：tests → cargo test、lint → cargo clippy --all-targets -- -D warnings
• Node/TS：tests → npm test、lint → npm run lint
• 停止条件の確認：スクリプトを作成し（手順5）、./check-done.sh として参照する

ralph を複数の対象で再利用する場合に限り、args を追加してください。それ以外では値を直接指定してください。後から汎用化するのは簡単です。

ガードスクリプト（早期終了パターン）

エージェントを起動する前に確認できる明確な「すべて完了」条件がある場合は、エージェントの呼び出しをガードスクリプトで囲み、agent: にそのスクリプトを指定してください。すべての生成 ralph に含める必要がある反復回数の上限ガードと COMPLETE センチネルガードを含む完全なパターンについては、references/guards.md を参照してください。

クローザーゲート（burn-down-todos 型の ralph のみ）

ループパターンが burn-down-todos（キュー駆動型の ralph で、キューが空になるとクローザーを実行し、オープン PR の作成、スタックのプッシュ、リリースのタグ付けなどを行うもの）の場合、正規スクリプトを両方とも ralph ディレクトリ内の RALPH.md と並べて配置します。

1. assets/next-issue.sh.template → next-issue.sh。キュー読み取りスクリプトです。RALPH.template.md の commands.next-issue から毎回のイテレーションで呼び出されます。標準出力（Path: …／QUEUE EMPTY／QUEUE READ ERROR）を使って、Task ブロックで相互排他の判断を行います。
2. assets/closer-gate.sh.template → closer-gate.sh。クローザーのイテレーションでは、プッシュ、送信、PR の作成、または COMPLETE センチネルの出力より先に、Guard 4 の判定ゲートを通過する必要があります。

両方のスクリプトで同じ PLACEHOLDER_* マーカー（キューディレクトリ、glob、ステータスフィールド、計画ブランチ）を埋め、chmod +x を実行します。また、RALPH.md のクローザーブロックでは、クローザーの 手順1 として CLOSER GATE PASS を必須にします。これは references/guards.md の Guard 4 です。この ralph の形式で確認された失敗はすべて、アイテムごとの作業と同じイテレーションでクローザーを実行し、アイテムがまだ未完了なのに COMPLETE を出力したことに起因するため、このガードが設けられています。

5. シェル機能はスクリプトに記述する

commands[].run は shlex.split で解析されます。パイプ、&&、リダイレクト、$(...) は使用できません。複雑な処理は ralph ディレクトリ内にスクリプトを作成し、./name.sh で参照してください。

commands:
  - name: coverage
    run: ./check-coverage.sh

• スクリプトに実行権限を付与します（chmod +x）。
• ./ プレフィックスを付けて呼び出したスクリプトは ralph ディレクトリをカレントディレクトリとして実行されます。プレフィックスなしのコマンドはプロジェクトのルートから実行されます。
• スクリプトは短く、単一の目的に絞ります。エージェントが確認できるのはスクリプトの出力だけです。

6. プロンプト本文を書く

各イテレーションは新しいコンテキストで開始されます。プロンプトでは、毎回役立つだけの状況を再提示する必要があります。次の正規の構成に従ってください。

1. 役割とループの認識。「あなたはループ内で実行される自律型の {role} エージェントです。」と記述します。## Iteration 見出しの下に {{ ralph.iteration }} を含め、エージェントが現在のイテレーションを把握できるようにします。「最終イテレーションではクリーンアップする」といったロジックに役立ちます。
2. コンテキストリセットの確認。「各イテレーションは新しいコンテキストで開始されます。進捗はコードと git に残ります。」と記述します。エージェントが状態を記憶しようとするのを防ぎます。
3. コマンド出力のセクション。 {{ commands.<name> }} を ## <Title> 見出しの下に配置します。エージェントが確認できるのは、プロンプトに表示されている内容だけです。
4. Task セクション。 1 回のイテレーションで行う作業を正確に記述します。広範な指示よりも範囲を絞った指示が効果的です。「カバレッジを改善する」よりも「テストされていない関数を1つ選んでテストを追加する」のほうが適切です。新しいコンテキストで開始するエージェントが対象を選び、1 回のイテレーション内で完了できるようにします。
5. 停止条件。 ループの「完了」条件を満たしたときにエージェントが出力する <promise>COMPLETE</promise> センチネルを指定します。ralph run の終了後、scripts/run.sh のランナーラッパーが取得したログをこのマーカーについて調べ、見つかった場合は 0 で終了します。見つからない場合は、上限到達による失敗として扱います。（実行途中で早期終了することはありません。ralph は自然に終了するまで実行されます。）
6. ルール。 避けるべきこと、常に行うべきことを箇条書きで記述します。
7. コミット規約。 1 イテレーションにつき 1 コミットとし、形式（Conventional Commits またはリポジトリのスタイル）と、プッシュするかどうかを指定します。

burn-down-todos 型の ralph では、Task セクションは相互排他ブロックにする必要があります。アイテムごとの作業、クローザー、リカバリーはそれぞれ異なるイテレーション形式であり、キュー読み取り出力（Path: …／QUEUE EMPTY／QUEUE READ ERROR）に基づいて選択されます。アイテムごとのイテレーションは明示的な STOP マーカー（ITERATION DONE: <id>）で終了します。クローザーのイテレーションは Guard 4 の closer-gate.sh から開始し、CLOSER GATE PASS がなければ先に進みません。正規の構成は assets/RALPH.template.md に用意されています。コピーしてプレースホルダーを埋め、アイテムごとの手順とクローザーの手順が同じイテレーションで実行されないようにしてください。

HTML コメント（``）はエージェントに渡す前に除去されます。そのため、保守用のメモに安全に使え、トークンを無駄にしません。

7. 同梱スクリプトで検証する

同梱のバリデーターをドラフトに対して実行します。これは必須のチェックです。省略したり、チェック内容を頭の中で再実装したりしないでください。

uv run --with pyyaml python scripts/validate.py PATH/TO/RALPH.md

（このスキルが配置されている場所に合わせて、スクリプトのパスを調整してください。）

references/schema.md に記載されたスキーマルール（必須フィールド、名前の正規表現、shlex の安全性、プレースホルダーの網羅性、PATH 上のエージェント、タイムアウトの型）を検証します。終了コード 0 は問題なし（警告は参考情報）、1 は修正が必要なエラー、2 は環境の問題を示します。

警告にも注意してください。宣言されているものの使われていないコマンドや引数は、整理が必要なサインです。

8. ランナーラッパーを組み込む

このスキルの scripts/run.sh を、生成した ralph ディレクトリに RALPH.md と同じ階層でコピーします（または ralphs/NAME/run.sh としてシンボリックリンクを作成します）。ラッパーを ralph ディレクトリ内に置くと、実行コマンドが自己完結し、ディレクトリを移動または共有してもラッパーが ralph と一緒に移動します。このラッパーは、素の ralph run では実施されない反復回数上限のルールを適用します。

• -n / --max-iterations が指定されていない場合は、開始を拒否します。生成する ralph にはすべて上限を設定する必要があります。
• 上限値を含む起動バナーを表示し、人が上限を把握できるようにします。
• ralph run の終了後、取得したログを検索して <promise>COMPLETE</promise> が見つかれば終了コード 0 で終了します。見つからない場合は、CAP HIT WITHOUT COMPLETE バナーを表示してゼロ以外の終了コードで終了します。黙って処理を続行することは禁止されています。（実行中に早期終了することはありません。ralph は上限到達、エラー、または --stop-on-error によって自然に終了するまで実行されます。）

ガードの契約全体については references/guards.md を参照してください。

9. 結果を報告する

ユーザーに次の内容を示します。

1. 作成したディレクトリの ファイルツリー。
2. 1 回の反復で行うことを説明する 1 文。
3. 最初の実行例： ralphs/NAME/run.sh ralphs/NAME -n 50 -t 1800 -s -l ralphs/NAME/logs — 50 回の反復、30 分のタイムアウト、エラー時に停止、ログを保存します。ラッパーのパスは手順 8 の「ralph ディレクトリにコピーする」という指示に沿っています。2 つ目の ralphs/NAME は、ラッパーが ralph run に渡す ralph ディレクトリ引数です。まず -n 50 でループの動作を確認でき、無制限に実行することもありません。ラッパーは上限の指定を必須とします。

やってはいけないこと

• ralphify がサポートしていない frontmatter フィールドを作らないでください。スキーマは意図的に小さくしてあります。agent、commands、args、credit 以外の項目は不要です。
• run: 内でコマンドをパイプしたり、連結したりしないでください。スクリプトを使用してください。
• 対応する宣言のないプレースホルダーを残さないでください。プレースホルダーは文字列のまま表示され、エージェントを混乱させます。
• ralphify の内部仕様についてユーザーに質問しないでください。YAML を自分で書きたければ、ここには来ていません。
• 初回実行時に -n を無制限に設定しないでください。まず -n 50 から始めてください。ランナーラッパーがこれを適用します。
• <promise>COMPLETE</promise> センチネルを省略しないでください。明示的な終了条件のないループは、上限に達するまでトークンを消費し、終了理由も曖昧になります。
• 項目ごとの作業と同じ反復内でクローザーが実行できる Task ブロックを含む、burn-down-todos 用の RALPH.md を生成しないでください。1 回の反復で行うのは、どちらか一方の作業（または復旧）です。複数を同時に行うことはありません。項目ごとのステップは ITERATION DONE: <id> で終了し、クローザーはプッシュや COMPLETE ステップを実行する前に CLOSER GATE PASS が成立するまで待機します。この構成を省略することこそ、Guard 4 が防ごうとしている失敗です。

同梱スクリプト

# Validate a draft RALPH.md against the v0.3.0 schema.
#   exit 0 = clean, 1 = errors, 2 = environment problem
uv run --with pyyaml python scripts/validate.py PATH/TO/RALPH.md

# Wrap `ralph run` so the iteration cap is mandatory and the COMPLETE
# sentinel decides the exit code. Forwards every other flag to ralph run.
scripts/run.sh PATH/TO/RALPH_DIR -n 50 -t 1800 -s -l PATH/TO/RALPH_DIR/logs

参考資料

• references/schema.md — フロントマターの正確な ルール（v0.3.0）が必要な場合に参照してください。必須フィールド、正規表現の制約、デフォルト値を記載しています。
• references/guards.md — 新しい ralph のガードの設計時に参照してください。 反復回数の上限、COMPLETE センチネル、クローザーゲート（Guard 4）、 エージェント実行前の短絡処理、標準の next-issue.sh、よくあるバグを記載しています。
• assets/RALPH.template.md — バーンダウンTODOループの開始点として、新しい ralph ディレクトリにコピーしてください。 PLACEHOLDER_* マーカーはその場で置き換えてください。
• assets/next-issue.sh.template — バーンダウンTODO型の ralph では、RALPH.md と同じ場所にコピーしてください。 テンプレートの commands.next-issue が各反復で実行する、キュー読み取りスクリプトです。
• assets/closer-gate.sh.template — バーンダウンTODO型の ralph では、RALPH.md と同じ場所にコピーしてください。 キューディレクトリ、glob、ステータスフィールド、計画ブランチを補完し、クローザーをゲートします（Guard 4）。