【保存版】RalphとClaude Codeで「完全自律開発環境」を構築する完全ガイド

「毎晩寝る前にRalphを起動して、朝起きたら新機能が3つ増えてる」

これが私の日常になりました。

前回の記事でRalphを紹介しましたが、今回は実際の環境構築から運用まで、すべてを公開します。

この記事を読み終わる頃には、あなたも「AIに開発を丸投げできる環境」が手に入ります。

🎯 この記事で構築する環境

┌─────────────────────────────────────────────────┐
│                    Ralph                         │
│  ┌─────────────────────────────────────────┐    │
│  │         Claude Code + Hooks              │    │
│  │  ┌─────────┐  ┌─────────┐  ┌─────────┐ │    │
│  │  │ Pre-run │→│ Execute │→│Post-run │ │    │
│  │  │ Hooks   │  │  Task   │  │ Hooks   │ │    │
│  │  └─────────┘  └─────────┘  └─────────┘ │    │
│  └─────────────────────────────────────────┘    │
│                      ↓                           │
│  ┌─────────────────────────────────────────┐    │
│  │    Git Auto-commit + Progress Track      │    │
│  └─────────────────────────────────────────┘    │
│                      ↓                           │
│              次のタスクへループ                   │
└─────────────────────────────────────────────────┘

完成形：

• PRDを書いて寝るだけ
• Claude Codeが自動で実装
• Hooksで品質を自動担保
• 朝起きたら全タスク完了

📦 Step 1: 必要なツールのインストール

Claude Codeのインストール

# npmでインストール
npm install -g @anthropic-ai/claude-code

# または直接インストール
curl -fsSL https://claude.ai/install.sh | sh

# バージョン確認
claude --version
# v2.1.0以上推奨

Ralphのインストール

# リポジトリをクローン
git clone https://github.com/snarktank/ralph.git
cd ralph

# PATHに追加
export PATH="$PATH:$(pwd)"

# または専用版
git clone https://github.com/frankbria/ralph-claude-code.git
cd ralph-claude-code
./install.sh

🔧 Step 2: CLAUDE.mdの最適化

プロジェクトルートにCLAUDE.mdを作成。これがClaude Codeの「脳」になります。

# CLAUDE.md

## プロジェクト概要
[プロジェクト名] - [1行説明]

## 技術スタック
- 言語: TypeScript 5.x
- フレームワーク: Next.js 15
- DB: PostgreSQL + Prisma
- テスト: Vitest

## 開発ルール

### 必須
- 全ての関数に型を付ける
- 新機能には必ずテストを書く
- コミットメッセージはConventional Commits

### 禁止
- any型の使用
- console.logの本番コード混入
- 未使用importの放置

## コマンド
- npm run dev - 開発サーバー
- npm run test - テスト実行
- npm run lint - Lint実行
- npm run typecheck - 型チェック

重要: CLAUDE.mdは定期的に更新しましょう。Ralphが学習した内容を蓄積することで、AIの精度が上がります。

🎛️ Step 3: Hooksの設定

Claude Codeのhooksで、品質を自動担保します。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Write|Edit",
        "command": "npm run lint:fix -- $CLAUDE_FILE_PATH 2>/dev/null || true"
      }
    ],
    "Stop": [
      {
        "command": "npm run typecheck 2>&1 | tail -20"
      },
      {
        "command": "npm run test 2>&1 | tail -30"
      }
    ]
  }
}

Hooksの解説

Hook	タイミング	用途
PreToolUse	ツール実行前	コマンドログ、バックアップ
PostToolUse	ツール実行後	自動フォーマット、Lint
Stop	応答完了時	テスト実行、型チェック
SessionEnd	セッション終了	ハンドオフ生成

📋 Step 4: PRDの作成

{
  "project": "my-awesome-app",
  "stories": [
    {
      "id": "auth-001",
      "title": "ユーザー登録APIの実装",
      "priority": 1,
      "status": "incomplete",
      "acceptance_criteria": [
        "POST /api/auth/register でユーザー登録できる",
        "パスワードはbcryptでハッシュ化",
        "テストカバレッジ80%以上"
      ]
    },
    {
      "id": "auth-002",
      "title": "ログインAPIの実装",
      "priority": 2,
      "status": "incomplete",
      "depends_on": ["auth-001"]
    }
  ]
}

PRD作成のコツ

✅ 良いタスク（原子的）
- "usersテーブルにemail_verified列を追加"
- "User.findByEmailメソッドを実装"

❌ 悪いタスク（大きすぎる）
- "認証システムを実装"
- "ユーザー管理機能を作る"

🚀 Step 5: Ralphの起動

# 基本起動
ralph

# 最大イテレーション数を指定（コスト制御）
ralph --max-iterations 20

# 特定のPRDファイルを指定
ralph --prd features/auth.json

⚠️ Step 6: セーフティ設定

{
  "exit_conditions": {
    "all_tasks_complete": true,
    "max_iterations": 50,
    "max_errors_consecutive": 3,
    "max_cost_usd": 100
  },
  "safety": {
    "require_tests_pass": true,
    "require_typecheck_pass": true,
    "no_force_push": true
  }
}

🔄 Step 7: CI/CD統合

GitHub Actionsで毎晩実行

name: Ralph Nightly Development

on:
  schedule:
    - cron: '0 0 * * *'

jobs:
  ralph:
    runs-on: ubuntu-latest
    timeout-minutes: 360

    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-node@v4

      - name: Run Ralph
        env:
          ANTHROPIC_API_KEY: ${{ secrets.ANTHROPIC_API_KEY }}
        run: ralph --max-iterations 30

      - name: Create Pull Request
        uses: peter-evans/create-pull-request@v5
        with:
          title: "[Ralph] Automated Development"
          branch: ralph/auto-dev-${{ github.run_number }}

💰 コスト試算

プロジェクト規模	イテレーション数	概算コスト/日
小規模（5タスク）	10-20	$5-15
中規模（15タスク）	30-50	$25-50
大規模（30タスク+）	50-100	$75-150

🎓 実践例：認証システムを一晩で構築

🕐 開始: 23:00
🕗 終了: 06:30 (7.5時間)

📊 統計:
- イテレーション: 24回
- コミット: 24個
- テスト: 47個（全パス）
- コスト: 約$35

✅ 完了タスク: 8/8 (100%)

寝てる間に認証システム完成。

🔮 まとめ

従来: 要件定義 → 設計 → 実装 → テスト → デプロイ
              ↑        ↑      ↑
            人間     人間    人間

これから: 要件定義 → 設計 → 実装 → テスト → デプロイ
              ↑        ↑      ↑
            人間    Ralph   Ralph

人間の仕事は「何を作るか決める」こと。作るのはAIに任せる時代。

---

🔗 リンク

• Ralph: https://github.com/snarktank/ralph
• Ralph for Claude Code: https://github.com/frankbria/ralph-claude-code
• Claude Code Hooks Guide: https://code.claude.com/docs/en/hooks-guide
• Claude Code Best Practices: https://www.anthropic.com/engineering/claude-code-best-practices

---

この環境、実際に構築してみた人いますか？どんなプロジェクトでRalphを活用していますか？コメントで教えてください！