Claude Code 開発ワークフロー実践ガイド｜4フェーズ方式からチーム並列運用まで

Claude Codeはチャットボットではありません。ファイルを読み、コマンドを実行し、コードを書き換え、テストを走らせるAIエージェントです。開発者が「何を作りたいか」を伝えると、Claude Codeが「どう作るか」を自律的に判断して実行します。

しかし、この自律性を活かすにはワークフローの設計が必要です。闇雲に指示を出すとコンテキストウィンドウが溢れ、精度が急落します。

この記事では、実際のプロジェクトで成果を出すためのワークフロー設計を、導入直後の段階からチームでの並列開発まで段階的に整理しています。

コンテキストウィンドウがワークフローの全てを左右する

Claude Codeを使ううえで最も重要な制約はコンテキストウィンドウです。会話のやり取り、読み込んだファイルの内容、コマンドの実行結果がすべてこのウィンドウに蓄積されます。

公称では200kトークンの容量がありますが、MCPサーバーやプラグインの設定情報だけで相当量を消費するため、実質的に利用できる容量は70k〜100k程度まで縮小するケースもあります。

コンテキストが埋まるほどLLMの精度は下がります。初期の指示を「忘れる」、同じミスを繰り返す、見当違いの修正をする——こうした問題の大半はコンテキストの肥大化が原因です。

そのため、ワークフローの設計方針は「コンテキストをいかに効率よく使うか」に集約されます。

基本ワークフロー：Explore → Plan → Code → Commit

Claude Code公式が推奨する4フェーズ方式は、コンテキストの無駄遣いを防ぎつつ高品質な成果を得るための基本形です。

Phase 1：Explore（探索）

Plan Modeに切り替え、コードベースの構造を読み取り専用で調査します。この段階ではファイルの読み込みと質問への回答だけが行われ、コードは変更されません。

# Plan Modeへの切り替え
Shift+Tab を2回押す（Normal → Auto-Accept → Plan Mode）

# または起動時にPlan Modeを指定
claude --permission-mode plan

> src/authディレクトリを読んで、セッション管理とログインの仕組みを把握して
> 環境変数でシークレットをどう管理しているかも確認して

Phase 2：Plan（計画）

同じPlan Mode内で、実装計画の策定を依頼します。Ctrl+Gを押すとテキストエディタで計画を直接編集できるため、要件の追加や方針の修正をその場で反映できます。

> Google OAuthを追加したい。変更が必要なファイルとセッションフローの計画を作って

Phase 3：Code（実装）

Normal Modeに戻し、計画に基づいて実装を進めます。検証基準を指示に含めることで、Claude Codeが自分自身の出力を検証できるようになります。

> 計画に従ってOAuthフローを実装して。コールバックハンドラのテストを書き、
> テストスイートを実行して失敗があれば修正して

検証基準を含める指示は、Claude Code公式のベストプラクティスで最もレバレッジの高い手法として位置づけられています。

Phase 4：Commit（記録）

実装が完了したら、コミットとPR作成まで一貫して依頼できます。

> 変更内容をわかりやすいメッセージでコミットして、PRを作成して

/commit-push-prスキルを使えば、コミット・プッシュ・PR作成を一括で実行できます。

フェーズをスキップしてよいケース

4フェーズ方式はあくまで基本形であり、全てのタスクに適用する必要はありません。

• タイポ修正や1行の変更：直接依頼して問題ありません
• 変更がdiff一文で説明できるタスク：計画フェーズは不要です
• 探索的なタスク：あえて曖昧な指示で反応を確認し、方向を修正していく方が効率的な場合もあります

CLAUDE.mdでワークフローの土台を作る

CLAUDE.mdは全セッションの冒頭で自動的に読み込まれるファイルです。ここにプロジェクト固有のルールを書いておくことで、毎回の説明を省略できます。

/initで雛形を自動生成する

claude
> /init

/initコマンドはコードベースを解析し、ビルドシステム、テストフレームワーク、コーディングパターンを検出してCLAUDE.mdの雛形を生成します。ゼロから書くよりも、この雛形をベースに調整する方が効率的です。

含めるべき6つのセクション

