概要#

機能要件さえ書けば無人で開発が進む究極のセットアップは、5 つの層を組み合わせれば 2026 年 5 月時点で実現可能 です。--permission-mode acceptEdits、.claude/settings.json の hooks、Subagents と Skills、.mcp.json での Playwright/GitHub MCP、そして Mac の launchd + caffeinate + tmux でラップする Ralph Loop──これだけで「PROMPT.md / fix_plan.md 駆動の自律実装ループ」が成立します。

Anthropic は 2025 年 7 月発表 / 8 月施行でユーザーの 5% 未満 しか引っかからない週次リミットを導入し、2025 年 9 月の Claude Code 2.0 で Checkpointing と VS Code 拡張(Plan Mode 自体は Shift+Tab で 2.0 以前から存在)、2025 年 10 月で Skills、2026 年 2 月で Agent Teams (実験的)、2026 年 3 月で --permission-mode auto、2026 年 4 月で Routines(クラウド定期実行) と Opus 4.7 を順次解放しました。Pro プランは Sonnet 4.6 中心(Opus 4.7 は Max プラン以上が前提)で「機能要件 1 行 → spec 生成 → 自律実装 → 自動検証 → PR 作成」までほぼ無人で回すことができ、リミット到達時は Claude が返すリセット時刻を bash でパースして caffeinate -i sleep で待機させればよいのです。

本稿では公式ドキュメント・GitHub の主要 OSS・Zenn / Qiita の実装事例を統合し、コピペで動くテンプレート一式を提示します。

flowchart TB
    User["👤 機能要件 1 行"] --> Loop["🔁 ralph-loop.sh<br/>(.ralph/PROMPT.md 駆動)"]

    subgraph "5 つの層"
        L5["⑤ launchd + caffeinate + tmux<br/>= 24 時間自走"]
        L4["④ Skills + Subagents + MCP<br/>= 分業と外部連携"]
        L3["③ CLAUDE.md + .ralph/fix_plan.md<br/>= 行動原則と作業キュー"]
        L2["② settings.json + Hooks<br/>(Stop で Ralph 継続強制)"]
        L1["① /model sonnet 固定<br/>= 安定稼働"]
    end

    Loop --> L5 --> L4 --> L3 --> L2 --> L1
    L1 --> PR["🐙 GitHub PR<br/>朝起きたら完成"]

    style User fill:#fff3e0
    style PR fill:#e8f5e9,stroke:#2e7d32
    style Loop fill:#e1f5ff,stroke:#0277bd

Pro プランの二層リミットと「Sonnet 固定」の鉄則#

Anthropic のサブスクリプションは 2025 年 8 月 28 日以降、5 時間セッション(rolling)と週次リミット の二層構造に変わりました。プラン別の上限は次の通りです。

Pro プランは事実上 Sonnet 専用です(2026 年 5 月時点)。Opus 4.7 を本格利用したいなら Max 5x 以上に上げる必要があります。リミット超過時は extra usage を有効にすれば、標準 API レートで継続課金できます。あるいは後述の claude-code-router で OpenRouter 等の API へ動的にスワップする運用もあります。

flowchart LR
    A["起動"] --> B{"/model 設定"}
    B -->|"Default のまま"| C["❌ 週次 Opus 上限で<br/>ブロック"]
    B -->|"/model sonnet 明示"| D["✅ 5h 上限のみ<br/>自動切替で継続"]
    style C fill:#ffebee,stroke:#c62828
    style D fill:#e8f5e9,stroke:#2e7d32

無人運用で最も詰まるのは(Max プラン以上の場合)「/model を Default (recommended) にしていると、週次の Opus 上限到達時に Sonnet へ自動フォールバックせずブロックされる」点です。/model sonnet を明示 すれば 5 時間制限は自動切替が効きます(Qiita @takezone)。Pro プランの場合は最初から Sonnet 固定なのでこの問題は生じませんが、習慣として /model sonnet を明示しておくと安全です。リミット到達時に Claude Code が出すメッセージは Claude usage limit reached. Your limit will reset at 3pm (America/New_York). または API 直エラーでは Claude AI usage limit reached|1749924000(Unix epoch)で、これを bash で正規表現パースします。

