Best Practices for Claude Code

記事の概要

この記事は、Claude Codeを最大限に活用するためのパターンとヒントをまとめたものです。環境設定から並列セッションのスケーリングまでカバーしています。

出典: https://code.claude.com/docs/en/best-practices

核心メッセージ：コンテキストウィンドウの制約

ほとんどのベストプラクティスは、1つの制約に基づいています：Claudeのコンテキストウィンドウはすぐにいっぱいになり、いっぱいになるとパフォーマンスが低下する

コンテキストウィンドウとは

コンテキストウィンドウには以下のすべてが含まれます：

  • 会話の全メッセージ
  • Claude が読んだ全ファイル
  • コマンドの全出力

なぜ問題か

  • デバッグセッションやコードベース探索 1 回で数万トークンを消費することがある
  • コンテキストがいっぱいになると、Claude は初期の指示を「忘れる」
  • ミスが増える

結論: コンテキストウィンドウは管理すべき最も重要なリソースです。

1. 自己検証手段を与える（最重要）

これが単一で最も効果的なことです

Claude が自分の作業を検証できると、パフォーマンスが劇的に向上します：

戦略 Before After
検証基準を提供する 「メールアドレスを検証する機能を実装する」 「validateEmail関数を記述します。テストケースの例：user@example.comはtrue、invalidはfalse、user@.comはfalse。実装後にテストを実行します。」
UIの変更を視覚的に確認する 「ダッシュボードの見栄えを良くする」 「[スクリーンショットを貼り付け] この設計を実装します。結果のスクリーンショットを撮り、元のデザインと比較します。相違点をリストアップして修正します。」
症状ではなく根本原因に対処する 「ビルドが失敗しています」 「ビルドは次のエラーで失敗しました: [貼り付けエラー]。これを修正し、ビルドが成功することを確認してください。エラーを抑制せず、根本原因に対処してください。」

2. 「探索 → 計画 → 実装」の順に進めよう

Plan Mode（計画モード）を活用する

手順:

  1. Plan Modeに入る - Claudeはファイルを読み、変更を加えずに質問に答えます

    /src/authを読んで、セッションとログインの処理方法を理解して。
シークレットの環境変数管理方法も確認して。

  2. 詳細な実装計画を作成させる

    Google OAuthを追加したい。どのファイルを変更する必要がある？
セッションフローは？計画を作成して。

  3. Normal Modeに戻り、計画に沿って実装させる

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

Plan Mode はいつ使うべきか

状況 推奨
スコープが明確で修正が小さい（タイポ修正、ログ追加、変数名変更） 直接実行させる
アプローチが不確か Plan Mode使用
複数ファイルを変更する Plan Mode使用
変更するコードに不慣れ Plan Mode使用

3. プロンプトに具体的なコンテキストを提供する

戦略 Before After
タスクの範囲を指定します。 対象となるファイル、シナリオ、テストの設定を指定します。 ”foo.py のテストを追加する” 「ユーザーがログアウトしているエッジケースをカバーする foo.py のテストを記述します。モックは避けてください。」
情報源を示してください。 質問に答えられる情報源をクロードに示してください。 「なぜ ExecutionFactory にはこのような奇妙な API があるのでしょうか?」 「ExecutionFactory の Git 履歴を調べて、その API がどのように生まれたかをまとめます」
既存のパターンを参照します。 コードベース内のパターンをClaudeに指示します。 「カレンダーウィジェットを追加する」 パターンを理解するために、ホームページ上の既存のウィジェットの実装方法を確認してください。HotDogWidget.php は良い例です。このパターンに従って、ユーザーが月を選択し、ページを前後に移動して年を選択できる新しいカレンダーウィジェットを実装します。コードベースで既に使用されているライブラリ以外は使用せずに、ゼロから構築します。
症状の詳細を記入してください。 症状、考えられる場所、そして「修復」とはどのような状態かを教えてください。 「ログインバグを修正」 「セッションタイムアウト後にログインに失敗するという報告がユーザーからありました。src/auth/ の認証フロー、特にトークンの更新を確認してください。問題を再現する失敗するテストを記述し、修正してください。」

豊富なコンテンツを提供する

1. @でファイルを参照

コードの場所を説明する代わりに、@でファイルを参照します。Claudeは応答前にそのファイルを読み込みます。

@src/auth/login.ts のバグを修正して

2. 画像を直接貼り付け