米国の開発者コミュニティで共有されているCLAUDE.mdの設計パターンをもとに、効果的な構成を整理します。

ファイル分割で遅延読み込みを実現する

CLAUDE.mdが長くなると、重要なルールが埋もれてClaudeに無視される問題が起きます。解決策は、詳細を別ファイルに分割し、必要なときだけ参照させることです。

# CLAUDE.md（メインファイル、簡潔に保つ）

## コードスタイル
C#ファイルを編集するときは @docs/csharp-standards.md を参照すること。
フロントエンドのファイルを編集するときは @docs/web-standards.md を参照すること。

## ビルドコマンド
- テスト: `cargo test`
- 型チェック: `npm run typecheck`

この方法により、メインのCLAUDE.mdはコンテキストを最小限に抑えつつ、必要な場面で詳細なルールが自動的に読み込まれます。

配置場所による使い分け

定期的な棚卸しが不可欠

CLAUDE.mdは「生きたドキュメント」として扱い、定期的に見直す必要があります。

• 各行に対して「これを削除するとClaudeがミスするか？」を問う。Noなら削除します
• Claudeがルールに従わない場合、ファイルが長すぎる可能性があります。ルールが埋もれている状態です
• Claudeが既に正しく行っていることは書かない。言語のデフォルト慣例などは不要です

プロンプト設計で成果の質が変わる

Claude Codeは意図を推測する能力が高いですが、精度の高い出力を得るにはプロンプトの設計が鍵になります。

精度を上げる4つの指示テクニック

1. スコープを絞る

# 曖昧な指示
> auth.pyのテストを追加して

# 具体的な指示
> auth.pyのテストを書いて。ユーザーがログアウト状態のエッジケースをカバーすること。
> モックは使わないで

2. 一次情報を参照させる

# Claudeが推測に頼る
> config_parser.pyのAPIはなぜこんな設計なの？

# git履歴やソースコードに直接アクセスさせる
> config_parser.pyのgit logを確認して、引数の変更履歴を時系列で整理して

3. プロジェクト内の実装例を示す

> @src/components/DashboardCard.tsx のレイアウト構成を確認して。
> 同じ構成で新しいAnalyticsCardコンポーネントを作成して

4. テスト条件を明示する

> sanitizeInput関数を実装して。
> テストケース: "<script>" → "&lt;script&gt;", "normal" → "normal", "" → ""
> 実装後にテストを実行して全件パスすること

@メンションでファイルを直接参照する

プロンプト中で@を使うと、ファイルやディレクトリの内容を直接コンテキストに含められます。

> @src/utils/auth.js のロジックを説明して
> @src/components のディレクトリ構造を見せて

画像もドラッグ＆ドロップやCtrl+Vでコンテキストに追加できます。UIのスクリーンショットやエラー画面を貼り付けて指示するのは非常に効果的です。

コンテキスト管理の実戦テクニック

/compactと/clearの判断基準

目安：同じ問題で2回以上修正を重ねている場合、コンテキストが失敗したアプローチで汚染されています。/clearで一度リセットし、学んだことを反映した新しいプロンプトで再開する方が、そのまま修正を重ねるよりも早く正確な結果に辿り着けます。

サブエージェントへの調査委譲

コードベースの調査をメインセッションで行うと、読み込んだファイルの内容がコンテキストを大量に消費します。サブエージェントは別のコンテキストウィンドウで動作するため、メインのコンテキストを汚さずに調査結果だけを受け取れます。

> サブエージェントを使って、認証システムのトークンリフレッシュの仕組みと、
> 既存のOAuthユーティリティがあるか調査して

実装後の検証にも活用できます。

> サブエージェントを使って、このコードのエッジケースをレビューして

/rewindによるチェックポイント復帰

Claude Codeは変更のたびにチェックポイントを自動作成しています。Escキーを2回押すか/rewindを実行すると、任意の時点に会話やコードの状態を巻き戻せます。

この仕組みがあるため、リスクのある変更でも気軽に試せます。うまくいかなければrewindして別のアプローチを取るだけです。チェックポイントはセッションをまたいで保持されます。

モデル選択とコスト最適化

Claude Codeでは3つのモデルを状況に応じて切り替えられます。/modelコマンドで変更可能です。