残量監視は ccusage(日本人開発者 ryoppippi 作、npx ccusage@latest blocks --live)が標準で、~/.claude/projects/*.jsonl を解析して 5 時間ブロックとモデル別コストを表示します。ccusage statusline を ~/.claude/settings.json の statusLine に登録すれば、プロンプト下部に常時残量が出ます。Python 製の claude-monitor(uv tool install claude-monitor、--plan pro --timezone Asia/Tokyo)は機械学習でリセット時刻を予測する TUI を提供し、tmux-claude-live で tmux ステータスバーへも出せます。日本語 note 記事(@euro0202)の指摘で重要なのは「消費の大半は output ではなく Cache Read」という点で、ccusage daily --breakdown で必ず内訳を確認すべきです。

自動化フラグの全貌と auto モードという新解#

Claude Code v2.1+ には自動化用フラグが 50 種類以上ありますが、無人運用で覚えるべきものは限られています。

権限制御の中心は --permission-mode で、値は default/acceptEdits/plan/auto/bypassPermissions の 5 つです。Shift+Tab で対話モード中の YOLO / auto-accept 切替に使います。

stateDiagram-v2
    [*] --> default
    default --> acceptEdits: Shift+Tab
    acceptEdits --> plan: Shift+Tab
    plan --> bypassPermissions: Shift+Tab
    bypassPermissions --> default: Shift+Tab
    plan --> auto: Shift+Tab
    auto --> default: Shift+Tab

    note right of acceptEdits
        🟢 無人運用の基本
    end note
    note right of bypassPermissions
        ⚠️ 危険:実機では避ける
    end note
    note right of auto
        🆕 2026/3 導入
        サーバ側で危険検知
    end note

--dangerously-skip-permissions は bypassPermissions の別名 で、全パーミッションプロンプトをスキップしますが .git/.claude/.vscode/.idea/.husky への書き込みだけは依然確認します(リポジトリ / フック破壊防止)。Anthropic 公式は「コンテナで使え、実機では使うな」と明記しており、2025 年 10 月 21 日に報告された Wolak 事件 (Issue #10077, Claude Code v2.0.22, WSL2 / Ubuntu) では rm -rf tests/ patches/ plan/ ~/ がチルダ展開後に実行され、ユーザのホームディレクトリを丸ごと削除しました(validation はチルダ展開「前」に行われていた)。eesel AI 調査では同フラグ利用者の 32% が意図しないファイル変更 を経験、9% がデータ損失 を経験しています。

2026 年 3 月 24 日導入の --permission-mode auto がこの代替として推奨されています(Sonnet 4.6 / Opus 4.6 以上必須、当初は Team プランのリサーチプレビュー)。サーバ側の transcript 分類器(fast filter → chain-of-thought)が危険操作を検知し、3 連続 / 累計 20 の拒否で人間にエスカレーションする仕組みです。auto 進入時は blanket shell access、python/node/ruby の wildcard、パッケージマネージャ run の always-allow ルールはドロップされる安全設計になっています。

settings.json は「許可リスト + deny + hooks」の三層で固める#

.claude/settings.json(プロジェクト)と ~/.claude/settings.json(ユーザー)と managed-settings.json(IT 管理)の 3 階層があり、配列フィールドは連結マージ、評価順は deny → ask → allow → defaultMode で最初にマッチしたルールが勝ちます。

flowchart TB
    Tool["Claude がツール実行を試みる"] --> L1{"① settings.json<br/>deny → ask → allow"}
    L1 -->|"deny ヒット"| Block1["🛑 ブロック"]
    L1 -->|"通過"| L2{"② PreToolUse Hook<br/>block-dangerous.sh"}
    L2 -->|"exit 2"| Block2["🛑 ブロック<br/>(deny バグの保険)"]
    L2 -->|"exit 0"| L3{"③ DevContainer<br/>iptables ファイアウォール"}
    L3 -->|"許可外通信"| Block3["🛑 ブロック"]
    L3 -->|"通過"| Exec["✅ 実行"]

    style Block1 fill:#ffebee,stroke:#c62828
    style Block2 fill:#ffebee,stroke:#c62828
    style Block3 fill:#ffebee,stroke:#c62828
    style Exec fill:#e8f5e9,stroke:#2e7d32

Bash ルールは glob、Read / Edit は gitignore 互換、WebFetch は domain: プレフィックスで指定します。ただし 2025〜2026 年の Issue #6699 / #18846 / #15921 / #13340 で allow/deny が一部効かない既知バグ が複数 open のため、重要な制約は必ず PreToolUse hook で重ねがけする のが業界 consensus です。

無人開発向けの推奨 settings.json テンプレートは以下の通りです。defaultMode を acceptEdits にし、開発で頻発する npm/pnpm/git/node/python/pytest/make 系を allow、git push だけ ask、機密ファイル(.env、.aws、.ssh、credentials*)と破壊コマンド(rm -rf:*、sudo:*、curl:*、wget:*)を deny します。

1
{
2
  "$schema": "https://json.schemastore.org/claude-code-settings.json",
3
  "env": {
4
    "CLAUDE_CODE_DISABLE_NONESSENTIAL_TRAFFIC": "1"
5
  },
6
  "permissions": {
7
    "defaultMode": "acceptEdits",
8
    "allow": [
9
      "Bash(npm:*)", "Bash(pnpm:*)", "Bash(yarn:*)",
10
      "Bash(git status)", "Bash(git diff *)", "Bash(git log *)",
11
      "Bash(git add *)", "Bash(git commit -m *)", "Bash(git checkout -b *)",
12
      "Bash(node *)", "Bash(python *)", "Bash(pytest *)", "Bash(make *)",
13
      "Bash(gh *)",
14
      "Read", "Edit", "Write", "Glob", "Grep",
15
      "WebFetch(domain:docs.anthropic.com)",
16
      "WebFetch(domain:github.com)",
17
      "mcp__playwright__*", "mcp__github__*", "mcp__context7__*"
18
    ],
19
    "ask": ["Bash(git push *)"],
20
    "deny": [
21
      "Read(./.env)", "Read(./.env.*)", "Read(**/.aws/**)",
22
      "Read(**/.ssh/**)", "Read(**/credentials*)",
23
      "Bash(rm -rf:*)", "Bash(sudo:*)", "Bash(curl:*)", "Bash(wget:*)"
24
    ]
25
  },
26
  "hooks": {
27
    "PreToolUse": [{
28
      "matcher": "Bash",
29
      "hooks": [{ "type": "command",
30
        "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/block-dangerous.sh" }]
31
    }],
32
    "PostToolUse": [{
33
      "matcher": "Edit|Write|MultiEdit",
34
      "hooks": [
35
        { "type": "command", "command": "npx prettier --write \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 2>/dev/null; true" },
36
        { "type": "command", "command": "npx eslint --fix \"$CLAUDE_TOOL_INPUT_FILE_PATH\" 2>/dev/null; true" }
37
      ]
38
    }],
39
    "Stop": [{
40
      "hooks": [{ "type": "command",
41
        "command": "afplay /System/Library/Sounds/Glass.aiff & osascript -e 'display notification \"Task done\" with title \"Claude Code\"'" }]
42
    }],
43
    "Notification": [{
44
      "matcher": "permission_prompt",
45
      "hooks": [{ "type": "command",
46
        "command": "afplay /System/Library/Sounds/Basso.aiff & osascript -e 'display notification \"Approval needed\" with title \"Claude Code\"'" }]
47
    }]
48
  }
