Claude Code を半年以上使ってみて、書いたコードの数よりも踏んだ落とし穴の方が多い
最初は、Claude Code は「ちょっと高度な Copilot」だと思っていました。ターミナルに入力すればコードを書いてくれる、それだけだと。しかし後になって、このツールの天井は想像以上に高い こと、ただし使い方を知っている場合に限る、と気づきました。
この記事では、公式ドキュメントと実践経験を組み合わせて、最も重要な使い方のコツをまとめました。中には苦い経験から学んだものもあれば、ドキュメントを読んで初めて知った隠し機能もあります。
1. CLAUDE.MD: 最も過小評価されている機能
この記事から一つだけ覚えるなら、これです：CLAUDE.md をしっかり書きましょう。
CLAUDE.md は、Claude Code が会話の開始時に自動的に読み込む指示ファイルです。新しい同僚のために書くオンボーディングドキュメントのようなもので、知っておいてほしいことをすべてそこに書きます。
多くの人は CLAUDE.md を書かなかったり、数行しか書かなかったりします。その結果、毎回の会話でプロジェクト構成、コーディング規約、技術スタックの選択理由を一から説明しなければなりません。毎朝、会社の説明を同僚にやり直すようなものです。
良い CLAUDE.md に含めるべき内容：
1# プロジェクト名23## ビルドとテストのコマンド4- 依存関係のインストール: npm install5- テストの実行: npm test6- 単一テスト: npm test -- --grep "テスト名"7- フォーマット: npm run format89## コーディング規約10- Python: ruff を使用、行幅 8811- テスト: pytest を使用、サービスごとに 1 つのテストファイル12- API ルート: 複数形のファイル名を使用: users.py、orders.py13- コミットメッセージ: 英語、形式: type(scope): description1415## アーキテクチャ上の決定16- CSS Modules ではなく Tailwind を選択（チームで標準化したため）17- ユーザー権限チェックはミドルウェアで行う。各ルートで繰り返さない18- Redis キャッシュキーのプレフィックス: app:v1:1920## よくある落とし穴21- DB コネクションプールの上限は 20。ループ内で新しい接続を開かない22- データベースをモックしない。前回モックは通ったが本番マイグレーションが失敗した
重要な原則：
まず、コードから推測できないことを書く。 プロジェクトの「何を」よりも「なぜ」が重要です。React の使い方を説明する必要はありませんが、「チームで標準化したから Tailwind を選んだ」と伝える必要があります。
次に、200 行以内に収める。 公式ドキュメントには、CLAUDE.md が長すぎると Claude がルールを無視する可能性があると明記されています。Markdown の見出しとリストを使ってスキャンしやすくしましょう。
第三に、頻繁に変更される内容は入れない。 詳細な API ドキュメントやファイルごとの説明は CLAUDE.md には不向きです。リンクを提供するだけにしましょう。
CLAUDE.md の 4 つのレベル
Claude Code は 4 つのレベルの CLAUDE.md をサポートしており、優先順位の高い順に並んでいます：
私のグローバル CLAUDE.md には、通常次のように書いています：
1- 私はフルスタックエンジニア。基本的な概念を過剰に説明する必要はない2- 返信は簡潔に。不要な挨拶は省略3- コード変更後に何をしたか要約しない。diff を確認する4- シンプルな解決策を優先。過剰設計は避ける
この 4 行で、何百回もの繰り返しの修正を省けます。
応用編：.claude/rules/ でルールを整理する
プロジェクトが大きくなるにつれて、1 つの CLAUDE.md ファイルでは収まりきらなくなります。公式の解決策はより洗練されています：ルールを .claude/rules/ ディレクトリに分割する。
1.claude/rules/2├── testing.md # テスト規約3├── api-style.md # API の書き方4└── frontend.md # フロントエンドの規約
さらに強力なことに、YAML フロントマターを使ってルールを特定のファイルに限定できます：
1---2paths: ["src/api/**/*.ts", "src/routes/**/*.ts"]3---45API ルートには入力検証とエラーハンドリングを含めること。6すべての新しいエンドポイントには tests/api/ に統合テストが必要。
これにより、Claude が一致するファイルにアクセスしたときだけルールが読み込まれ、コンテキストスペースを節約できます。
2. プロンプトの品質が出力の品質を決める
これは決まり文句のように聞こえますが、あまりにも多くの人が Claude Code を次のように使っているのを見てきました：
「ログイン機能を書いて」
そして、生成された大量のコードに頭を悩ませる——こんなはずじゃなかった、と。
良い指示には 3 つの要素が必要です：目標、制約、コンテキスト。
悪い指示 vs 良い指示
悪い例：「ユーザー一覧に検索機能を追加して」
良い例：「@src/pages/UserList.tsx のテーブルの上に検索ボックスを追加して。検索はバックエンド API /api/users?search=xxx を使い、フロントエンドでのフィルタリングはしない。300ms のデバウンスを使用し、スタイルは既存の Filter コンポーネントに合わせて。」
違いは何でしょうか？良い指示は曖昧さを減らします。Claude Code は、フロントエンド検索かバックエンド検索か、デバウンス時間、スタイルの基準を推測する必要がありません。
公式推奨のプロンプトのコツ
1. @ を使って特定のファイルを参照する
Claude Code は @filepath を使ってファイルの内容を直接コンテキストに取り込むことができます。「あの認証関連のコード」と言うよりも、@src/auth/login.ts と書く方がはるかに正確です。行範囲も指定できます：@src/auth/login.ts#5-30。
2. スクリーンショットや画像を貼り付ける
Ctrl+V で画像を直接貼り付けられます。UI の問題をデバッグするとき、「今の見た目」と「理想の見た目」のスクリーンショットは、テキストでの説明よりも 10 倍効果的です。
3. 検証基準を提供する
「このバグを直して」と言うだけではなく、次のように言いましょう：
「ログインタイムアウト後の再認証が失敗する問題を修正して。修正後、トークン期限切れ後に任意のボタンをクリックすると自動的にログインページにリダイレクトされるように。テストケースは @tests/auth.test.ts にあるので、修正後に実行して確認して。」
Claude に自己検証可能な基準（テストケース、スクリーンショット、期待される出力）を与えることで、自身の作業品質をチェックでき、やり取りの往復を減らせます。
4. やってほしくないことを明確に伝える
Claude Code は時に熱心すぎることがあります——バグを修正してほしいのに、周辺のコードもリファクタリングしてしまう。「この関数だけ変更して、他のコードには触らないで」と明示的に言うことで、多くの手間を省けます。
曖昧な指示が役立つとき
すべての状況で正確さが必要なわけではありません。探索的なタスクには、曖昧な指示の方が適しています：
- 「このファイルで改善できる点は？」
- 「このモジュールのアーキテクチャを理解するのを手伝って」
- 「このコードに潜在的な問題はある？」
しかし、実装段階に入ったら、正確さモードに戻しましょう。
3. プランモード：行動する前に明確に考える
Claude Code にはプランモードがあり、これが最も過小評価されているワークフローだと思います。
プランモードに入る方法
3 つの方法：
1# プランモードで直接開始2claude --permission-mode plan34# 会話中に切り替え（Shift+Tab を 2 回押す）5Shift+Tab Shift+Tab67# プロンプトで指示8「まだコードを変更しないで、計画を立てるのを手伝って」
プランモードでは、Claude Code はファイルの読み取りとコードの検索のみが可能で、変更は一切できません。 コードベースを探索し、要件を分析し、詳細な実装計画を提供します。
プランモードの正しい使い方
重要な操作：Ctrl+G を押して、エディタで計画を開いて編集します。
つまり、次のことが可能です：
- Claude に初期計画を生成させる
- Ctrl+G で計画を開き、同意できない部分を削除し、自分のアイデアを追加する
- 通常モードに戻して（Shift+Tab）、修正した計画に従って Claude に実行させる
計画を変更するのは一文で済みます。すでに書かれたコードを変更するのは 10 倍の時間がかかります。
複雑なタスクの推奨ワークフロー
公式の標準プロセスは 4 つのステップです：探索 → 計画 → 実装 → 検証。
11. プランモードに入る22. Claude に関連コードを読ませる：「src/auth/ のコードを読んでセッションロジックを理解して」33. 計画を依頼する：「OAuth2 移行計画を立てて」44. Ctrl+G で計画を確認・編集55. 通常モードに戻す66. 「計画に従って実装し、書き終えたらテストを実行して」77. Claude に要件に照らして自己チェックさせる
プランモードが不要なとき
- 変数名の変更
- 明らかなタイプミスの修正
- 1 行のログ追加
基準はシンプルです：タスクの実装方法が 1 つしかないなら、直接実行する。複数の選択肢があるなら、まず計画を立てる。
4. サブエージェント：Claude Code のマルチタスク能力
サブエージェントは強力なメカニズムです——Claude Code は独立した AI プロセスを起動して、タスクを並行して処理できます。各サブエージェントは独自のコンテキストウィンドウを持ち、メインの会話を乱しません。
組み込みのサブエージェントタイプ
サブエージェントの最大の価値：コンテキストの分離
Claude にテストの実行、ログの分析、多くのファイルの検索を依頼すると、これらの操作は大量の出力を生成し、コンテキストウィンドウを埋め尽くします。これらのタスクにはサブエージェントを使用しましょう。出力はサブエージェントのコンテキストに留まり、要約だけが返されます。
例えば：
「サブエージェントを使ってすべてのテストを実行し、失敗したケースをリストアップして」
「サブエージェントを使って非推奨 API を使用しているすべてのファイルを検索して」
バックグラウンド実行：Ctrl+B
Ctrl+B を押すと、サブエージェントをバックグラウンドに回せます。Claude と他のことについて会話を続けられ、バックグラウンドタスクが完了すると通知されます。
適している用途：
- テストスイートの実行（通常数分かかる）
- 大規模なコード検索
- 緊急でないコードレビュー
カスタムサブエージェント
.claude/agents/ ディレクトリにカスタムエージェントを作成できます：
1---2name: code-reviewer3description: コードレビューの専門家。コード変更後に自動的に起動。4tools: Read, Grep, Glob, Bash5model: sonnet6---78あなたはシニアコードレビュアーです。以下の観点をチェックしてください：9- コードの明確さと可読性10- エラーハンドリングの完全性11- 機密情報の露出12- 入力検証13- パフォーマンス上の問題
そして、会話中に @"code-reviewer (agent)" を使って呼び出します。
5. コンテキスト管理：最も見落とされがちな鍵
Claude Code のコンテキストウィンドウは大きいですが（最大 100 万トークン）、無限ではありません。そしてコンテキスト管理が出力の品質を直接左右します。
コンテキストに含まれるもの
- 会話履歴
- Claude が読み取ったすべてのファイルの内容
- コマンド実行の出力
- CLAUDE.md ファイル（毎回読み込まれる）
- メモリファイル（最初の 200 行）
- 読み込まれたスキルと MCP ツールの定義
5 つの実践的な戦略
1. /clear：タスクが終わったらクリアする
バグ修正、機能追加、リファクタリングをすべて同じ会話で行わないでください。/clear はコンテキストを空にしますが、CLAUDE.md は保持し、無料の再起動のように機能します。
2. /compact：手動でコンテキストを圧縮する
会話が長くなったら、/compact を使って Claude に過去の会話を自動的に要約・圧縮させます。さらに良い方法は、圧縮に焦点を追加することです：
/compact focus on API changes and test results
これにより、Claude は圧縮時に関心のある内容を優先的に保持します。
3. /context：コンテキストを消費しているものを確認する
/context と入力すると、現在の使用状況が表示されます——どのファイルが何トークン使用しているか、MCP ツール定義がどのくらいのスペースを占めているか。私はよく、使っていない MCP サーバーが大量のスペースを占有しているのを発見します。
4. サブエージェントを使ってノイズを分離する
テストの実行やログの分析は多くの出力を生成します。サブエージェントに任せて、メインの会話コンテキストをクリーンに保ちましょう。
5. CLAUDE.md に圧縮保持指示を書く
Claude に圧縮時に何を保持すべきかを伝えられます：
1# 圧縮指示2コンテキストを圧縮するときは、常に以下を保持：3- 変更されたファイルの完全なリスト4- テストコマンドと結果5- 主要なアーキテクチャ上の決定
メモリ vs CLAUDE.md
メモリの用途： あなたの好み（「この人は簡潔な返信を好む」）、プロジェクトの慣習（「デプロイには特別な手順がある」）、過去の決定（「前回は X の理由でオプション A を選んだ」）。
メモリに適さないもの： コードの詳細、Git 履歴、一時的な状態——これらはコードや Git からより正確に取得できます。
/memory コマンドを使って、読み込まれているすべてのメモリを表示・管理できます。
6. 権限管理：セキュリティと効率のバランス
Claude Code は 5 つの権限モードを提供し、会話中に Shift+Tab で切り替えられます：
権限ルールの設定
.claude/settings.json で、各ツールの権限を細かく制御できます：
1{2 "permissions": {3 "allow": [4 "Bash(npm run *)",5 "Bash(git commit *)",6 "Edit(src/**/*.ts)",7 "Read(*.md)"8 ],9 "deny": [10 "Bash(rm -rf *)",11 "Edit(.env)"12 ]13 }14}
ルールの優先順位：deny → ask → allow（deny が最優先）。
つまり、一般的なコマンドは大胆に許可し、deny で機密ファイルを保護できます。例えば、.env ファイルは決して編集されるべきではありません。
設定ファイルの階層
CLAUDE.md と同様に、設定にも複数のレベルがあります：
1組織ポリシー（最優先）2 ↓3CLI 引数4 ↓5.claude/settings.local.json（ローカル、Git にコミットしない）6 ↓7.claude/settings.json（プロジェクトレベル、チームで共有）8 ↓9~/.claude/settings.json（グローバル、個人用）10 ↓11デフォルト値（最低優先順位）
私のアドバイス：チームで共有するルールは .claude/settings.json に、個人の好みは ~/.claude/settings.json に、機密設定は .claude/settings.local.json に（.gitignore に追加するのを忘れずに）。
7. フック：ルールを鉄則に変える
CLAUDE.md の指示は「提案」です——Claude はほとんどの場合従いますが、時々忘れることがあります。フックは「鉄則」です——何があっても実行されます。
フックは、特定のライフサイクルイベントによって自動的にトリガーされるシェルコマンドで、settings.json で設定します。
主要なイベントタイプ
実践例
自動フォーマット——編集後に Prettier を実行：
1{2 "hooks": {3 "PostToolUse": [{4 "matcher": "Edit|Write",5 "hooks": [{6 "type": "command",7 "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"8 }]9 }]10 }11}
重要なファイルの保護——本番設定の変更を防止：
1{2 "hooks": {3 "PreToolUse": [{4 "matcher": "Edit|Write",5 "hooks": [{6 "type": "command",7 "command": ".claude/hooks/protect-files.sh"8 }]9 }]10 }11}
フックコマンドが終了コード 0 を返せば許可、終了コード 2 を返せばブロックされます。つまり、任意の複雑なロジックを書くことができます。
コンテキスト圧縮後に重要な情報を再注入：
1{2 "hooks": {3 "SessionStart": [{4 "matcher": "compact",5 "hooks": [{6 "type": "command",7 "command": "echo 'Bun を使用し、npm は使わない。コミット前に bun test を実行すること。'"8 }]9 }]10 }11}
これはよくある問題を解決します：長い会話が圧縮されると、以前に言及された重要な指示が失われる可能性があります。フックは圧縮のたびに自動的にそれらを再注入できます。
4 種類のフック
8. GIT ワークフロー：WORKTREE を活用する
Claude Code は Git コマンドを実行できますが、これは諸刃の剣です。しかし、公式ツールは優れたセーフティネットを提供します：Worktree。
Git Worktree：分離されたワークスペース
1# 分離されたワークツリーで Claude を起動2claude --worktree feature-auth3claude --worktree bugfix-12345# 自動的に名前を生成6claude --worktree
Worktree は、.claude/worktrees/ の下に独立した Git ブランチのコピーを作成します。Claude が内部で何をしても、メインブランチには影響しません。終了時：
- 変更がない場合 → 自動クリーンアップ
- 変更がある場合 → 保持するか削除するか確認
これは特に探索的なタスクに便利です。 リファクタリング計画がうまくいくかわからない？ワークツリーで試してみて、失敗したらリスクゼロで破棄できます。
Git のいくつかの鉄則
1. Claude Code に自動プッシュさせない
コミットは許可しても、プッシュは自分で確認すべきです。リモートにプッシュしてしまうと、ロールバックのコストが大幅に上がります。
2. 頻繁にコミットする
小さな機能が完了したらコミットします。/rewind を使って任意のチェックポイントに戻れますが、コミット記録がある場合に限ります。
3. 破壊的な操作に注意する
Claude Code が git reset --hard、git push --force、rm -rf を実行しようとしたら、承認する前に結果をよく考えてください。 これらの操作は元に戻せません。権限ルールでこれらのコマンドを拒否することもできます。
4. PR からコンテキストを復元する
これにより、PR の変更と議論がコンテキストとして自動的に読み込まれ、コードレビューや他の人の作業の継続に最適です。
1claude --from-pr 123
9. ショートカットとコマンドリファレンス
私はこれらのショートカットを毎日使っています。ぜひ覚えてください：
最も一般的なショートカット
最も一般的なスラッシュコマンド
1/compact [focus] # コンテキストを圧縮、焦点を指定可能2/clear # 会話をクリア、最初からやり直し3/context # コンテキスト使用状況を表示4/memory # メモリを表示・管理5/rewind # チェックポイントにロールバック6/resume [name] # 以前の会話を再開7/model # モデルを切り替え8/effort [level] # 推論の深さを設定：low/medium/high/max9/init # CLAUDE.md を自動生成10/mcp # MCP サーバーを管理11/permissions # 権限ルールを表示12/cost # トークン消費量を表示
/init は新しいプロジェクトで特に便利です——コードベースを自動的に分析し、CLAUDE.md のドラフト生成を支援します。通常は手動での調整が必要ですが、ゼロから始めるよりはるかに速いです。
10. 拡張思考：Claude にもっと深く考えさせる
複雑な問題には、拡張思考モードを有効にすることで、Claude が回答前により多くの時間をかけて推論できるようになります。
使用方法
1# ショートカットで切り替え2Option+T（Mac）/ Alt+T（Windows/Linux）34# またはコマンドで5/effort high # より深い推論6/effort max # 最大の推論深度7/effort low # 単純なタスク、トークンを節約
使用すべきタイミング
- 複雑なアーキテクチャ上の決定
- 厄介なデバッグ（複数の可能性のある原因を排除）
- 複数ステップのリファクタリング設計
- 複数の解決策のメリット・デメリットの比較
不要なとき
- 単純なコード変更
- フォーマット、名前変更
- すでに明確なバグ修正
プロのコツ： プロンプトに「ultrathink」と書くと、手動で努力設定を調整しなくても、最高の推論深度を強制できます。
11. MCP サーバー：Claude を外部世界に接続する
MCP（Model Context Protocol）により、Claude Code は外部ツール（GitHub、データベース、Slack、Notion など）と通信できます。
クイック追加
1claude mcp add github -- npx @anthropic-ai/mcp-server-github2claude mcp add postgres -- npx @anthropic-ai/mcp-server-postgres postgresql://localhost:5432/mydb
設定ファイル
MCP は .mcp.json で設定します：
1{2 "mcpServers": {3 "github": {4 "type": "stdio",5 "command": "npx",6 "args": ["@modelcontextprotocol/server-github"],7 "env": {8 "GITHUB_TOKEN": "$GITHUB_TOKEN"9 }10 }11 }12}
コンテキストのオーバーヘッドに注意
各 MCP サーバーは、ツール定義のために追加で 100～500+ トークンを消費します。 /mcp コマンドを使って各サーバーのオーバーヘッドを確認し、使用していないものは無効にしましょう。
私の経験：欲張らないこと。 よく使う 2～3 個の MCP サーバーで十分です。あまり多くインストールすると、ツール定義でコンテキストスペースを消費し、コード分析の品質が低下する可能性があります。
12. IDE 統合：ターミナル以上のもの
VS Code
Claude Code 拡張機能をインストールすると、ターミナルに切り替えなくても VS Code 内で直接 Claude を使用できます。
便利な機能：
- サイドバイサイドの差分表示：Claude の変更が差分として表示され、一目でわかります
- Option+K / Alt+K：現在のファイルへの @参照をすばやく挿入
- マルチタブ会話：異なるタブで複数の独立した会話を開く
- Cmd+Shift+Esc：新しい会話タブをすばやく開く
JetBrains
IntelliJ、PyCharm、WebStorm などの JetBrains IDE にも Claude Code プラグインがあります。プラグインマーケットプレイスで「Claude Code」を検索してインストールしてください。
13. コードレビュー：信頼するが検証する
Claude Code のコード品質は概ね良好ですが、盲目的に信頼してはいけません。
よくある問題
1. 過剰設計
単純なユーティリティ関数を依頼したのに、ジェネリクス、インターフェース、ファクトリパターンを備えた完全な抽象化レイヤーが返ってくる。釘を打つためにハンマーではなく、巨大な岩を使うようなものです。
解決策： CLAUDE.md に「シンプルな解決策を優先」と書くか、指示で「抽象化は不要」と明示的に伝える。
2. 幻覚 API
存在しない API や古い構文を使用することがあります。特に、ニッチなライブラリの新しいバージョンで発生します。
解決策： テストを実行する。これが、指示に検証基準を含めるべき理由です。
3. スコープの拡大
1 つの関数を変更してほしいのに、ファイル全体をリファクタリングしてしまう。
解決策： 「X だけを変更し、他のコードには触らないで」と明示的に伝える。または、/freeze コマンドを使って編集範囲を特定のディレクトリに制限する。
ライター／レビュアーモード
公式に推奨されている高度なモード：2 つの独立したセッションを使って、「ライター」と「レビュアー」の役割を分担します。
2 つのセッションは独立したコンテキストを持ち、レビュアーはライターのロジックに影響されず、盲点を見つけられます。
1セッション A（ライター）：「API レート制限ミドルウェアを実装して」2セッション B（レビュアー）：「@src/middleware/rateLimiter.ts のレート制限実装をレビューして、3 エッジケース、競合状態、一貫性に注目して」4セッション A：「レビューフィードバックを修正：[B の出力を貼り付け]」
14. Claude Code でやってはいけないこと
「やるべきこと」をたくさん話してきたので、次は「やってはいけないこと」について話しましょう。
1. まったく理解していないことをやらせない
Kubernetes について何も知らないなら、Claude Code にデプロイ設定を書かせてそのまま使ってはいけません。理解できないものはレビューできません。
2. バージョン管理のない環境で使わない
Git がないとロールバックできません。Claude Code の変更はファイルを上書きする可能性があり、バージョン管理なしで使うのは、ネットなしの綱渡りのようなものです。
3. 巨大なタスクを一度に投げない
「プロジェクト全体を JavaScript から TypeScript に移行して」
この指示は Claude Code に自由を与えすぎて、結果が制御不能になります。小さなステップに分割し、各ステップを確認してから次に進みましょう。
4. 最初の試行で完璧を期待しない
反復は普通です。/rewind を使って戻り、正確なフィードバックで「何が悪いのか」を説明しましょう。
まとめ
Claude Code を使う上での核となる哲学はシンプルです：
それは非常に有能な協力者ですが、自動操縦装置ではありません。ハンドルは常にあなたの手にあります。
重要度順に、私のアドバイスは次のとおりです：
- CLAUDE.md を適切に作成する — 一度投資すれば、すべての会話で恩恵を受けられます
- 正確な指示を与える — 目標 + 制約 + 検証基準
- Plan モードを使用する — 複雑なタスクでは、まず計画を立て、後で実行する
- コンテキストを管理する — /clear、/compact、サブエージェント
- 権限を制御する — 危険な操作は拒否し、一般的なコマンドは許可する
- 頻繁にコミットする — ロールバックする能力を維持する
これらを実践すれば、Claude Code はあなたの効率を数倍に高めてくれます。実践しなければ、より速く混乱を生み出すだけのツールになってしまいます。
ツールの価値は、常にそれを使う人次第です。
上記は、Claude Code の公式ドキュメントと実践経験を組み合わせたものです。より良いプラクティスがあれば、ぜひ共有してください。
![マーク・ザッカーバーグの天才的な AI 戦略：生活とビジネスへの AI 統合術 [プロンプト付き]](/cdn-cgi/image/width=1920,quality=90,format=auto,metadata=none/https%3A%2F%2Fcms-assets.youmind.com%2Fmedia%2F1783879071532_p6yioz_HM62kqza8AAOydz.jpg)