モデル特性の比較

opusplanエイリアスでコスパを最大化する

Anthropic社内でも使われている設定パターンとして、計画フェーズはOpusで深く考えさせ、実装フェーズはSonnetに切り替えるという運用があります。シェルエイリアスとして設定しておくと便利です。

# ~/.bashrc や ~/.zshrc に追加
alias opusplan='claude --model opus --permission-mode plan'

計画策定にはOpusの高い推論能力を使い、計画が固まったら/modelでSonnetに切り替えて実装を進めます。

Effort Level（Opus 4.6向け）

Opus 4.6ではAdaptive Reasoning機能により、Effort Levelに応じて思考の深さが動的に調整されます。

環境変数CLAUDE_CODE_EFFORT_LEVELまたはセッション中の/modelコマンドで切り替えます。maxはOpus 4.6でのみ利用可能で、拡張思考が有効になるため応答に時間がかかりますが、複雑な問題に対する精度が大幅に向上します。

API費用を抑える5つのポイント

1. プロンプトの精度を上げる — 曖昧な指示は修正ループを生み、トークン消費が倍増します。前述の4原則を意識するだけでやり直し回数が減ります
2. コンテキストの肥大化を防ぐ — /compactで同タスク内の履歴を圧縮し、タスク切り替え時は/clearでリセットします。CLAUDE.mdも500行以下に収めるとセッション開始時の読み込みコストが下がります
3. opusplanエイリアスでモデルを使い分ける — 設計にはOpusの推論力、実装にはSonnetの速度を使い分けるだけで、同じ品質のままコストを削減できます
4. Effort Levelをタスク難易度に合わせる — 型定義の追加やリネーム程度のタスクにhighは過剰です。lowやmediumに下げるとトークン消費が抑えられます
5. 使わないMCPサーバーを切断する — MCPサーバーは接続しているだけでコンテキストを消費します。プロジェクトで使わないサーバーはclaude mcp removeで外しておきます

並列開発で生産性を数倍にする

1つのClaude Codeセッションで得たスキルを、複数のセッションに展開することで生産性は倍増します。

Git Worktreeで独立したセッションを同時実行する

複数タスクを並行して進める場合、各セッションが別々の作業ディレクトリを持つ必要があります。Git Worktreeはリポジトリの履歴を共有しつつ、独立したブランチとファイルを持つ作業ディレクトリを作成します。

# 名前付きworktreeでClaude Codeを起動
claude --worktree feature-auth

# 別のターミナルで別のworktreeを起動
claude --worktree bugfix-123

Worktreeは<リポジトリ>/.claude/worktrees/<名前>/に作成され、ブランチ名はworktree-<名前>になります。セッション終了時に変更がなければ自動的にクリーンアップされます。

.claude/worktrees/を.gitignoreに追加しておくと、メインリポジトリにworktreeの内容が表示されなくなります。

Writer/Reviewerパターン

2つのセッションを使い、実装と品質チェックを分離するパターンです。新しいコンテキストでレビューすることで、実装時のバイアスに影響されない客観的な評価が得られます。

# セッションA（実装）
> APIエンドポイントにレート制限を実装して

# セッションB（レビュー）
> @src/middleware/rateLimiter.ts のレート制限実装をレビューして。
> エッジケース、レース条件、既存ミドルウェアとの一貫性を確認して

さらに進んだパターンとして、セッションBでセキュリティレビュー、セッションCでパフォーマンスレビューを同時に走らせる並列レビューも有効です。

fan-outパターンで大規模タスクを分散処理する

数百ファイルに及ぶマイグレーションなどでは、ファイルごとにClaude Codeを並列起動して処理を分散できます。

# 1. 対象ファイルのリストを生成
claude -p "Python 2からPython 3に移行が必要なファイルを全てリストして" > files.txt

# 2. 各ファイルに対して並列実行
for file in $(cat files.txt); do
  claude -p "$file をPython 3に移行して。結果をOKまたはFAILで返して" \
    --allowedTools "Edit,Bash(git commit *)" &
done

最初の2〜3ファイルで動作を確認し、プロンプトを調整してから残りを実行するのが安全です。

Agent Teamsで複数セッションを組織的に連携させる

