AI・テクノロジー

Claude Codeを使いこなすベストプラクティス完全ガイド2026

anchang info 約2分で読めます

Claude Codeを使い始めたけど「なんとなく動く」止まりで、もう一段上の使い方がしたい——そんなエンジニア向けに、公式ドキュメントのベストプラクティスを日本語でまとめました。読み終わる頃には、Claude Codeとの向き合い方が根本から変わるはずです。

Claude Codeはチャットボットではない

最初に認識を合わせておきましょう。Claude Codeは「質問に答えるチャットボット」ではなく、コードベース全体を把握して自律的にタスクをこなすエージェントです。

この違いは使い方に直結します。チャットボットなら「どうすればいいですか？」と聞けばいい。でもエージェントに対しては「このファイルを読んで、このテストをパスするように実装して、最後にコミットしてください」と、目的・制約・完了条件をセットで渡すほうが圧倒的に成果が出ます。

そしてClaude Codeを使う上で最も重要なリソースがコンテキストウィンドウです。会話が長くなるほどコンテキストは埋まり、古い情報が押し出されて精度が落ちます。これを前提に、セッション管理・タスク分割・サブエージェントの使い分けを設計する必要があります。

1. 検証手段を与える（最重要プラクティス）

Claude Codeに「うまくいったかどうか」を自分で確認させることが、品質の最大の担保になります。

Before / After で見る違い

Before（曖昧な指示） After（検証手段つき）
「ログイン機能を修正して」 「tests/test_auth.py を実行して全テストがパスするように修正して」
「UIを改善して」 「スクリーンショットを撮って、ボタンが中央揃えになっているか確認して」
「バグを直して」 「npm run dev で起動後、http://localhost:3000/dashboard にアクセスして404が出ないことを確認して」

テストがない場合は、Claude Codeに先にテストを書かせる方法も有効です。

まずこの機能の期待動作をテストとして書いてください。
その後、テストがパスするように実装してください。

これにより、「実装した気になっているだけ」の状態を防げます。スクリーンショット・ログ・エラーメッセージを貼り付けて渡すことも、検証精度を大きく上げます。

2. Explore → Plan → Code → Commit の4段階フロー

複雑なタスクほど、いきなりコードを書かせるのは失敗のもとです。公式が推奨する4段階フローを使いましょう。

Step 1: Explore（探索）

まずコードベースを理解させます。

このリポジトリの認証まわりのコードをすべて読んで、
現在の実装方式を説明してください。コードは書かないでください。

Step 2: Plan（計画）

Plan Modeを使って実装方針だけを決めます。このモードではファイルの変更が行われないため、安全に計画を練れます。

[Plan Mode で] 
JWT認証をSession認証に移行する計画を立ててください。
影響ファイル・変更順序・リスクを整理してから提案してください。

Step 3: Code（実装）

計画を確認したら通常モードで実装します。

先ほどの計画に従って実装してください。
各ファイルの変更後に `python -m pytest tests/test_auth.py` を実行して確認してください。

Step 4: Commit（確定）

テストがパスしたらコミットします。

変更内容を確認して、適切なコミットメッセージでコミットしてください。

小さなタスク（1ファイル・1関数の修正など）は、いきなり「Code」から始めて問題ありません。複雑さに応じてフローの深さを調整するのがポイントです。

3. 具体的なプロンプトの書き方

「なんとなく通じる指示」から「確実に意図が伝わる指示」へのアップグレード方法です。

ファイル・制約・パターンを明示する

# 曖昧
「APIエンドポイントを追加して」

# 具体的
「`app/routes/users.py` に GET /users/{id}/posts エンドポイントを追加してください。
既存の `get_user()` 関数のパターンに合わせて実装し、
`tests/test_users.py` に対応するテストも追加してください。
認証はJWTミドルウェアを使用します（既存実装を参照）。」

@ファイル参照・画像・URLを活用する

  • @src/components/Button.tsx — 特定ファイルを参照させる
  • スクリーンショットをそのまま貼り付ける — UI修正に効果的
  • URLを貼ると内容を取得して活用してくれる

完了条件を明示する

以下をすべて満たした時点で完了とします：
1. `npm test` が全件パス
2. `npm run build` がエラーなし
3. 変更したファイルのみコミット済み

4. 環境設定：CLAUDE.md を正しく書く

CLAUDE.md はClaude Codeがプロジェクトに参加するたびに読む「引き継ぎ書」です。ここの質がそのまま出力の質に直結します。

含めるべきもの vs 不要なもの

