gists

Ralph の内部ロジック: 1-story ワークフローと LLM 呼び出し

Q. 1-story をつくるのにどんなワークフローを敷いてる？またLLM呼び出しはどうしてる？

---

1-story のワークフロー

prompt.md (= CLAUDE.md) に定義、ralph.sh がループ実行する。

1 イテレーション = 1 story の流れ (prompt.md:5-16):

1. prd.json を読込
2. progress.txt の Codebase Patterns セクションを確認
3. PRD の branchName に沿ってブランチをチェックアウト (無ければ main から作成)
4. passes: false の中で 最高優先度 の user story を 1 つだけ選択
5. その story を実装
6. 品質チェック (typecheck / lint / test)
7. AGENTS.md / CLAUDE.md に再利用可能なパターンがあれば追記
8. 通ったら feat: [Story ID] - [Story Title] でコミット
9. PRD の該当 story を passes: true に更新
10. progress.txt に進捗 (learnings 含む) を追記

全 story が passes: true になったら <promise>COMPLETE</promise> を出力。 ralph.sh 側でこれを grep 検知してループを終了する (ralph.sh:99-104)。

---

LLM 呼び出し

ralph.sh がシェルから CLI を繰り返し起動するだけの構造 (ralph.sh:84-108)。

for i in $(seq 1 $MAX_ITERATIONS); do
  if [[ "$TOOL" == "amp" ]]; then
    OUTPUT=$(cat "$SCRIPT_DIR/prompt.md" | amp --dangerously-allow-all 2>&1 | tee /dev/stderr) || true
  else
    OUTPUT=$(claude --dangerously-skip-permissions --print < "$SCRIPT_DIR/CLAUDE.md" 2>&1 | tee /dev/stderr) || true
  fi

  if echo "$OUTPUT" | grep -q "<promise>COMPLETE</promise>"; then
    exit 0
  fi
  sleep 2
done

ポイント

• 会話を引き継がない。毎イテレーション コールドスタート で prompt.md (または CLAUDE.md) を stdin 投入する。
• 状態は全てファイルに外出し:
  • prd.json — 何をやるか / どこまで終わったか (passes フラグ)
  • progress.txt — 学びの蓄積 (Codebase Patterns / 各イテレーションの learnings)
  • git — 実装そのもの
• 次イテレーションはこれらを再読込することで継続性を担保している。
• MAX_ITERATIONS (デフォルト 10) まで単純な for ループで回す。
• ブランチが切り替わると archive/ に前回の prd.json と progress.txt を退避する仕組みもある (ralph.sh:43-65)。

構造的な特徴

プロンプト (タスク定義) + 外部ファイル状態 + CLI をループ で叩くだけ

という極めてミニマルな設計。「LLM に会話履歴を持たせない」「状態は全部ファイル」という割り切りで、Agent の長時間自律動作を実現している。

This site is open source. Improve this page.