Agent Teamsは複数のClaude Codeセッションが共有タスクリストとメッセージングで連携する仕組みです。チームリードが全体を統括し、各セッションが専門タスクを担当します。

Git Worktreeの手動管理に比べて、タスクの割り当て・進捗管理・セッション間の情報共有が自動化される点が特長です。

自動化レイヤーを構築する：Hooks・Skills・Subagents

ワークフローが定まったら、繰り返し行う操作を自動化して人手を減らします。

Hooksで「例外なく実行される」品質ゲートを設定する

HooksはClaude Codeのライフサイクルの特定タイミングで自動実行されるスクリプトです。CLAUDE.mdの指示が「助言」であるのに対し、Hooksは確実に実行される点が異なります。

代表的なイベントと活用例を整理します。

Hooksの設定はClaude Codeに依頼することもできます。

> ファイル編集後にeslintを自動実行するhookを書いて
> migrationsフォルダへの書き込みをブロックするhookを書いて

/hooksコマンドで対話的に設定するか、.claude/settings.jsonを直接編集します。

Skillsでチーム標準のワークフローを定義する

Skillsは.claude/skills/ディレクトリにSKILL.mdとして配置する、再利用可能な手順書です。

<!-- .claude/skills/fix-issue/SKILL.md -->
---
name: fix-issue
description: GitHub Issueの修正ワークフロー
disable-model-invocation: true
---
GitHub Issue $ARGUMENTS を分析して修正する。

1. `gh issue view`でIssueの詳細を取得
2. 問題を理解し、関連ファイルを検索
3. 修正を実装
4. テストを書いて実行
5. lint・型チェックを通す
6. コミットメッセージを作成してPRを作成

/fix-issue 1234で呼び出せます。disable-model-invocation: trueを設定すると、手動でのみ起動される（Claudeが自動判断では呼び出さない）ようになります。

チーム全員がgitにコミットされたSkillsを使うことで、経験の浅いメンバーでも標準化されたワークフローで作業できます。

Subagentsで専門タスクを独立して実行する

Subagentsは独自のコンテキストとツール権限を持つ専門エージェントです。.claude/agents/に定義します。

<!-- .claude/agents/security-reviewer.md -->
---
name: security-reviewer
description: セキュリティ脆弱性のレビュー
tools: Read, Grep, Glob, Bash
model: opus
---
シニアセキュリティエンジニアとしてコードをレビューする。
- インジェクション脆弱性（SQL, XSS, コマンドインジェクション）
- 認証・認可の欠陥
- コード内のシークレットや認証情報
- 安全でないデータ処理

具体的な行番号と修正案を提示すること。

Subagentのworktree隔離も可能です。isolation: worktreeをfrontmatterに追加すると、Subagentが独立したworktreeで動作し、メインのコードベースに影響を与えません。

使い分けの判断基準

毎回同じ結果が欲しい → Hooks（確実に実行される）
手順をテンプレート化したい → Skills（呼び出し時に読み込み）
別コンテキストで調査・検証したい → Subagents（独立実行）
外部ツールと連携したい → MCP（次セクション参照）

MCP連携で外部ツールと統合する

MCP（Model Context Protocol）は、Claude Codeと外部ツールをつなぐプロトコルです。claude mcp addコマンドでサーバーを追加します。

実践的なMCP構成例

MCPサーバーは同時に5〜6個程度に抑えるのが推奨です。接続するだけでコンテキストを消費するため、使わないサーバーは無効化しておきます。

MCPのルールをCLAUDE.mdに記載する

MCPサーバーの使用方法をCLAUDE.mdに明記しておくと、Claudeが適切なタイミングで正しいツールを選択できます。

## MCP利用ルール
- UIコンポーネントを追加するときはFigma MCPでデザインを確認すること
- Issueの詳細はLinear MCPで取得し、ghコマンドは使わないこと
- データベーススキーマの変更前にSupabase MCPで現在のスキーマを確認すること

避けるべき5つの失敗パターン

Claude Code公式のベストプラクティスで言及されている典型的なアンチパターンと、その回避策を整理します。

1. Kitchen Sinkセッション