49
}

Hook は 20 種類前後のライフサイクルイベント(2026 年 5 月時点で公式 21 イベント)を持ち、PreToolUse(ツール呼出前、deny 可)、PostToolUse / PostToolUseFailure(編集後フォーマット)、Stop / StopFailure(応答終了、exit 2 で継続強制可、Ralph Loop の心臓部)、SessionStart / SessionEnd、UserPromptSubmit、SubagentStart / SubagentStop、PreCompact、Notification、PermissionRequest などが主役になります。

sequenceDiagram
    participant U as User
    participant C as Claude
    participant H as Hooks
    participant T as Tool

    U->>C: プロンプト送信
    C->>H: UserPromptSubmit
    C->>C: 推論
    C->>H: PreToolUse (deny 判定可)
    alt deny ヒット
        H-->>C: exit 2 (ブロック)
    else 通過
        C->>T: ツール実行
        T-->>C: 結果
        C->>H: PostToolUse (フォーマット等)
    end
    C-->>U: 応答返却
    C->>H: Stop (テスト失敗なら exit 2 で継続強制)

exit 0 で成功・exit 2 でブロッキング / 継続強制 というセマンティクスが Unix 慣習と異なる点に注意してください。PreToolUse で permissionDecision: "deny" を返せば bypassPermissions モードでも止まるため、settings.json の deny バグを補完できます。Stop hook で「テストが通るまで継続」を強制する例は次の通りです。

1
#!/usr/bin/env bash
2
INPUT=$(cat); ACTIVE=$(echo "$INPUT" | jq -r '.stop_hook_active')
3
[ "$ACTIVE" = "true" ] && exit 0   # 無限ループ防止
4
if ! npm test > /tmp/test.log 2>&1; then
5
  echo "Tests failing. Fix and retry. See /tmp/test.log" >&2
6
  exit 2   # Claude に継続させる
7
fi

CLAUDE.md・Skills・Subagents で「動作優先・解決困難は後回し」を行動原則化#

CLAUDE.md は セッション開始時に自動でコンテキストへロードされる Markdown で、プロジェクトの「憲法」として働きます。

flowchart TB
    Start["セッション開始"] --> E["Enterprise managed"]
    E --> P["プロジェクトルート<br/>CLAUDE.md"]
    P --> S["サブディレクトリ<br/>(lazy)"]
    S --> H["~/.claude/CLAUDE.md"]
    H --> L["CLAUDE.local.md"]
    L --> Loaded["📚 重ねがけで全部ロード"]

    style Loaded fill:#e8f5e9,stroke:#2e7d32

優先順位は Enterprise → プロジェクトルート → サブディレクトリ(lazy)→ ~/.claude/CLAUDE.md → CLAUDE.local.md の順で重ねがけされます。HumanLayer 調査によれば LLM の指示遵守は 150〜200 個程度が限界 のため、本体は 200 行以下 にし、@docs/architecture.md のような import 構文で組織化するのがベストプラクティスです。コードスタイルは linter / formatter / hook に任せ、CLAUDE.md には「動作ルール」だけ書きましょう。

ユーザーの要件「動作優先・デザイン後回し」「解決困難は後回し」「自動コミット」を行動原則化した CLAUDE.md テンプレートは以下の通りです。

1
# プロジェクト: <NAME>
2

3
## アーキテクチャ概要
4
- 言語:TypeScript(厳格)/ Next.js 15 / Vitest + Playwright
5
- 詳細は @docs/architecture.md
6

7
## 開発フロー(必ず守る)
8
1. 変更前に `git switch -c feat/<topic>` でブランチ作成
9
2. **動作優先・デザイン後回し**:UI は最低限の見た目で先に動かす。
10
   美化や色調整は最後にまとめて行う
11
3. 機能を実装したら必ず:
12
   a. `npm run typecheck` を通す
13
   b. `npm test` を通す
14
   c. UI 機能なら verify-in-browser スキルで Playwright 検証
15
4. 全グリーンになったら **自動コミット**:
16
   `git add -p` で関連変更のみステージ → Conventional Commits でコミット
17
5. 1 機能完了ごとに push し、`gh pr create --fill` で PR 作成
18

19
## 解決困難な課題のハンドリング
20
- 同じテストが **3 回連続で失敗** したら、修正を諦めて以下を行う:
21
  1. `.ralph/fix_plan.md` に「⚠️ Blocked: <問題> / <ファイル:行> / <最後のエラー>」を追記
22
  2. 該当箇所に `// TODO(claude): blocked - see .ralph/fix_plan.md` コメントを残す
23
  3. **次のタスクに進む**(Ralph ループを止めない)
24
- 不確実な API 仕様は Context7 MCP で確認してから実装
25

26
## Retry Policy
27
- 問題発生時は自動で**最大 5 回**まで再試行
28
- 完了報告時に「failing tests / compile errors / unresolved errors」が
29
  残っていた場合は完了報告禁止
30

31
## 禁止事項
32
- `git add -A` 禁止(必ず `git add <file>` か `git add -p`)
33
- `.env*`、`secrets/`、`*.pem` のコミット禁止
34
- `any`、`as`、`@ts-ignore` の使用禁止
35
- 既存テストの削除禁止(壊れたら原因を直す)
36

