第2章：公式推奨ワークフロー「Explore → Plan → Code → Commit」
はじめに：なぜワークフローが重要なのか
Claude Codeを使い始めたばかりの人がよくやってしまう失敗があります。それは「とりあえず作りたいものを伝えて、あとはClaudeに任せる」というアプローチです。
たしかに、Claudeは驚くほど賢いAIです。簡単なスクリプトや小さなコンポーネントなら、一言伝えるだけで完璧なコードを生成してくれることもあるでしょう。しかし、ある程度の規模のアプリケーションを作ろうとすると、この「丸投げアプローチ」は必ず破綻します。
なぜでしょうか？
理由はシンプルです。AIは文脈がなければ、あなたの意図を正確に理解できないからです。あなたの頭の中にある「こういう感じのアプリ」というイメージは、言語化しない限りClaudeには伝わりません。そして、曖昧な指示からClaudeが推測した実装は、往々にしてあなたの期待とは異なるものになります。
Anthropicはこの問題を深く理解しており、2024年から2025年にかけて、Claude Codeを使った開発の「正しい進め方」を体系化しました。それが**「Explore → Plan → Code → Commit」**という4段階ワークフローです。
このワークフローの本質は、コードを書く前に十分な準備をするということ。当たり前のように聞こえるかもしれませんが、AIコーディングの文脈では、この「準備」の意味が従来の開発とは少し異なります。
第1段階：Explore（探索）
探索フェーズの目的
Exploreフェーズの目的は、Claudeにプロジェクトの全体像を把握させることです。
人間の開発者が新しいプロジェクトに参加したとき、最初に何をするでしょうか？おそらく、既存のコードを読み、ドキュメントを確認し、アーキテクチャを理解しようとするはずです。Claudeも同じです。いきなりコードを書かせるのではなく、まず「このプロジェクトはどういう構造になっているのか」「どんな技術スタックを使っているのか」「既存のコードはどんなスタイルで書かれているのか」を理解させる必要があります。
実践：探索フェーズの進め方
探索フェーズでは、以下のような情報をClaudeに読み込ませます：
あなた：このプロジェクトの構造を理解してほしい。
まず、以下のファイルを読んでくれ：
- README.md
- package.json
- src/の構造
- 主要なコンポーネントファイル
まだコードは書かないで。理解したことを説明してくれ。
ここで最も重要なのは「まだコードは書かないで」という一言です。この指示がないと、Claudeは親切心から「では、こういう実装はいかがでしょうか」とコードを提案し始めてしまいます。探索フェーズでは、あくまで情報収集に徹してもらう必要があります。
画像やURLの活用
Claude Codeは画像を理解できます。これは探索フェーズで非常に強力な武器になります。
たとえば、UIのモックアップやワイヤーフレームがあれば、それをClaudeに見せることで、言葉で説明するよりもはるかに正確に意図を伝えられます：
あなた：このFigmaのスクリーンショットを見てほしい。
[画像を添付]
このデザインを実装したい。
まず、この画面に必要なコンポーネントを洗い出してくれ。
まだコードは書かないで。
同様に、参考にしたいWebサイトのURLを共有することもできます。Claudeはそのサイトを分析し、どのような技術や設計パターンが使われているかを教えてくれます。
サブエージェントの活用
複雑なプロジェクトでは、探索すべき領域が多岐にわたります。そんなときはサブエージェントを活用しましょう。
サブエージェントとは、メインのClaudeから独立したタスクを委譲できる機能です。たとえば：
あなた：このプロジェクトについて調べたい。以下の3つを並行して調査してくれ：
1. フロントエンドの技術スタックと設計パターン
2. バックエンドAPIの構造とエンドポイント一覧
3. データベーススキーマと主要なリレーション
サブエージェントは、詳細の検証や特定の質問の調査を委譲するのに適しています。メインのコンテキストを汚さずに、深い調査ができるのがメリットです。
第2段階：Plan（計画）
計画フェーズの目的
探索フェーズでプロジェクトの全体像を把握したら、次は具体的な実装計画を立てる段階です。
ここで重要なのは、計画を人間がレビューできる形で残すことです。Claudeの頭の中だけで計画を立てさせると、後から「なぜこういう設計にしたのか」を確認できなくなります。また、計画段階で方向性の間違いに気づければ、実装後に大幅な手戻りが発生するのを防げます。
Extended Thinkingの活用
Claude CodeにはExtended Thinkingという機能があります。これは、Claudeにより深く考えさせるための仕組みです。
計画フェーズでは、この機能を積極的に活用しましょう。Extended Thinkingを発動させるキーワードは以下の通りです：
| キーワード | 思考レベル | 使いどころ |
|---|---|---|
think |
標準 | 一般的な設計検討 |
think hard |
深い | 複雑な設計判断 |
think harder |
より深い | トレードオフの検討 |
ultrathink |
最大 | アーキテクチャ全体の設計 |
実際の使い方はこんな感じです：
あなた：ユーザー認証システムを実装したい。
think hardして、以下の点を検討してくれ：
1. セッション管理の方式（JWT vs セッションCookie）
2. OAuth連携の設計
3. セキュリティ上の考慮点
4. 段階的な実装計画
検討結果はMarkdownファイルにまとめてくれ。
まだ実装コードは書かないで。
計画の記録方法
計画は必ずMarkdownファイルまたはGitHub Issueに記録します。私のおすすめは、プロジェクトルートにdocs/plans/ディレクトリを作り、そこに計画ファイルを保存する方法です：
docs/plans/
├── 2025-01-15-auth-system.md
├── 2025-01-16-user-profile.md
└── 2025-01-17-notification.md
日付をファイル名に含めることで、後から「いつ、どんな計画を立てたか」を追跡できます。
計画ファイルの構成例：
# 認証システム実装計画
## 背景
現在のアプリにはユーザー認証機能がない。
Google OAuthでのログインを実装し、ユーザー固有のデータを保存できるようにしたい。
## 技術選定
### 採用：JWT + HTTPOnly Cookie
理由：
- SPAとの相性が良い
- サーバーサイドでのセッション管理が不要
- XSS攻撃への耐性
### 不採用：セッションベース認証
理由：
- Redis等のセッションストアが必要
- スケーラビリティの課題
## 実装ステップ
1. [ ] Google OAuth設定
2. [ ] JWTトークン生成・検証ロジック
3. [ ] 認証ミドルウェア
4. [ ] ログイン/ログアウトAPI
5. [ ] フロントエンドの認証フロー
## セキュリティチェックリスト
- [ ] CSRF対策
- [ ] トークンのローテーション
- [ ] Refresh Tokenの実装
計画のレビューと修正
計画ファイルが完成したら、必ず人間の目でレビューします。ここがvibe codingの肝です。
Claudeが提案した計画が、あなたの意図と合っているか確認してください。合っていなければ、この段階で修正します。実装が始まってから方向転換するよりも、計画段階で修正する方がはるかに低コストです。
あなた：計画を見た。いくつか修正したい：
1. 最初のバージョンではOAuthは不要。
メールアドレス+パスワードの認証だけでいい。
2. JWTではなく、セッションCookieを使いたい。
理由は既存のインフラにRedisがあるから。
この方針で計画を修正してくれ。
第3段階：Code（実装）
実装フェーズの目的
計画が固まったら、いよいよコードを書く段階です。
とはいえ、ここでも「丸投げ」は禁物です。実装フェーズでも、あなたはパイロットとしてClaudeをナビゲートし続ける必要があります。
計画に基づいた実装指示
実装を始めるときは、計画ファイルを参照しながら指示を出します：
あなた：docs/plans/2025-01-15-auth-system.mdの計画に従って、
ステップ1「Google OAuth設定」を実装してくれ。
実装が終わったら、動作確認の方法も教えてほしい。
ポイントは、一度にすべてを実装させないことです。計画を小さなステップに分割し、一つずつ実装させていきます。これにより：
- 各ステップで動作確認ができる
- 問題が起きても影響範囲が限定される
- 進捗が見えやすい
実装中の軌道修正
Claudeが実装を進めている最中に、「あれ、これは違うな」と思ったら、Escapeキーで中断できます。
[Claudeが実装中...]
あなた：[Escapeキーを押す]
あなた：ちょっと待って。今の実装だと、既存のUserモデルと
整合性が取れない。先にUserモデルを確認してから
続けてくれ。
この「中断して軌道修正」ができることが、vibe codingの大きな強みです。従来の開発では、コードを書いてしまった後で方向転換するのは大きなコストでした。しかしClaude Codeなら、途中で止めて方向を変えるのは簡単です。
妥当性の検証
実装が完了したら、そのコードが計画通りになっているか検証します。Claudeに自己検証させるのも有効です：
あなた：今の実装が計画通りになっているか、自分で検証してくれ。
特に以下の点をチェック：
1. セキュリティチェックリストの項目は満たしているか
2. エラーハンドリングは適切か
3. テストは書いてあるか
第4段階：Commit（確定）
コミットフェーズの目的
実装が完了し、動作確認も済んだら、変更を確定します。
ここでAnthropicが推奨しているのが**「1 Todo = 1 Commit」**の原則です。つまり、計画の各ステップを1つのコミットとして記録するということです。
しかし、Commitフェーズの役割は「コードを保存する」だけではありません。今回の実装で得た学びを、未来の自分とClaudeのために記録するという、より重要な役割があります。
良いコミットの作り方
あなた：今の実装をコミットしたい。
コミットメッセージは以下の形式で：
feat: Google OAuth認証の実装
- OAuth設定ファイルの追加
- 認証コールバックの実装
- ユーザー作成/更新ロジック
関連: docs/plans/2025-01-15-auth-system.md
コミットメッセージには、何をしたかだけでなく、なぜそうしたか（計画ファイルへの参照）を含めるのがベストプラクティスです。後から見返したときに、そのコミットの文脈が理解できます。
🔑 最重要：LLMの方向性ミスと指摘事項を記録する
ここで、vibe codingにおける最も重要なプラクティスをお伝えします。
各ToDoに対して、Claudeが犯した大局的な方向性ミスや、あなたが行った指摘事項は、必ずドキュメントに残してください。
なぜこれが重要なのでしょうか？
Claudeは非常に優秀ですが、同じタイプのミスを繰り返す傾向があります。たとえば：
- 「このプロジェクトではORMを使っているのに、生SQLを書こうとした」
- 「認証が必要なAPIなのに、認証チェックを忘れた」
- 「既存のユーティリティ関数があるのに、似た機能を新たに実装しようとした」
- 「エラーハンドリングの方針と異なる実装をした」
これらのミスを記録せずに放置すると、次のセッションでまた同じミスが発生します。Claudeはセッション間で記憶を持たないため、あなたが記録しない限り、学習は蓄積されません。
学習ログ（Lessons Learned）の記録方法
私がお勧めするのは、docs/LESSONS.md というファイルを作成し、各ToDoで発生した問題と解決策を記録する方法です。
docs/LESSONS.md の例：
# 学習ログ（Lessons Learned）
このファイルには、開発中にClaudeが犯した方向性ミスと、
その修正内容を記録しています。
Claudeは新しいセッションでこのファイルを参照し、
同じミスを繰り返さないようにしてください。
---
## 認証・認可
### 2025-01-15: APIエンドポイントの認証チェック漏れ
**状況**: `/api/users/[id]` エンドポイントを実装した際、
認証チェックなしで実装しようとした。
**問題**: 未認証ユーザーが他人のユーザー情報にアクセスできてしまう。
**正しい実装**:
- すべての `/api/` エンドポイントには `authMiddleware` を適用する
- ユーザー固有のリソースには、所有者チェックも追加する
**参照**: `src/middleware/auth.ts`
---
## データベース操作
### 2025-01-16: 生SQLの使用
**状況**: 複雑なクエリを実装する際、Prismaではなく生SQLを書こうとした。
**問題**:
- 型安全性が失われる
- SQLインジェクションのリスク
- プロジェクトの一貫性が崩れる
**正しい実装**:
- 複雑なクエリでもPrismaの `$queryRaw` は使わない
- Prismaのリレーションクエリで対応できないか検討する
- どうしても必要な場合は、チームに相談してから実装
---
## コンポーネント設計
### 2025-01-16: 既存ユーティリティの重複実装
**状況**: 日付フォーマット関数を新たに作ろうとした。
**問題**: `src/utils/date.ts` に同様の関数が既に存在していた。
**教訓**: 新しいユーティリティ関数を作る前に、
必ず `src/utils/` ディレクトリを確認すること。
**既存のユーティリティ一覧**:
- `src/utils/date.ts` - 日付操作
- `src/utils/string.ts` - 文字列操作
- `src/utils/validation.ts` - バリデーション
CLAUDE.mdからの参照
LESSONS.mdを作成したら、CLAUDE.mdから参照するようにします：
## Critical Context
実装を始める前に、必ず以下を確認すること：
- `docs/LESSONS.md` - 過去の方向性ミスと教訓
これにより、Claudeは新しいセッションを開始するたびに、過去の学びを参照できます。
計画ファイルへの追記
また、各機能の計画ファイル（docs/plans/）にも、その機能特有の学びを追記することをお勧めします：
docs/plans/2025-01-15-auth-system.md（追記部分）：
## 実装時の学び
### 発生した問題と解決策
1. **JWT秘密鍵の管理**
- 問題: Claudeが秘密鍵をコードにハードコードしようとした
- 解決: 環境変数 `JWT_SECRET` から読み込むよう修正
- 教訓: シークレットは必ず環境変数で管理
2. **トークン保存場所**
- 問題: LocalStorageに保存しようとした
- 解決: HTTPOnly Cookieに変更
- 教訓: XSS対策として、トークンはJSからアクセスできない場所に
3. **リフレッシュトークンの実装漏れ**
- 問題: アクセストークンのみの実装で完了しようとした
- 解決: リフレッシュトークンのフローを追加
- 教訓: 認証設計は最初から完全な形で実装する
### 次回同様の機能を実装する際の注意点
- 認証フローは `docs/SECURITY.md` を必ず参照
- 既存の `authMiddleware` を再利用する
- テストは正常系・異常系両方書く
なぜこれが「Commit」フェーズに含まれるのか
「学習の記録」をCommitフェーズに含めているのには理由があります。
コードをコミットするタイミングは、その実装で何が起きたかを最も鮮明に覚えているタイミングだからです。翌日になれば、どんなミスがあったか忘れてしまいます。1週間後には、そもそもどんな実装をしたかすら曖昧になります。
だからこそ、コミットと同時に学びを記録する習慣が重要なのです。
あなた：実装が完了した。以下をお願い：
1. コードをコミット
2. PROGRESS.mdを更新
3. 今回の実装で発生した問題と解決策を
docs/LESSONS.md に追記
この一手間が、未来のあなたとClaudeを救います。
ドキュメントの更新
コミットと同時に、関連ドキュメントも更新します：
あなた：コミットが終わったら、以下のドキュメントも更新してくれ：
1. README.mdに認証機能のセットアップ手順を追加
2. PROGRESS.mdに今日の進捗を記録
3. CHANGELOG.mdに変更内容を追加
4. docs/LESSONS.mdに今回の学びを追記
ドキュメントの更新を後回しにすると、必ず忘れます。コミットとセットで更新する習慣をつけましょう。
TDD（テスト駆動開発）ワークフロー
Anthropicは、テスト駆動開発のワークフローも推奨しています。これは特に、バグが許されない重要な機能を実装するときに有効です。
TDDの6ステップ
-
期待する入出力ペアに基づくテストを書く
あなた：認証APIのテストを先に書いてほしい。 以下のケースをカバーしてくれ： - 正常なログイン - 不正なパスワードでのログイン試行 - 存在しないユーザーでのログイン試行 - トークン期限切れ まだ実装コードは書かないで。テストだけ。 -
テスト実行で失敗を確認
あなた：書いたテストを実行して、すべて失敗することを確認してくれ。 -
テストをコミット
あなた：失敗するテストをコミットしてくれ。 メッセージは「test: 認証APIのテストケース追加（実装前）」で。 -
テストを通すコードを実装
あなた：書いたテストがすべて通るように、認証APIを実装してくれ。 テストは修正しないで。 -
サブエージェントで過剰適合をチェック
あなた：サブエージェントを使って、今の実装がテストに 過剰適合していないか検証してくれ。 エッジケースで壊れないか確認して。 -
コードをコミット
あなた：実装をコミット。 メッセージは「feat: 認証API実装」で。
なぜTDDが効果的なのか
TDDの最大のメリットは、Claudeの暴走を防げることです。
テストを先に書くことで、「期待する動作」が明確になります。Claudeは、そのテストを通すことだけに集中すればよいので、余計な機能を追加したり、想定外の設計判断をしたりするリスクが減ります。
また、テストがあることで、リファクタリングも安心してできます。「この実装を変えたい」と思ったとき、テストが通り続ける限り、変更が正しいことが保証されます。
まとめ：ワークフローの本質
**「Explore → Plan → Code → Commit」**ワークフローの本質は、AIを制御下に置くことです。
vibe codingという言葉には「AIに任せてノリで開発する」というニュアンスがあるかもしれません。しかし実際には、成功するvibe codingは計画的です。AIの能力を最大限に引き出すためには、適切な文脈と明確な指示が必要なのです。
このワークフローを身につければ、あなたはClaudeを「優秀だけど新人のエンジニア」のように扱えるようになります。新人には、いきなり複雑なタスクを丸投げしませんよね？まず全体像を説明し、計画を立てさせ、小さなタスクから任せていく。うまくいったら褒め、間違っていたら軌道修正する。
Claude Codeとの開発も、それと同じです。
次の章では、このワークフローをさらに効率化するCLAUDE.mdとドキュメント設計について詳しく見ていきます。