Wiggum Loopを使ってClaude Codeを効果的に活用する
著者紹介
こんにちは、Chris Fletcherです。Third Scopeでエンジニアをしています。
この記事では、私が実際に使っている「Wiggum Loop」というClaude Codeの活用テクニックを紹介します。プラグイン不要で自律的なタスク処理を実現する方法を、初心者の方でも再現できるように解説します。
この記事で学べること
この記事を読むことで、以下のことが学べます：
- Wiggum Loopの基本 - 名前の由来、仕組み、実行コマンド
-
CLAUDE.mdの書き方 - Claudeへの指示書を効果的に構成する方法 -
tasks.jsonの書き方 - タスク定義と依存関係の設計 - プロンプト設計のコツ - 自律モードで一貫した結果を得る技術
- なぜ効果的なのか - コンテキスト管理とタスク分解のメリット
- Bashコマンドの解説 - 各コンポーネントをステップバイステップで説明
- 注意すべきポイント - トークン消費、校正の必要性、セキュリティ
Wiggum Loopとは
名前の由来：Ralph Wiggum
Wiggum Loopの名前は、アメリカの人気アニメ「ザ・シンプソンズ」に登場するキャラクター、Ralph Wiggum（ラルフ・ウィガム）に由来しています。
Ralphは警察署長Clancy Wiggumの息子で、少し天然で予測不可能な発言をすることで知られています。特に有名なのが「I'm helping!（僕、手伝ってるよ！）」というセリフ。実際に役立っているかどうかは別として、一生懸命やっている姿が印象的なキャラクターです。
Wiggum Loopも同様に、Claude Codeに「I'm helping!」と言わせながら、夜通し自律的にタスクを処理させるテクニックです。朝起きたら、Claudeが一晩中頑張った成果物が待っています—もちろん、校正は必要ですが。
ループの仕組み
Wiggum Loopは、以下のシンプルな流れで動作します：
ポイントは、Claudeが1つのタスクを処理したら終了することです。Bashの無限ループが自動的にClaudeを再起動し、次のタスクを処理させます。これにより、コンテキストがリセットされ、Claudeは常に新鮮な状態で各タスクに取り組めます。
クイックスタート（5分で試す）
- プロジェクトルートに
CLAUDE.mdとtasks.jsonを作成（テンプレートは下記参照） - 以下を実行：
while true; do claude -p "$(cat CLAUDE.md)" --allowedTools "Read,Write,Edit,Glob,Grep"; done - Ctrl+Cで停止
詳細は以下のセクションで解説します。
このワンライナーで、ClaudeはCLAUDE.mdの指示に従い、tasks.jsonのタスクを処理し続けます。Ctrl+Cで停止するまでループが継続します。
必要なファイル
Wiggum Loopを動かすには、以下の2つのファイルが必要です：
| ファイル | 役割 |
|---|---|
CLAUDE.md |
Claudeへの指示書。ワークフロー、タスクスキーマ、ルールを定義 |
tasks.json |
タスク一覧。各タスクのID、ステータス、内容、完了条件を管理 |
これらのファイルをプロジェクトのルートディレクトリに配置するだけで準備完了です。
Wiggum Loopが効果的な理由
Wiggum Loopは単なる自動化スクリプトではありません。Claude Codeの特性を活かし、その能力を最大限に引き出すアプローチです。
コンテキスト過負荷を回避する
LLM（大規模言語モデル）には「コンテキストウィンドウ」という制限があります。これは、一度に処理できる情報量の上限です。
長時間のセッションでは、以下の問題が発生します：
| 問題 | 症状 |
|---|---|
| コンテキストの肥大化 | 会話履歴、読み込んだコード、出力が積み重なる |
| パフォーマンス低下 | 古い情報に引きずられて判断が鈍る |
| 一貫性の喪失 | 最初の指示を「忘れた」ような振る舞いをする |
| ダムゾーン | トークン限界に近づくとClaudeの能力が著しく低下する |
「ダムゾーン」 とは、コンテキストが限界に近づいたときにLLMのパフォーマンスが低下する現象です。この状態では、Claudeが指示を無視する、同じ内容を繰り返す、品質の低い出力を生成するといった問題が発生します。
Wiggum Loopは、各タスク完了後にClaudeを再起動してコンテキストをリセットすることで、この問題を回避します。
タスク分解によるトークン管理
大きなタスクを小さく分解することで、トークン消費が予測可能になります。
❌ 大きなタスク1つ：
"ユーザー管理システム全体を実装"
→ トークン消費：予測不可能
→ 中断時の進捗：不明確
✓ 小さなタスク7つ：
"Userモデル作成" → 約2,000トークン ✓
"ユーザー作成API" → 約3,000トークン ✓
"認証ミドルウェア" → 約2,500トークン ✓
→ 各タスクのコストが予測可能
→ 進捗が明確（3/7完了）
タスクが小さければ、Claudeは1つの作業に集中でき、問題発生時の影響も限定的です。タスク5でエラーが起きても、タスク1〜4は完了済み—修正すべき範囲が明確になります。
効果的なCLAUDE.mdの書き方
CLAUDE.mdはWiggum Loopの要となるファイルです。Claudeは起動時に必ずこのファイルを読み込むため、ここに書かれた指示が自律処理の品質を決定します。
CLAUDE.mdに含めるべき内容
1. プロジェクトの概要
プロジェクトの目的を明確に記述します。
# プロジェクト名
プロジェクトの目的と概要を1〜2文で説明。
Claudeは各タスク実行時にこの概要を参照し、一貫した方向性を保てます。
2. ワークフローの定義
Claudeがどの流れでタスクを処理するかを指示します。
## ワークフロー
1. `tasks.json`を読み込み、次の未完了タスクを見つける
2. タスクのステータスを「進行中」に設定する
3. タスクの説明に基づいて実行する
4. 完了条件を確認し、ステータスを「完了」に設定する
5. 未完了タスクがなくなるまで繰り返す
重要: 「1つのタスクを処理したら終了する」ことを明記してください。これがWiggum Loopの核心です。
3. タスクスキーマの定義
tasks.jsonのフォーマットを定義し、Claudeがタスクファイルを正しく読み書きできるようにします。
## タスクスキーマ
\`\`\`json
{
"id": 1,
"status": "未完了 | 進行中 | 完了",
"title": "短いタスクタイトル",
"description": "何をすべきかの詳細な説明",
"complete_condition": "完了とするための条件",
"depends_on": [1, 2]
}
\`\`\`
4. ルールと制約
Claudeに守ってほしいルールを明記します。
## ルール
- 一度に1つのタスクを処理して終了する
- タスク完了後は必ず`tasks.json`を更新する
- タスクが不明確な場合は「未完了」のままにし、ブロッカーを記録する
- 出力は簡潔だが情報量のあるものにする
ベストプラクティス
明確で具体的な言葉を使う
曖昧な表現を避け、具体的に指示します。
| 避けるべき表現 | 推奨する表現 |
|---|---|
| 「適切に処理する」 | 「エラーをログに記録し、ユーザーにエラーメッセージを表示する」 |
| 「必要に応じて」 | 「ファイルが存在しない場合は」 |
| 「できるだけ」 | 「最大5回までリトライする」 |
失敗時の対応を定義する
タスクが完了できない場合の対処法を指示します。
## ルール
- タスクが不明確な場合は「未完了」のままにし、`output`にブロッカーの説明を追加する
- 外部依存（API、データベースなど）が利用できない場合は、タスクをスキップして次へ進む
コンテキスト制限を意識させる
長時間のセッションでコンテキストが肥大化することを防ぎます。
- 100kトークンに近い場合は、タスクを「進行中」のままにして後で実装する
CLAUDE.mdのテンプレート
以下は、すぐに使えるテンプレートです：
# プロジェクト名
プロジェクトの概要をここに記述。
## ワークフロー
1. `tasks.json`を読み込み、次の未完了タスクを見つける（IDが最も小さいもので、`depends_on`の全タスクが完了しているもの）
2. タスクのステータスを「進行中」に設定する
3. タスクの説明に基づいて実行する
4. 完了条件を確認し、ステータスを「完了」に設定して`output`を追加する
5. 未完了タスクがなくなるまで繰り返す
## タスクスキーマ
\`\`\`json
{
"id": 1,
"status": "未完了 | 進行中 | 完了",
"title": "短いタスクタイトル",
"description": "何をすべきかの詳細な説明",
"complete_condition": "このタスクを完了とするための条件",
"depends_on": [1, 2]
}
\`\`\`
## ルール
- 一度に1つのタスクを処理して終了する
- タスク完了後は必ず`tasks.json`を更新する
- タスクが不明確な場合は「未完了」のままにし、`output`にブロッカーの説明を追加する
- 出力は簡潔だが情報量のあるものにする
- [プロジェクト固有のルールをここに追加]
このテンプレートをプロジェクトに合わせてカスタマイズしてください。
効果的なtasks.jsonの書き方
tasks.jsonはWiggum Loopのタスクキューです。Claudeはこのファイルから次のタスクを判断するため、明確なtasks.jsonを書くことが自律処理の成功を左右します。
タスクスキーマの詳細
各タスクは以下のフィールドで構成されます：
{
"id": 1,
"status": "未完了",
"title": "短いタスクタイトル",
"description": "何をすべきかの詳細な説明",
"complete_condition": "このタスクを完了とするための条件",
"depends_on": [1, 2],
"output": "タスク完了後の結果サマリー"
}
| フィールド | 必須 | 説明 |
|---|---|---|
id |
○ | タスクの一意識別子。処理順序の決定に使用 |
status |
○ | 「未完了」「進行中」「完了」のいずれか |
title |
○ | タスクの簡潔なタイトル（10文字以内推奨） |
description |
○ | タスクの詳細な説明 |
complete_condition |
○ | 完了とみなすための具体的な条件 |
depends_on |
- | 先に完了している必要があるタスクIDの配列 |
output |
- | タスク完了後にClaudeが追加する結果サマリー |
明確なタイトルの書き方
タイトルは動詞から始め、具体的に書きます。一目で「何をするタスクか」が分かることが重要です。
| 悪い例 | 良い例 |
|---|---|
| 「ログイン」 | 「ログイン画面を実装」 |
| 「バグ修正」 | 「認証エラー時のリダイレクトを修正」 |
| 「テスト」 | 「UserServiceのユニットテストを作成」 |
| 「リファクタ」 | 「APIクライアントをシングルトンに変更」 |
詳細な説明（description）の書き方
Claudeが追加の質問なしで実行できるレベルの詳細さが必要です。
含めるべき情報
- 何をするか - 具体的なアクション
- どこで - 対象ファイルやコンポーネント
- どのように - 技術的なアプローチや制約
- 参考情報 - 関連するコードやドキュメントへの参照
例
{
"description": "src/services/AuthService.tsにパスワードリセット機能を実装する。既存のsendEmail()メソッドを使用し、リセットトークンは24時間で期限切れにする。トークンはcrypto.randomUUID()で生成する。"
}
比較：
| 悪い例 | 良い例 |
|---|---|
| 「認証機能を追加」 | 「src/auth/にJWT認証ミドルウェアを実装。既存のUserモデルと連携し、トークンの有効期限は1時間とする」 |
| 「エラーハンドリング改善」 | 「src/api/client.tsの全APIコールにtry-catchを追加。ネットワークエラーはリトライ（最大3回）、4xx/5xxエラーはエラーモーダルを表示」 |
良い完了条件（complete_condition）の設定
完了条件は客観的に検証可能であることが必須です。「完了か否か」をClaudeが明確に判断できる条件を設定します。
効果的な完了条件のパターン
-
ファイルの存在確認
"complete_condition": "src/components/LoginForm.tsxが作成され、email/passwordフィールドとsubmitボタンが実装されている" -
機能の動作確認
"complete_condition": "npm run testが成功し、AuthService関連のテストがすべてパスする" -
コードの状態確認
"complete_condition": "全APIエンドポイントにレート制限が適用され、100リクエスト/分を超えると429エラーを返す"
避けるべき完了条件
| 悪い例 | 問題点 |
|---|---|
| 「実装が完了している」 | 何をもって「完了」とするか不明 |
| 「品質が良い」 | 主観的で検証不可能 |
| 「問題がない」 | 「問題」の定義が曖昧 |
タスクを分解するコツ
Wiggum Loopの効果を最大化するには、タスクの適切なサイズへの分解が重要です。
1タスク = 1コンテキストウィンドウ
1つのタスクは1回のClaudeセッションで完了できるサイズが目安です。大きすぎるとコンテキストを圧迫し、品質が低下します。
分解の例
分解前（大きすぎる）:
{
"title": "ユーザー管理機能を実装",
"description": "ユーザーの作成、読み取り、更新、削除、認証、権限管理をすべて実装する"
}
分解後（適切なサイズ）:
[
{ "id": 1, "title": "Userモデルを作成", "description": "..." },
{
"id": 2,
"title": "ユーザー作成APIを実装",
"depends_on": [1],
"description": "..."
},
{
"id": 3,
"title": "ユーザー取得APIを実装",
"depends_on": [1],
"description": "..."
},
{
"id": 4,
"title": "ユーザー更新APIを実装",
"depends_on": [1],
"description": "..."
},
{
"id": 5,
"title": "ユーザー削除APIを実装",
"depends_on": [1],
"description": "..."
},
{
"id": 6,
"title": "認証ミドルウェアを実装",
"depends_on": [2],
"description": "..."
},
{
"id": 7,
"title": "権限チェックを追加",
"depends_on": [6],
"description": "..."
}
]
depends_onを活用する
タスク間に依存関係がある場合は、depends_onで順序を制御します。Claudeは自動的に正しい順序でタスクを処理します。
{
"id": 3,
"title": "APIクライアントのテストを作成",
"depends_on": [1, 2],
"description": "タスク1（モデル作成）とタスク2（API実装）が完了後、APIクライアントの単体テストを作成する"
}
tasks.jsonのテンプレート
以下は、すぐに使えるテンプレートです：
{
"tasks": [
{
"id": 1,
"status": "未完了",
"title": "動詞から始まる簡潔なタイトル",
"description": "何を、どこで、どのように実装するかの詳細な説明。対象ファイルや技術的な制約も含める。",
"complete_condition": "客観的に検証可能な完了条件"
},
{
"id": 2,
"status": "未完了",
"title": "依存関係のあるタスク",
"description": "タスク1の完了を前提とした作業の説明。",
"complete_condition": "検証可能な完了条件",
"depends_on": [1]
}
]
}
よくある間違いと対処法
| 間違い | 対処法 |
|---|---|
| タスクが大きすぎる | 1セッションで完了できるサイズに分解する |
| 説明が曖昧 | 対象ファイル、技術アプローチ、制約を明記する |
| 完了条件がない | 検証可能な具体的な条件を追加する |
| 依存関係の漏れ | タスク間の前後関係をdepends_onで明示する |
| 重複するタスク | 類似タスクを統合するか、明確に区別する |
適切に構造化されたtasks.jsonがWiggum Loopの成功を決定します。最初は時間がかかりますが、慣れれば効果的なタスクリストを素早く作成できます。
効果的なプロンプトの書き方
CLAUDE.mdとtasks.jsonに加え、ループを起動するプロンプトもWiggum Loopの重要な要素です。毎回Claudeに渡されるため、その書き方が一貫した結果を左右します。
起動プロンプトの基本
Wiggum Loopを起動するBashコマンドでは、-pフラグでプロンプトを指定します：
claude -p "$(cat CLAUDE.md)" --allowedTools "Read,Write,Edit,Glob,Grep"
このコマンドではCLAUDE.mdの内容全体をプロンプトとして渡しています。CLAUDE.mdにワークフローの詳細が記述されているため、Claudeは起動するたびに完全な指示を受け取ります。
実際のユースケース
個人的には、難易度の高いタスクの複雑さそのものを楽しんでいるため、ただClaude Codeに任せてしまって、その過程を失いたくありません。仮に任せるとしても、tasks.json にタスク内容を説明する方が、実際に自分で作業するよりもかえって手間だと感じます。私にとって真価を発揮するのは、1つのプロンプトではトークン数が多くなりすぎてしまうような、長時間かかる単調または反復的な作業です。例えば、プロジェクトへのドキュメント追加、複数モジュールにまたがるテスト条件の作成、あるいはライブラリのアップグレードによる破壊的変更が影響していないかを、プロジェクト内の各ファイルを順に確認する作業などが挙げられます。
とはいえ、Ralph Wiggum Loopについて、他の人たちがよく使っている用途には次のようなものがあります。
| ユースケース | タスク例 | 効果 |
|---|---|---|
| テスト自動生成 | 各サービスのテストファイル作成 | 退屈な作業から解放 |
| ドキュメント作成 | API仕様書、README、チュートリアル | 一貫したスタイルで生成 |
| マイグレーション | 古いコードを新しいフレームワークに移行 | 大量のファイルを効率的に変換 |
| コードレビュー | 各ファイルのレビューと改善提案 | 見落としを防ぐ |
| 国際化対応 | 多言語リソースファイルの生成 | 翻訳の一貫性を確保 |
完全なコマンド
while true; do claude -p "$(cat CLAUDE.md)" --allowedTools "Read,Write,Edit,Glob,Grep"; done
このワンライナーを分解してみましょう。
コンポーネントごとの詳細解説
各パーツの説明
1. while true; do ... done
無限ループを作成する構文です。
while true; do
# ここに繰り返し実行したいコマンドを書く
done
| 要素 | 意味 |
|---|---|
while |
「〜の間、繰り返す」を意味するループ構文 |
true |
常に「真」を返すコマンド。条件が常に成立するので無限ループになる |
; |
コマンドの区切り（改行の代わり） |
do |
ループ内のコマンドブロックの開始 |
done |
ループ内のコマンドブロックの終了 |
2. claude
Claude Code CLIを呼び出すコマンドです。
3. -p "$(cat CLAUDE.md)"
プロンプトを指定するフラグとコマンド置換の組み合わせです。
claude -p "$(cat CLAUDE.md)"
| 要素 | 意味 |
|---|---|
-p |
プロンプト（--promptの短縮形） |
$(...)$ |
コマンド置換（括弧内のコマンドを実行） |
cat CLAUDE.md |
CLAUDE.mdファイルの内容を出力 |
コマンド置換とは？
$(...)$はBashのコマンド置換という機能で、括弧内のコマンドを実行し、その出力を文字列として埋め込みます。
# 例：現在の日付をファイル名に使う
touch "backup_$(date +%Y%m%d).txt"
# → backup_20240115.txt のようなファイルが作成される
この場合、cat CLAUDE.mdの出力（＝CLAUDE.mdの全内容）がプロンプトとしてClaudeに渡されます。つまり、ワークフローの指示をまるごとプロンプトとして渡しているのです。
なぜこのアプローチ？
CLAUDE.mdの内容を直接プロンプトに渡すことで：
- Claudeがワークフロー全体を確実に理解する
- 毎回同じ指示が渡されるため一貫性が保たれる
- CLAUDE.mdを編集するだけで動作を変更できる
4. --allowedTools "Read,Write,Edit,Glob,Grep"
使用可能なツールを制限するフラグです。
claude --allowedTools "Read,Write,Edit,Glob,Grep"
| ツール | 役割 |
|---|---|
Read |
ファイルを読み込む |
Write |
ファイルを新規作成・上書きする |
Edit |
ファイルの一部を編集する |
Glob |
パターンでファイルを検索する |
Grep |
ファイル内の文字列を検索する |
なぜツールを制限するのか？
--allowedToolsを使うと、Claudeが使用できるツールを明示的に指定できます。これにより：
- 安全性の向上: Bashコマンドの実行を禁止することで、予期しないシステム操作を防ぐ
- 確認プロンプトの回避: 許可されたツールは確認なしで実行される
- 予測可能な動作: ファイル操作のみに限定することで、挙動が予測しやすくなる
--dangerously-skip-permissionsと比較すると、--allowedToolsはより細かい制御が可能で、必要最小限の権限のみを付与できます。
ループの終了について
このコマンドには|| breakのようなエラー時の終了条件がありません。つまり、Ctrl+Cで手動停止するまで永遠にループし続けます。
| 終了方法 | 説明 |
|---|---|
| Ctrl+C | 手動でループを中断する |
| 全タスク完了後 | Claudeが起動するが処理するタスクがない状態 |
注意事項
Wiggum Loopは強力なツールですが、いくつかの注意点があります。トラブルを避けるためのポイントを解説します。
トークン使用量に注意
Wiggum Loopは大量のトークンを消費します。各タスクでClaudeを新規起動するため、システムプロンプトやCLAUDE.mdの読み込みが毎回発生するためです。
通常の対話セッション:
システムプロンプト読み込み: 1回
CLAUDE.md読み込み: 1回
タスク処理: N回
合計: 基本コスト + 処理コスト
Wiggum Loop（10タスク）:
システムプロンプト読み込み: 10回
CLAUDE.md読み込み: 10回
tasks.json読み込み: 10回
タスク処理: 10回
合計: (基本コスト × 10) + 処理コスト
推奨：トークンリセット前日に実行
多くのAPIプランでは、月次または週次でトークン使用量がリセットされます。リセット直前の余剰トークンを活用するのに最適です。
| タイミング | 推奨度 | 理由 |
|---|---|---|
| 月初・週初 | △ | 貴重なトークンを消費してしまう |
| 月中・週中 | ○ | 通常利用の範囲内で使用 |
| リセット前日 | ◎ | 余剰トークンを有効活用できる |
トークン消費を抑えるコツ
- タスクを適切なサイズに分割: 大きすぎるとコンテキストを圧迫し、小さすぎると起動オーバーヘッドが増加
- CLAUDE.mdを簡潔に: 毎回読み込まれるため、冗長な記述を避ける
- 不要なファイル読み込みを減らす: タスク説明に必要なファイルパスを明記し、探索を減らす
校正は必須
Wiggum Loopの出力は必ず人間が校正する必要があります。AIは優れた出力を生成しますが、以下のような問題が発生する可能性があります：
| 問題の種類 | 例 |
|---|---|
| ハルシネーション | 存在しないAPIやライブラリの使用 |
| コンテキストの誤解 | タスク説明の意図と異なる実装 |
| スタイルの不一致 | プロジェクトのコーディング規約に合わない |
| エッジケースの見落とし | 特殊なケースへの対応漏れ |
| 古い情報の使用 | 非推奨のメソッドや構文の使用 |
Claudeに校正を依頼することで、明らかなエラーは自動的に修正されます。ただし最終的な確認は人間が行うべきです。
その他の注意点
セキュリティに関する注意
--allowedToolsでファイル操作ツールを許可しているため、意図しないファイル変更が行われる可能性があります。ただし、Bashコマンドの実行は許可していないため、--dangerously-skip-permissionsよりは安全です。
- 重要なファイルはバックアップを取る: 特に本番環境のコードや設定ファイル
- Gitで変更を追跡: 何が変更されたか後から確認できるようにする
-
機密情報を含むファイルに注意:
.envファイルなどがタスク対象に含まれないようにする
無限ループの回避
タスク設計に問題があると、意図しない無限ループに陥る可能性があります：
| 原因 | 対策 |
|---|---|
| 完了条件が達成不可能 | 具体的で検証可能な条件を設定 |
| 循環依存 |
depends_onの設計を確認 |
| タスクが完了にならない | ステータス更新の指示を明確に |
最後に
Ralph Wiggumの「I'm helping!」のように、Wiggum Loopはあなたの開発作業を黙々と手助けします。完璧ではありませんが、適切なタスク設計と校正を組み合わせることで強力な自動化ツールになります。
まずは小さなプロジェクトから試してみてください。テスト自動生成、ドキュメント作成、リファクタリングなど、退屈な繰り返し作業から解放される体験をぜひ味わってください。
この記事が参考になれば幸いです。質問やフィードバックがあれば、コメントでお知らせください。