37
## 関連ドキュメント
38
- @.ralph/PROMPT.md(同一プロンプト)
39
- @.ralph/fix_plan.md(現在の作業キュー)
40
- @docs/architecture.md

flowchart LR
    A["セッション開始"] --> B["📋 メタデータのみロード<br/>(name + description)"]
    B --> C{"トリガー?"}
    C -->|"description にマッチ"| D["📖 SKILL.md 本体ロード"]
    D --> E{"参照必要?"}
    E -->|"yes"| F["📚 references/ を Read"]
    E -->|"yes"| G["🔧 scripts/ を Bash 実行"]
    C -->|"非マッチ"| H["💤 ロードしない<br/>= コンテキスト節約"]

    style B fill:#e1f5ff
    style H fill:#eceff1
    style D fill:#e8f5e9

1
---
2
name: verify-in-browser
3
description: >
4
  実装した UI 機能を Playwright MCP で実際にブラウザで開き、
5
  期待通りに表示・動作するか確認する。フロントエンド機能の
6
  実装完了直後、PR 作成前に必ず使用。
7
allowed-tools: mcp__playwright__*, Read, Bash
8
---
9
## 手順
10
1. `npm run dev` をバックグラウンド起動(ポート確認)
11
2. `browser_navigate` で localhost:<port> を開く
12
3. `browser_snapshot` でアクセシビリティツリー取得
13
4. 実装した UI フロー(クリック・入力・遷移)を実行
14
5. 期待 DOM/テキストの存在を検証
15
6. 失敗したら debugger サブエージェントへ委譲
16
7. 成功なら "✅ Verified in browser: <flow>" を返す

flowchart TB
    Main["🧠 メインエージェント<br/>(タスク分配)"]

    subgraph "Subagents (独立コンテキスト)"
        S1["feature-implementer<br/>+ worktree 隔離"]
        S2["test-writer"]
        S3["code-reviewer"]
        S4["debugger"]
    end

    Main -->|並列起動| S1
    Main -->|並列起動| S2
    Main -->|並列起動| S3
    Main -->|並列起動| S4
    S1 -->|最終要約のみ| Main
    S2 -->|最終要約のみ| Main
    S3 -->|最終要約のみ| Main
    S4 -->|最終要約のみ| Main

    style Main fill:#fff3e0,stroke:#ef6c00
    style S1 fill:#e8f5e9
    style S2 fill:#e8f5e9
    style S3 fill:#e8f5e9
    style S4 fill:#e8f5e9

MCP サーバー 7 点セットで「ブラウザで動かして検証」まで自動化#