含めるべき 不要・逆効果
よく使うコマンド（npm run dev、テスト実行コマンド等） 当たり前のこと（「コードは丁寧に書くこと」等）
プロジェクト固有のルール（命名規則・フォルダ構成） 他所からコピーしてきた汎用的なガイドライン
使ってはいけないライブラリ・パターン ドキュメントで代替できる詳細な説明
環境変数の場所・設定方法 頻繁に変わる情報（メンテ漏れの原因）
エラー時の対処法（既知の罠）

CLAUDE.md の肥大化に注意

「念のため書いておこう」の積み重ねで CLAUDE.md が肥大化すると、重要な情報が埋もれて逆効果になります。定期的に棚卸しして、本当に必要な情報だけを残すようにしましょう。

パーミッション設定

Claude Codeには3つのパーミッションモードがあります：

  • 通常モード: 変更前に確認を求める（デフォルト）
  • Auto Mode: 確認なしで自動実行（自動化向け）
  • Allowlist: 特定コマンドのみ自動許可

繰り返し実行するコマンド（テスト・ビルド）はAllowlistに追加しておくと、確認プロンプトが減って作業が快適になります。

5. セッション管理

/clear でコンテキストをリセット

タスクが一区切りついたら /clear でコンテキストをリセットします。不要な情報が詰まったまま次のタスクに進むと、精度が落ちる原因になります。

目安： - 1つのタスクが完了したとき - コンテキストが50%を超えてきたとき - 話題が大きく変わるとき

/rewind でチェックポイントに戻る

「やっぱりこの実装方針は違った」と思ったとき、/rewind で以前の状態に戻れます。コードを手動で戻す手間が省けます。

サブエージェントで調査を分離する

調査・実装・レビューを同じセッションで混在させると、コンテキストが無駄に消費されます。調査は別のサブエージェントに任せることで、メインセッションをクリーンに保てます。

# 調査専用サブエージェントに渡す例
「このライブラリのv3からv4への破壊的変更を調査して、
影響を受けるファイルのリストだけを返してください。
コードは変更しないでください。」

6. 並列実行・自動化

Non-interactive Mode（claude -p）

CI/CDや自動化スクリプトから呼び出す場合は -p フラグを使います。

# パイプラインに組み込む例
claude -p "src/components/ 配下のすべてのコンポーネントにアクセシビリティ属性を追加してください" \
  --allowedTools "Edit,Read"

Writer / Reviewer パターン

実装エージェントとレビューエージェントを分けて使うパターンです。

# Writer（実装）
「この機能を実装してください」

# Reviewer（レビュー・品質確認）
「実装された内容を確認して、バグ・セキュリティ上の問題・
パフォーマンス上の問題をリストアップしてください。
コードは変更しないでください。」

同じコンテキストで実装とレビューをさせると「自分で作ったものを自分でチェック」になるため、別セッションにするのが効果的です。

Fan-out（ファイル一括処理）

複数ファイルへの同じ処理を並列で実行するパターンです。

# 各ファイルに対して並列でサブエージェントを起動する例
for file in src/components/*.tsx; do
  claude -p "このファイルのPropsの型定義をzodスキーマに移行してください: $file" &
done
wait

7. よくある失敗パターンと対策

Kitchen Sink セッション

問題: 1つのセッションで複数の無関係なタスクを詰め込む。 対策: タスク単位でセッションを分ける。完了後は /clear。

修正の繰り返し

問題: 「ちょっと直して → また違う → また直して」の無限ループ。 対策: 最初に完了条件を明示する。途中で方針変更するなら /rewind でリセット。

CLAUDE.md の肥大化

問題: 書き続けた結果、重要な情報が埋もれる。 対策: 月に一度棚卸し。「これが無くても困らない」情報は削除する。

検証ギャップ

問題: 「実装しました」で終わり、実際に動くかを確認しない。 対策: 指示の中に必ず検証コマンドを含める。テストがなければ先に書かせる。

まとめ：Claude Codeを使いこなす5つの鉄則

  1. 検証手段を必ず渡す — テスト・コマンド・期待値をセットで指示する
  2. 計画してから実装する — 複雑なタスクはExplore→Plan→Code→Commitの順に
  3. 具体的に指示する — ファイル名・制約・完了条件を明示する
  4. コンテキストを管理する — /clearを活用し、セッションを使い捨て感覚で使う
  5. CLAUDE.mdを育てる — 本当に必要な情報だけを凝縮して書く

Claude Codeは「指示の質がそのまま出力の質になる」ツールです。最初は丁寧に指示を書く手間を感じるかもしれませんが、慣れてくると「このパターンで動く」という感覚がつかめてきます。ぜひ今日から試してみてください。

関連記事