コピー＆ペースト、またはドラッグ＆ドロップで画像をプロンプトに追加できます。

3. URLを与える

ドキュメントやAPIリファレンスのURLを与えます。/permissionsでよく使うドメインを許可リストに追加しておくと便利です。

4. データをパイプで渡す

cat error.log | claude

ファイルの内容を直接送り込めます。

5. Claudeに自分で取得させる

Bashコマンド、MCPツール、ファイル読み込みなどを使って、Claude自身にコンテキストを取得させることもできます。

4. 環境を整える

いくつかのセットアップ手順で、すべてのセッションで Claude Code の効果が大幅に向上します。

CLAUDE.md ファイルを作成する

CLAUDE.mdは、Claude が会話開始時に自動で読み込む特別なファイルです。

記載する内容:

  • Bash コマンド
  • コードスタイル
  • ワークフロールール

これにより、コードだけでは推測できない 永続的なコンテキストを Claude に与えられます。

/init コマンドを使う

/init

このコマンドは：

  1. コードベースを分析
  2. ビルドシステム、テストフレームワーク、コードパターンを検出
  3. スターター CLAUDE.md を生成

生成されたファイルは出発点です。時間をかけて改良していきましょう。

CLAUDE.md の例

# コードスタイル

- ES modules構文（import/export）を使用、CommonJS（require）は使わない
- importはできるだけ分割代入する（例: import { foo } from 'bar'）

# ワークフロー

- コード変更の一連の作業が終わったら必ず型チェックを実行
- パフォーマンスのため、テストスイート全体ではなく単一テストを優先

ポイント: フォーマットの決まりはありませんが、短く、人間が読みやすく 保ちましょう。

簡潔にまとめる

CLAUDE.mdファイルが肥大化すると、クロードはあなたの指示を無視してしまいます。CLAUDE.md はセッションごとに読み込まれるため、広く適用される情報のみを含めてください。ドメイン知識や、たまにしか関係のないワークフローについては、スキル を使用してください。

各行について、「これを削除するとクロードは間違いを犯すだろうか？」 と自問してみてください。

✅ 含める ❌ 除外
クロードが推測できないBashコマンド クロードがコードを読んで理解できること
デフォルトとは異なるコードスタイルルール クロードがすでに知っている標準的な言語慣習
テストの手順と推奨テストランナー 詳細な API ドキュメント (代わりにドキュメントへのリンク)
リポジトリのエチケット（ブランチの命名、PR の規則） 頻繁に変更される情報
プロジェクト固有のアーキテクチャ上の決定 長い説明やチュートリアル
開発者環境の癖（必要な環境変数） コードベースのファイルごとの説明
よくある落とし穴やわかりにくい動作 「きれいなコードを書く」といった自明の習慣

権限を設定する

デフォルトでは、Claude Code はシステムを変更する可能性のあるアクション（ファイルの書き込み、Bash コマンド、MCP ツールなど）に対して許可を求めます。これは安全ですが、面倒です。

  • /permissions: 安全であることがわかっている特定のツールを許可します (または npm run lint などgit commit)
  • /sandbox: ファイルシステムとネットワークアクセスを制限する OS レベルの分離を有効にし、定義された境界内でクロードがより自由に作業できるようにします。

CLI ツールを使用する

CLI ツールは、外部サービスとやり取りする最もコンテキスト効率の高い方法です。

  • gh - GitHub
  • aws - AWS

Hook を設定する

例外なく毎回実行する必要があるアクションには Hook を使用します。

Hook は、 Claude のワークフローの特定の時点でスクリプトを自動的に実行します。CLAUDE.md の指示が助言的なものであるのに対し、フックは決定論的であり、アクションの実行が保証されます。

例：

  • 編集後の自動フォーマット
  • 変更ファイルのリント
  • Claude が待機中に通知

Skill を設定する

.claude/skills/ 配下に　SKILL.md でファイルを作成し、Claude にドメイン知識と再利用可能なワークフローを提供します。スキルは、プロジェクト、チーム、またはドメインに固有の情報で Claude の知識を拡張します。

---
name: api-conventions
description: サービスの REST API 設計規約
---

# API 規約

- URL パスにはケバブケースを使用
- JSON プロパティにはキャメルケースを使用
- リストエンドポイントには必ずページネーションを含める
- URL パスで API をバージョニング（/v1/、/v2/）