1つのセッションで認証の修正→UIの調整→APIの追加と無関係なタスクを次々に依頼してしまうパターンです。コンテキストが無関係な情報で埋まり、各タスクの精度が低下します。

回避策：タスク間で/clearを実行してコンテキストをリセットします。

2. 修正の繰り返し

Claudeの出力が間違い→修正を指示→まだ間違い→また修正……と繰り返すパターンです。失敗したアプローチがコンテキストに蓄積し、正解に辿り着きにくくなります。

回避策：2回修正しても改善しない場合、/clearして最初のプロンプトを改善した状態で再開します。

3. 肥大化したCLAUDE.md

ルールが多すぎて重要な指示が埋もれ、Claudeが半分を無視するパターンです。

回避策：各行に対して「これがないとClaudeがミスするか？」を問い、Noなら削除します。確実に実行されるべきルールはHooksに移行します。

4. 検証なき信頼

Claudeの出力がもっともらしいため精査せず受け入れ、エッジケース未処理のコードがリリースされるパターンです。

回避策：テストスイート、リンター、スクリーンショット比較など、Claudeが自分自身の出力を検証できる手段を必ず指示に含めます。

5. 際限のない探索

「調査して」と曖昧に依頼し、Claudeが数百のファイルを読み込んでコンテキストを使い尽くすパターンです。

回避策：調査のスコープを絞るか、サブエージェントに委譲してメインのコンテキストを保護します。

ワークフロー習熟度別ロードマップ

段階的にワークフローを拡充していくための目安です。

Level 1：基本操作を身につける

• /initでCLAUDE.mdを生成し、プロジェクト固有のルールを追記
• Explore → Plan → Code → Commitの4フェーズを1タスクで実践
• /compactと/clearを意識的に使い分ける
• プロンプトにテスト条件を明示する習慣をつける
• /renameでセッションに名前をつけ、--continueで再開する

Level 2：効率を高める

• opusplanエイリアスを設定し、モデルを使い分ける
• Effort Levelをタスク難易度に応じて切り替える
• Skillsを2〜3個作成してチーム内で共有する
• Hooksでフォーマッタの自動実行やデスクトップ通知を設定する
• MCPサーバーを1〜2個接続して外部ツール連携を試す
• CLAUDE.mdを定期的に棚卸しする

Level 3：並列・自動化で拡張する

• Git Worktreeで2つ以上のセッションを並列実行する
• Writer/Reviewerパターンで品質を向上させる
• Subagentsを定義してセキュリティレビューやテスト検証を自動化する
• claude -pをCI/CDパイプラインやpre-commitフックに組み込む
• fan-outパターンで大規模なファイル変更を分散処理する
• Agent Teamsで複数セッションの連携を自動化する

セッションの中断・再開を効率化する

長期のプロジェクトでは、セッションの管理手法が作業効率に直結します。

セッション再開の3つの方法

セッション命名のコツ

「explain this function」のような初期プロンプトがセッション名になると後から探しにくくなります。/renameで意味のある名前をつけておきます。

> /rename oauth-migration
> /rename memory-leak-debug
> /rename api-v2-endpoint

セッションピッカー（/resumeで起動）では、/で検索、Bで現在のブランチのセッションのみ表示、Pでプレビューが可能です。

まとめ：ワークフロー設計の3原則

Claude Codeの開発ワークフローは、次の3原則に集約されます。

1. コンテキストを守る 全ての設計判断は「コンテキストウィンドウを効率的に使えるか」で評価します。/clear・/compact・サブエージェントへの委譲は、そのための具体的な手段です。

2. 検証可能な指示を出す テスト、リンター、スクリーンショット比較など、Claudeが自分の出力をチェックできる条件を指示に含めます。テスト条件のない指示は、品質の保証がない実装を生みます。

3. 段階的に自動化する まず4フェーズ方式で基本を固め、繰り返す操作をHooks・Skills・Subagentsで自動化し、並列実行で生産性を拡張します。最初から全てを自動化する必要はありません。

これらの原則を基盤として、プロジェクトの規模やチームの成熟度に応じたワークフローを構築していけます。

参考資料:

• Claude Code公式ドキュメント - Common Workflows
• Claude Code公式ドキュメント - Best Practices