MCP(Model Context Protocol)は 2024 年 11 月発表のオープンプロトコルで、claude mcp add または .mcp.json で接続します。ルート直下の .mcp.json に置く こと(.claude/.mcp.json だと一部サーバが読み込まれない既知不具合あり、Issue #5037)。

flowchart LR
    Claude["🧠 Claude Code"]

    subgraph "MCP 7 点セット"
        M1["🐙 GitHub MCP<br/>issue/PR/コミット"]
        M2["📁 Filesystem MCP"]
        M3["🌐 Playwright MCP<br/>ブラウザ操作"]
        M4["🔍 Chrome DevTools MCP<br/>ネットワーク解析"]
        M5["📚 Context7 MCP<br/>最新ドキュメント"]
        M6["🧠 Sequential Thinking"]
        M7["💾 Memory MCP<br/>SQLite KG"]
    end

    Claude --> M1 & M2 & M3 & M4 & M5 & M6 & M7
    style Claude fill:#fff3e0,stroke:#ef6c00

無人開発に効く 7 点セットは GitHub MCP(公式の api.githubcopilot.com/mcp、issue/PR/コミット)、Filesystem MCP、Playwright MCP(Microsoft 公式、browser_navigate/browser_snapshot/browser_run_code)、Chrome DevTools MCP(Google 公式、ネットワーク解析)、Context7 MCP(Upstash、ライブラリ最新ドキュメント取得)、Sequential Thinking MCP、Memory MCP(SQLite Knowledge Graph)です。

⚠️ 注意:@modelcontextprotocol/server-github npm 版は 2025 年中に deprecated となっています(現行は github/github-mcp-server リポジトリの Docker / HTTP 版に統合)。本記事の .mcp.json は HTTP 版(api.githubcopilot.com/mcp)を採用しています。

1
{
2
  "mcpServers": {
3
    "github": {
4
      "type": "http",
5
      "url": "https://api.githubcopilot.com/mcp",
6
      "headers": { "Authorization": "Bearer ${GITHUB_PAT}" }
7
    },
8
    "playwright": { "command": "npx", "args": ["@playwright/mcp@latest", "--browser=chromium"] },
9
    "chrome-devtools": { "command": "npx", "args": ["chrome-devtools-mcp@latest"] },
10
    "context7": { "command": "npx", "args": ["-y", "@upstash/context7-mcp@latest"] },
11
    "sequential-thinking": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-sequential-thinking"] },
12
    "memory": { "command": "npx", "args": ["-y", "@modelcontextprotocol/server-memory", "--memory-path", "${HOME}/.claude-memory"] }
13
  }
14
}

ブラウザ動作確認のワークフローは次の連鎖になります。

flowchart LR
    A["1. 機能実装"] --> B["2. browser_navigate"]
    B --> C["3. browser_snapshot<br/>(a11y tree)"]
    C --> D["4. DOM/テキスト検証"]
    D -->|"OK"| E["7. PR 作成<br/>(GitHub MCP)"]
    D -->|"NG"| F["5. Chrome DevTools MCP<br/>で深掘り"]
    F --> G["6. 修正"] --> A

    style E fill:#e8f5e9,stroke:#2e7d32
    style F fill:#fff3e0

Microsoft の playwright-cli install --skills で Skill が自動配置され、--codegen オプションで TypeScript テストの自動生成までしてくれます。

Ralph Loop:2026 年に標準化された「同一プロンプト無限投入」パターン#

リミット到達の検知から再開までの実装は OSS が複数公開されています。terryso/claude-auto-resume(bash で Claude usage limit reached を grep → date -d で時刻パース → sleep → --continue)と cheapestinference/claude-auto-retry(npm、tmux capture-pane でポーリング、DST 対応)が代表格です。Anthropic 公式 issue(#36320, #35744, #18980)でも要望が多数集まっていますが、2026 年 5 月時点で公式機能としては未実装のため、自前で組みます。

「機能要件さえ書けば無人で動く」コア部分は、Geoffrey Huntley が提唱した Ralph Wiggum ループ(原典 ghuntley.com/ralph / everything is a ralph loop / note @jujunjun110 日本語解説)で実装します。思想は 「同じプロンプトを while ループで AI に投げ続け、状態は AI の記憶ではなくファイル(PROMPT.md / fix_plan.md / AGENTS.md)+ git に保持する」。各イテレーションは フレッシュコンテキスト で開始するので context rot(コンテキスト劣化)が起きず、根気だけで機能が完成します。

flowchart LR
    A["① 機械検証可能な完了条件<br/>(tests pass, lint clean, checklist [x])"] --> B["② ハードキャップ必須<br/>(--max-iterations + $ budget)"]
    B --> C["③ コンテキスト枯渇前に<br/>fresh agent へ rotate<br/>状態は AGENTS.md + git へ"]
    C --> D["④ SDD と分離<br/>(spec は人間 / 実装だけ Ralph)"]

    style A fill:#e8f5e9
    style B fill:#fff3e0
    style C fill:#e1f5ff
    style D fill:#f3e5f5

flowchart TB
    Start(["🌙 launchd 22:00 起動"]) --> Init["📂 .ralph/ 初期化<br/>PROMPT.md / fix_plan.md / AGENTS.md"]
    Init --> Loop{"fix_plan.md に<br/>[ ] あり?"}
    Loop -->|"なし"| Done(["🎉 完了通知<br/>(osascript)"])
    Loop -->|"あり"| Fresh["🆕 フレッシュ claude -p<br/>(同一 PROMPT.md 投入)"]
    Fresh --> Impl["実装 → テスト → コミット<br/>→ fix_plan.md 更新"]
    Impl --> Check{"Stop hook<br/>判定"}
    Check -->|"DONE 出力"| Loop
    Check -->|"usage limit"| Wait["⏰ リセット時刻まで<br/>caffeinate -i sleep"]
    Wait --> Loop
    Check -->|"3 回連続失敗"| Block["⚠️ fix_plan.md に<br/>Blocked 追記"]
    Block --> Loop
    Loop -->|"max-iter 到達"| Cap(["🛑 ハードキャップで停止"])

    style Start fill:#e1f5ff
    style Done fill:#e8f5e9
    style Wait fill:#fff3e0
    style Block fill:#ffebee
    style Cap fill:#ffebee

1
# プラグインインストール(2026/5 時点)
2
claude plugin install anthropic/ralph-loop

1
# 目的
2
@specs/feature/requirements.md を fix_plan.md のチェックリストに沿って実装する。
3

4
# あなたが毎イテレーション必ず行うこと
5
1. `git status` と `cat .ralph/fix_plan.md` で現在地を確認
6
2. `[ ]` の最上位項目を 1 つだけ選ぶ
7
3. TDD で実装(Red → Green → Refactor)
8
4. `pnpm test && pnpm lint && pnpm typecheck` がすべて緑になるまで修正
9
5. `git add -p && git commit -m "feat: ..."`(Conventional Commits)
10
6. `.ralph/fix_plan.md` で該当項目を `[x]` に更新して再 commit
11
7. **完了したら最終行に必ず `DONE` とだけ出力**
12
8. 5 回連続で同じテストが落ちたら、その項目に `⚠️ Blocked: <理由>` を追記し次へ
13

14
# 禁止
15
- `git add -A` / `--no-verify` / `any` / `as` / `@ts-ignore`
16
- 既存テストの削除(壊れたら原因を直す)
17
- specs/ 以下の改変(仕様変更が必要なら fix_plan.md に「要 spec 改訂」と書いて停止)

1
#!/usr/bin/env bash
2
# ralph-loop.sh - 公式 plugin に薄く被せるリミット耐性ラッパー
3
set -uo pipefail
4
REPO="$(pwd)"; LOG_DIR="${REPO}/.ralph/logs"; mkdir -p "$LOG_DIR"
5
ITER=0; MAX_ITER="${MAX_ITER:-30}"; BUDGET="${BUDGET_USD:-5.00}"
6

7
while (( ITER < MAX_ITER )); do
8
  ITER=$((ITER + 1)); TS=$(date +%Y%m%d_%H%M%S)
9
  LOG="$LOG_DIR/iter_${ITER}_${TS}.log"
10
  echo "===== Ralph Iteration ${ITER} =====" | tee "$LOG"
11

12
  # ① fix_plan.md に未完了 [ ] が残っているか
13
  if ! grep -qE '^\s*-\s*\[\s*\]' .ralph/fix_plan.md 2>/dev/null; then
14
    osascript -e 'display notification "Ralph: ALL DONE 🎉" with title "Claude"' 2>/dev/null
15
    break
16
  fi
17

18
  # ② フレッシュコンテキストで PROMPT.md 投入
19
  timeout 30m claude -p "$(cat .ralph/PROMPT.md)" \
20
    --permission-mode acceptEdits \
21
    --max-turns 80 \
22
    --output-format text 2>&1 | tee -a "$LOG"
23
  EC=${PIPESTATUS[0]}
24

25
  # ③ リミット検知 → リセット時刻まで caffeinate sleep
26
  if grep -qiE "usage limit reached" "$LOG"; then
27
    reset=$(grep -oE 'reset at [0-9]+(am|pm)' "$LOG" | tail -1 | awk '{print $3}')
28
    tz=$(grep -oE '\([A-Za-z_/]+\)' "$LOG" | tail -1 | tr -d '()')
29
    target=$(TZ="$tz" date -j -f '%I%p %Y-%m-%d' "$reset $(date +%Y-%m-%d)" +%s 2>/dev/null \
30
             || date -d "today $reset" +%s 2>/dev/null \
31
             || echo $(( $(date +%s) + 1800 )))
32
    now=$(date +%s); (( target <= now )) && target=$((target + 86400))
33
    sleep_for=$(( target - now + 60 ))
34
    osascript -e "display notification \"Ralph waiting $((sleep_for/60))m\" with title \"Claude\"" 2>/dev/null
35
    caffeinate -i sleep "$sleep_for"
36
    continue
37
  fi
38

39
  # ④ DONE が最終行になければ次イテレーションで再投入(これが Ralph の本質)
40
  if ! tail -3 "$LOG" | grep -q "^DONE$"; then
41
    sleep $(( 30 * (1 + ITER % 5) ))    # 軽いバックオフのみ
42
  fi
43
done

1
{
2
  "hooks": {
3
    "Stop": [{
4
      "hooks": [{
5
        "type": "command",
6
        "command": "$CLAUDE_PROJECT_DIR/.claude/hooks/ralph-continue.sh"
7
      }]
8
    }]
9
  }
10
}

1
#!/usr/bin/env bash
2
# .claude/hooks/ralph-continue.sh - Stop 時に DONE が無ければ exit 2 で継続強制
3
INPUT=$(cat)
4
[ "$(echo "$INPUT" | jq -r '.stop_hook_active')" = "true" ] && exit 0
5
LAST=$(echo "$INPUT" | jq -r '.transcript_path' | xargs tail -n 5)
6
if echo "$LAST" | grep -q "^DONE$"; then exit 0; fi
7
echo "fix_plan.md にまだ [ ] が残っています。次のタスクを継続してください。" >&2
8
exit 2   # Claude に継続を強制

Mac 固有の自動化 + caffeinate + 4 つの壁突破#

caffeinate -i でアイドルスリープ防止、-d でディスプレイ、-s で AC 電源時の system sleep、-t 28800 で時間限定が可能です。実は Claude Code 自身が内部で caffeinate -i -t 300 を 5 分ごとに spawn する ため対話実行中はそもそもスリープしませんが(Issue #21432)、バックエンド / cron / launchd から spawn する場合は明示的に caffeinate でラップする のが安全です。ラップトップを閉じた瞬間も caffeinate は効きません。

flowchart LR
    A["💤 Mac スリープ中"] --> B{{"launchd<br/>22:00 起床"}}
    B --> C["caffeinate -i<br/>(スリープ抑止)"]
    C --> D["claude-loop.sh"]
    D --> E["朝起きたら<br/>PR が積み上がっている"]

    style A fill:#eceff1
    style B fill:#e1f5ff,stroke:#0277bd
    style C fill:#fff3e0
    style E fill:#e8f5e9,stroke:#2e7d32

GMO ペパボの記事(zenn.dev/pepabo)が指摘する cron 自走で毎回ハマる 4 つの壁 を整理しました。

flowchart LR
    Start["🚀 launchd 起動"] --> W1{"壁 ①<br/>Bypass<br/>permissions"}
    W1 -->|"OK"| W2{"壁 ②<br/>Trust this<br/>folder"}
    W2 -->|"OK"| W3{"壁 ③<br/>MCP<br/>allow/deny"}
    W3 -->|"OK"| W4{"壁 ④<br/>ファイル<br/>除外リスト"}
    W4 -->|"OK"| Run["✅ 自走開始"]

    W1 -.解決策.-> S1["acceptEdits 設定"]
    W2 -.解決策.-> S2["事前に対話モードで<br/>一度開く"]
    W3 -.解決策.-> S3["事前 allowlist"]
    W4 -.解決策.-> S4[".env 等の deny を<br/>settings.json に"]

    style Run fill:#e8f5e9,stroke:#2e7d32

これらを抜ければ launchd で完全無人化できます。~/Library/LaunchAgents/com.user.claude-loop.plist を以下で配置します。

1
<?xml version="1.0" encoding="UTF-8"?>
2
<plist version="1.0"><dict>
3
  <key>Label</key><string>com.user.claude-loop</string>
4
  <key>ProgramArguments</key><array>
5
    <string>/usr/bin/caffeinate</string><string>-i</string>
6
    <string>/bin/bash</string><string>-lc</string>
7
    <string>cd /Users/me/projects/myapp && /usr/local/bin/claude-loop.sh</string>
8
  </array>
9
  <key>StartCalendarInterval</key>
10
    <dict><key>Hour</key><integer>22</integer><key>Minute</key><integer>0</integer></dict>
11
  <key>EnvironmentVariables</key>
12
    <dict><key>PATH</key><string>/opt/homebrew/bin:/usr/local/bin:/usr/bin:/bin</string></dict>
13
  <key>StandardOutPath</key><string>/Users/me/.claude-loop/stdout.log</string>
14
  <key>StandardErrorPath</key><string>/Users/me/.claude-loop/stderr.log</string>
15
  <key>WorkingDirectory</key><string>/Users/me/projects/myapp</string>
16
</dict></plist>

launchctl load ~/Library/LaunchAgents/com.user.claude-loop.plist でロードし、launchctl start com.user.claude-loop で即時実行できます。cron は寝てる Mac では発火しない ため pmset repeat wake MTWRF 02:55:00 の事前起床と組み合わせるか、launchd 一択 です。完了通知は osascript -e 'display notification "Iteration 5 完了" with title "Claude Loop" sound name "Glass"' でロックスクリーンに送れます。fswatch -o src/ tests/ | xargs -n1 -I{} claude -p "..." のファイル監視併用も有効で、保存と同時にテスト / 修復ループが走ります。

究極のセットアップ:4 フェーズで「機能要件 1 行 → PR 作成」#

ディレクトリ構成は次のように .claude/ と .ralph/ 配下に 全制御ファイルを集約 します。

1
~/projects/myapp/
2
├── CLAUDE.md                     # 200 行以下、行動原則
3
├── AGENTS.md                     # マルチ AI 共通(Ralph 状態の正典)
4
├── .mcp.json                     # 7 点セット MCP
5
├── .ralph/
6
│   ├── PROMPT.md                 # 同一プロンプト(毎イテレーション再投入)
7
│   ├── fix_plan.md               # 作業キュー([ ]/[x]/⚠️ Blocked)
8
│   └── logs/                     # 各イテレーションのログ
9
├── .claude/
10
│   ├── settings.json             # 権限・hooks(Stop で ralph-continue.sh)
11
│   ├── skills/
12
│   │   ├── commit/SKILL.md       # Conventional Commits 自動生成
13
│   │   ├── run-tests-and-fix/SKILL.md
14
│   │   └── verify-in-browser/SKILL.md  # Playwright 検証
15
│   ├── agents/
16
│   │   ├── feature-implementer.md  # model: sonnet, isolation: worktree
17
│   │   ├── test-writer.md
18
│   │   ├── code-reviewer.md
19
│   │   └── debugger.md
20
│   └── hooks/
21
│       ├── block-dangerous.sh
22
│       ├── format-and-lint.sh
23
│       └── ralph-continue.sh     # Stop hook で DONE 判定 → 継続強制
24
└── specs/<feature>/{requirements,design,tasks}.md   # cc-sdd の SDD

運用は次の 4 フェーズで進めます。

flowchart TB
    P1["📋 Phase 1: 計画(人間関与)<br/>plan モード + /kiro-discovery<br/>requirements → design → tasks"]
    P2["🔁 Phase 2: 自律実装ループ<br/>/ralph-loop で TDD 実装<br/>Stop hook でテスト自動実行"]
    P3["🌐 Phase 3: 自動 QA<br/>qa subagent + Playwright MCP<br/>各種 viewport で実フロー検証"]
    P4["🐙 Phase 4: 出荷<br/>gh pr create<br/>Actions で自動レビュー"]

    P1 --> P2 --> P3 --> P4

    style P1 fill:#fff3e0,stroke:#ef6c00
    style P2 fill:#e1f5ff,stroke:#0277bd
    style P3 fill:#f3e5f5,stroke:#7b1fa2
    style P4 fill:#e8f5e9,stroke:#2e7d32

Phase 1(計画、人間関与) で claude --permission-mode plan を起動し cc-sdd プラグイン(gotalab/cc-sdd)で機能要件を requirements.md(EARS 記法)→ design.md → tasks.md に分解、人間が approve します。この成果物を .ralph/fix_plan.md の機械検証可能なチェックリストへ変換するのが Phase 1 の最終ステップ です。Phase 2(Ralph 自律実装ループ) で claude -w feature-x から ./ralph-loop.sh を起動、Sonnet 4.6 が フレッシュコンテキストで .ralph/PROMPT.md を毎回再投入、各タスクを TDD で実装、Stop hook (ralph-continue.sh) で DONE が出ていなければ自動継続。Phase 3(自動 QA) では qa subagent が Playwright MCP で 375×667 モバイル含む各種 viewport で実フロー検証、失敗時はデバッガに自動委譲します。Phase 4(出荷) で gh pr create し、GitHub Actions の anthropics/claude-code-action@v1 が PR レビューを自動コメントします。

「機能要件 1 行 → 無人で機能完成」の最小コマンドは次の通りです(Ralph パターン版)。

1
# 1. 仕様を spec に展開(対話、5 分)
2
echo "ユーザーが商品にレビューを書いて星評価できる機能" > /tmp/req.txt
3
claude --permission-mode plan \
4
  -p "$(cat /tmp/req.txt) を cc-sdd で specs/review/{requirements,design,tasks}.md に展開し、
5
       .ralph/fix_plan.md にテストで検証可能なチェックリストを作成してください"
6

7
# 2. Ralph ループを夜間に走らせる
8
caffeinate -i tmux new -d -s ralph \
9
  "MAX_ITER=30 BUDGET_USD=5.00 ./ralph-loop.sh"
10

11
# 3. 朝、PR を確認
12
gh pr list --author @me

Pro プランで 24 時間化する経済的レシピ は、ローカル launchd で毎晩 22:00 に ralph-loop.sh を起動し(/loop はセッション終了で消えるため永続用途には不適)、ccusage statusline で残量常時表示、リミット到達時は bash でリセット時刻まで caffeinate -i sleep するというものです。Routines(クラウド)は Pro で 5 回 / 日と少ないため、@claude の PR コメント自動レビュー専用に使い、メイン開発はローカル Ralph で回しましょう。Pro 上限が頻繁にぶつかるようなら Max 5x($100)か musistudio/claude-code-router で Sonnet を OpenRouter 経由 API(例: anthropic/claude-sonnet-4.6)にスワップ する運用が現実解です。

隔離戦略 + Worktree + Checkpointing が三種の神器#

--dangerously-skip-permissions を実機で直に使うのはプロンプトインジェクションと破壊コマンドのリスクが高いです。

flowchart TB
    Risk["⚠️ プロンプトインジェクション<br/>+ 破壊コマンド"]

    subgraph "🛡️ 三種の神器"
        A["🐳 DevContainer<br/>iptables ホワイトリスト"]
        B["🌳 Worktree 隔離<br/>.claude/worktrees/"]
        C["⏪ Checkpointing<br/>Esc Esc / /rewind"]
    end

    Risk -.防ぐ.-> A
    Risk -.防ぐ.-> B
    Risk -.防ぐ.-> C

    A --> Safe["✅ 無人実行可能"]
    B --> Safe
    C --> Safe

    style Risk fill:#ffebee,stroke:#c62828
    style Safe fill:#e8f5e9,stroke:#2e7d32

Anthropic 公式 DevContainer(anthropics/claude-code/.devcontainer)は 3 ファイル構成(devcontainer.json/Dockerfile/init-firewall.sh)で、iptables + ipset によるホワイトリスト型ファイアウォールを node ユーザー sudoers で設定し、api.anthropic.com/registry.npmjs.org/api.github.com 等のみ outbound 許可、それ以外 deny します。Anthropic は「コンテナのセキュリティ強化により安全に無人実行できる」と明記していますが、「Claude Code credential が漏洩しうるので 信頼できるリポジトリでのみ使え」と注意しています。スタンドアロンで動かすなら docker run --cap-drop=ALL --cap-add=NET_ADMIN --cap-add=NET_RAW -v $(pwd):/workspaces/project claude-code-sandbox が定石で、~/.ssh ~/.aws は絶対にマウントしないでください。

--worktree (-w) ネイティブサポートは v2.1.49–50 で CLI 統合され、<repo>/.claude/worktrees/<name>/ に隔離 worktree を作成します。Subagent frontmatter の isolation: worktree で各サブエージェントを独立 worktree に閉じ込められ、並列実行時の同一ファイル編集競合を物理的に防げます。Boris Cherny 自身は 同時 10〜15 体 の Claude を回しています。Checkpointing(Claude Code 2.0)は各編集前に自動スナップショットし Esc Esc または /rewind で巻き戻せますが、Claude のファイル編集ツールが行った変更のみ が対象で手動編集や bash 経由の変更は含まれません──必ず Git と併用してください。--max-turns 50 と --max-budget-usd 5.00 で物理的上限も設定し、PreToolUse hook で rm -rf|sudo|:(){:|:&};:|dd if=|mkfs を正規表現で deny するスクリプトを必ず登録するようにしましょう。

結論 でも実装可能、ボトルネックは「人間の要件記述」だけ#

2026 年 5 月時点で「機能要件さえ書けば Claude Code が無人で開発を進める」セットアップは Pro プランでも完全に実装可能です。鍵は次の 5 つです。

mindmap
  root((Pro で<br/>24h 自走))
    1. 三層防衛
      acceptEdits モード
      厳密な deny
      PreToolUse Hook
    2. 行動原則
      動作優先
      解決困難は次へ
      fix_plan.md 記録
    3. 分業
      Skills
      Subagents
      MCP 7 点
    4. 自己 QA
      Playwright MCP
      自動ブラウザ検証
    5. Ralph Loop で 24h 自走
      公式 ralph-loop plugin
      Stop hook 継続強制
      caffeinate + launchd

• (1) acceptEdits モード + 厳密な deny + PreToolUse hook の三層防衛 で危険操作を物理ブロックする
• (2) CLAUDE.md に「動作優先・解決困難は .ralph/fix_plan.md に⚠️で記録して次へ」を行動原則化 する
• (3) Skills と Subagents で実装 / テスト / レビュー / QA を分業 する
• (4) Playwright MCP で自己 QA まで閉じさせる
• (5) Ralph Loop(公式 ralph-loop plugin or snarktank/ralph)+ caffeinate + リミット時刻パース + launchd で 24 時間自走させる

Ralph Wiggum ループ思想で「フレッシュコンテキスト × ファイルと git による状態永続化」を徹底し、機械検証可能な完了条件 + ハードキャップ(--max-iterations/--max-budget-usd) を必ず設定すれば、context rot で破綻せず根気で機能を完成させられます。

留意点として、Claude Code は週次で急速にアップデートしており、auto モード(2026/3)、Agent Teams(2026/2 実験的)、Routines(2026/4)、Opus 4.7(2026/4/16 GA)、OpenAI Codex CLI への Ralph ビルトイン化(2026/4/30)など 2026 年に入って自律性の階梯が一段上がりました。Pro での Routines 5 回 / 日制限は重要トリガー(PR review など)に絞り、メインのループはローカル launchd + Ralph で安く長く回すのが経済合理的です。

最後に注意したいのは Pro は事実上 Sonnet 専用(Opus 4.7 は Max 以上)である点、/model sonnet 明示で安定稼働 する点、Cache Read がトークン消費の主犯 である点で、ccusage daily --breakdown で月初に内訳を確認する習慣をつけたいところです。残るボトルネックは Claude ではなく 人間が書く機能要件の質(と .ralph/fix_plan.md に落とす機械検証可能なチェックリストの設計)だけで、それを SDD の requirements.md に EARS 記法で書ければ──あとは寝ている間に PR が積み上がっています。