スキルでは、直接呼び出す繰り返し可能なワークフローを定義することもできます。

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---

Analyze and fix the GitHub issue: $ARGUMENTS.

1. Use `gh issue view` to get the issue details
2. Understand the problem described in the issue
3. Search the codebase for relevant files
4. Implement the necessary changes to fix the issue
5. Write and run tests to verify the fix
6. Ensure code passes linting and type checking
7. Create a descriptive commit message
8. Push and create a PR

カスタムサブエージェントを作成する

.claude/agents/ クロードが個別のタスクを委任できる専門のアシスタントを定義します。

サブエージェントは、独自のコンテキストで、許可されたツールセットを使用して実行されます。サブエージェントは、メインの会話を乱すことなく、多数のファイルを読み取るタスクや、特定の処理に集中する必要があるタスクに役立ちます。

---
name: security-reviewer
description: セキュリティ脆弱性のコードレビュー
tools: Read, Grep, Glob, Bash
model: opus
---
あなたはシニアセキュリティエンジニアです。以下の観点でコードをレビューしてください:
- インジェクション脆弱性（SQL、XSS、コマンドインジェクション）
- 認証・認可の欠陥
- コード内のシークレットや認証情報
- 安全でないデータ処理

具体的な行番号の参照と修正案を提供してください。

5. 効果的なコミュニケーションをする

シニアエンジニアに聞くような質問をする

新しいコードベースにオンボーディングする際、Claude Codeを学習と探索に活用できます。他のエンジニアに聞くのと同じような質問ができます：

質問例:

  • foo.rsの134行目のasync move { ... }は何をしている？
  • CustomerOnboardingFlowImplはどんなエッジケースを処理している？
  • なぜこのコードは333行目でbar()ではなくfoo()を呼んでいる？

大きな機能には、まず Claude にインタビューさせる

より大きな機能を作る場合、まず Claude にインタビューをさせることで、見落としがちなポイントを洗い出せる。

質問: 「[簡単な説明]を作りたい。AskUserQuestion ツールを使って 詳細にインタビューして。

技術的な実装、UI/UX、エッジケース、懸念点、トレードオフについて
質問して。明らかな質問はしないで、私が考えていなかった
難しい部分を掘り下げて。

すべてカバーするまでインタビューを続けて、
その後完全な仕様書をSPEC.mdに書いて」

6. セッションを管理する

早期かつ頻繁に軌道修正する

ショートカット 動作
Esc Claudeの作業を途中で停止（コンテキストは保持）
Esc + Esc or /rewind リワインドメニューを開き、会話とコード状態を復元
Undo that Claudeに変更を取り消させる
/clear 無関係なタスク間でコンテキストをリセット

重要なルール:

同じ問題について2回以上修正したら、コンテキストは失敗したアプローチで散らかっている。/clearを実行し、学んだことを組み込んだより具体的なプロンプトで新たに始めよう。

調査にはサブエージェントを使用する

コンテキストが根本的な制約であるため、サブエージェントは最も強力なツールの1つです

Claudeがコードベースを調査すると、多くのファイルを読み込み、すべてがコンテキストを消費します。サブエージェントは別のコンテキストウィンドウで実行され、サマリーを報告します。

使用例:

Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.

Claude が何かを実装した後、検証のためにサブエージェントを使用することもできます。

use a subagent to review this code for edge cases

⚠️ よくある失敗パターン（アンチパターン）

1. キッチンシンク・セッション

症状: 1つのタスクから始めて、無関係なことを質問し、また最初のタスクに戻る。コンテキストが無関係な情報でいっぱいになる。

解決策: /clearを無関係なタスク間で使用する。

2. 何度も修正を繰り返す

症状: Claudeが何か間違いをする→修正する→まだ間違い→また修正する。コンテキストが失敗したアプローチで汚染される。

解決策: 2回の修正に失敗したら、/clearして学んだことを組み込んだより良い最初のプロンプトを書く

3. 過度に詳細な CLAUDE.md

症状: CLAUDE.md が長すぎると、Claude はその半分を無視する。重要なルールがノイズの中で埋もれてしまう。

解決策:

  • 容赦なく削る
  • Claude が指示なしで既に正しく行っていることは削除するか、フックに変換する

4. 信頼してから検証するギャップ

症状: Claude がもっともらしい実装を生成するが、エッジケースを処理していない。

解決策: 常に検証手段を提供する（テスト、スクリプト、スクリーンショット）。