Zenn
🍣

Claude Code実践Tips集: 初級・中級・上級編

に公開
Tips
Claude Code
tech

はじめに

Claude Codeは、Anthropic社が提供する公式のAIコーディングアシスタントCLIツールです。ターミナル上でプロジェクトのコードを理解し、自然言語コマンドでコードの編集・検索・テスト実行・Git操作などを行ってくれます。本記事では、Claude Codeを初心者から上級者まで日常の開発ワークフローで使いこなすための実践的なTipsを紹介します。CLAUDE.md設定のベストプラクティスから、メモリ管理・コンテキスト制御のコツ、pre-commitフックを使った品質担保、自動化の手法、外部ツール連携（MCP）の最新情報や遊び心ある活用法、さらには失敗例とその回避策までカバーします。読者のスキルレベルに応じて初級・中級・上級編に分けていますので、自分の利用状況に合ったヒントを見つけてみてください。

初級者向けTips

Tip 1: CLAUDE.mdでプロジェクト情報を共有

Claude Codeにはメモリファイルとして機能するCLAUDE.mdがあります。これはプロジェクト固有の設定や知識を記載するMarkdownで、新しいセッション開始時に自動で読み込まれ、以降の対話のコンテキストに組み込まれます。プロジェクトのルートに置くのが一般的ですが、ホームディレクトリ（全プロジェクト共通）にも置けます。CLAUDE.mdには以下のような情報をまとめておくと効果的です。

  • 開発環境や使用技術: 例: 使用するNode.jsやPythonのバージョン、主要フレームワーク、テストツールなど。
  • コーディング規約: インデント幅、引用符の種類、セミコロンの有無などプロジェクトのコードスタイル規則。
  • よく使うコマンド: ビルドやテスト、デプロイ手順などのスクリプト名。

こうした情報を箇条書きで記載しておくと、Claudeはプロジェクトの前提を理解した上で動いてくれます。「テストを実行して」と指示すればnpm testを実行しようとする、といった具合です。特に出力してほしい言語やトーンもここで指定可能です（例：「ユーザー向けメッセージは日本語で出力すること」など）。新規プロジェクトでは/initコマンドを使うと基本情報を自動収集したCLAUDE.mdが生成されるので、それを叩き台にカスタマイズするとよいでしょう。

Tip 2: 明確な指示と行動ガイドを与える

Claude Codeに何かを頼む際は、できるだけ具体的かつ明示的に指示するのがコツです。曖昧なお願いより、期待する手順や成果物をはっきり伝えた方が成功率が大幅に上がります。例えば「バグを直して」ではなく「特定の関数Xで発生するNULL参照バグを修正し、ユニットテストを追加して」が望ましい指示になります。

また、Claudeに守ってほしい振る舞いや制約がある場合は、CLAUDE.mdに明示的な行動指示を書くことができます。重要事項には「IMPORTANT: ...」「YOU MUST ...」のように強調して書くと、モデルがより遵守しやすくなります。たとえば「IMPORTANT: セキュリティ上、パスワードはコード中にハードコーディングしないこと」のように書いておけば、そうしたミスを防ぎやすくなるでしょう。

Claudeが一度ミスをしたり好ましくない提案をした場合、その場で修正するだけでなく次回以降繰り返さない工夫も大切です。具体的には、「CLAUDE.mdを更新してこの種のミスを今後防止して」と依頼します。実際にモデル自身がCLAUDE.mdに追記案を示してくれるので、それを採用すれば次回から改善されます。このようにメモリを逐次アップデートすることで、自分好みのAIアシスタントに育てていくことができます。

Tip 3: コマンド実行権限の管理

Claude Codeは安全のため、ファイルの書き込みや外部コマンド実行などシステムに変更を及ぼす操作を行う際には常にユーザーの許可を求めてきます。これを適切に管理することで、効率と安全性のバランスを取ることができます。基本方針としては、読み取り系の無害な操作は自動許可し、破壊的な操作は逐一確認することです。Anthropicのエンジニアも「git statusやlsなどは毎回確認しなくてよいので自動許可、git commitやrmは必ず手動許可」といったルールで運用しています。

Claude Codeの権限許可設定画面。「Bash(npm run lint)」など特定のコマンドをAllowリストに登録すると、それらに対して確認プロンプトを省略できます。逆にrmやデプロイなど破壊的な操作は自動許可しないようにしましょう。

Claude Codeでは一度許可した操作を「Always allow（今後自動許可）」に設定することも可能です。設定ファイル（.claude/settings.json）を直接編集してAllowリストを追加することもできますし、セッション中に/permissionsコマンドで対話的に許可ルールを変更することもできます。例えばGitコミットはBash(git commit:*)でパターン許可する、といった細かな指定も可能です。

ただし自動許可の範囲は慎重に見極めてください。うっかり危険な操作まで許可すると想定外の変更を加えてしまう恐れがあります。実際にあるユーザーはgit add .を許可した結果、秘密情報を含むファイルまで一括でステージされそうになり、慌てて操作を止めたという事例があります。幸い履歴から機密情報を削除して事なきを得ましたが、最初からgit add .を自動許可しないのが賢明でしょう。このようにAllowリストは「必要最小限」に留め、基本は手動確認としておくことで、大事故を防げます。

Tip 4: 出力結果の確認と逐次実行

Claude Codeを使い始めたら、そのアウトプットを必ず人間がレビューする癖をつけましょう。Claudeは非常に高性能ですが、提案されたコードや変更を漫然と受け入れるのは危険です。新人エンジニアのコードレビューをするように、**「信頼しつつも全行チェック」**が鉄則です。特に大きな変更や自動修正を行った場合は、動作確認や差分確認を徹底しましょう。

また、一度に多くのことを頼みすぎないのもポイントです。Claudeは一度与えた指示に対して全力で応えようとしますが、複雑なタスクを一気に投げ込むと見落としや暴走のリスクが上がります。タスクは細かく分解し、逐次的に実行・確認するのがおすすめです。例えば、「この10個のLintエラーをすべて直して」ではなく、「まずはファイルAの2件のLintエラーを直して」という具合に小分けに依頼し、都度テストやLintを走らせて確認します。大きな修正が必要な場合は、Claudeにチェックリスト形式の作業計画を書かせ、それを順番に実行する方法も有効です。実際、Lintエラーが大量にある場合にClaudeにエラー一覧をMarkdownのチェックリストとして出力させ、一つずつ修正・チェックを繰り返すというワークフローが紹介されています。

対話が長くなってきてコンテキストが散漫になったら、/clearコマンドで会話履歴をクリアすることも検討しましょう。古い話題や不要なファイル内容がコンテキストに残ったままだと、モデルの応答が遅くなったり見当違いになることがあります。タスクごとにコンテキストをリセットし、今取り組んでいる内容に集中させることで、パフォーマンスと精度を維持できます。

中級者向けTips

Tip 5: コンテキストとメモリを上手に制御する

Claude Codeは非常に長い文脈も扱えますが（Claude 2なら最大100kトークン程度と言われます）、コンテキストは無限ではないため効率的に使う工夫が必要です。不要な情報でコンテキストを埋めないよう、セッション中は話題に関係ないファイルや会話履歴を適宜クリアする（前述の/clear活用）ことが有効です。

また、要約の活用もポイントです。大量のログや長大なコードをそのまま読ませるとコンテキストを圧迫します。そこで「このログを要約してポイントを抽出して」とClaudeに頼み、得られた要約をもとに分析を進めるといったテクニックが使えます。Claude自身に要約させることで、詳細は省きつつ本質的な情報だけをコンテキストに残せます。特に不具合調査では、エラーログ全文より「頻出するエラーメッセージとスタックトレースの要点」をまとめてもらうと効率が上がります。

Claude Codeのセッションをまたいで知識を持ち越したい場合は、CLAUDE.mdに学習内容を蓄積するようにしましょう。実行した解析結果や調査内容のサマリーをCLAUDE.mdに追記しておけば、次回セッション開始時にそれを読み込むことで過去の知見を再利用できます。たとえば「アーキテクチャ解析結果」「重要なモジュール一覧」等のセクションをCLAUDE.mdに設け、プロジェクトの構造やドメイン知識を簡潔に整理しておくと、新しいセッションでもすぐ概要を思い出させることができます。

大規模な既存プロジェクトでは、段階的に理解を深めるアプローチが有効です。いきなり全貌を理解させようとするのではなく、まずは「プロジェクトの全体構造を教えて」「主要なディレクトリとファイルの役割を説明して」と尋ねて大まかな構造を掴みます。次に「ユーザー認証部分のコードを見つけて説明して」のように特定の機能にフォーカスした質問を投げ、局所的な理解を進めます。必要な修正も「まずはauthディレクトリ配下のdeprecatedな関数を直す」→「影響範囲をClaudeに確認する」→「関連テストを実行して検証」…といった手順でスコープを限定しながら順次対応するのがおすすめです。このように範囲を絞って少しずつ進めることで、Claudeもコンテキストを把握しやすくなり、作業ミスが減ります。

Tip 6: テスト駆動と段階的な開発を取り入れる

AIと協調して開発する場合、テスト駆動開発（TDD）や段階的な検証プロセスが非常に効果的です。人間の開発者にとっても望ましい手法ですが、特にLLMであるClaudeにとっては格好の指標となります。LLMはゴールが明確だと軌道を外れにくいため、テストでゴールを示してからコードを書かせると非常にスムーズです。「ロボット（AI）達はTDDが大好きだ。本当に嬉々として取り組む」という開発者の声もあります。例えば、新機能を実装する前に「この関数のユニットテストを書いて」と依頼し、生成されたテスト（Failする状態）を確認します。その後「テストをパスするように実装して」とClaudeに促すと、テストを満たすコードを書くという明確な目標がある分、無駄な実装をせずに的確にコードを書いてくれることが多いです。

同様に、Lintやフォーマッタを組み合わせるのも効果的です。Claudeは人間以上に几帳面にLintエラーを修正してくれますし、スタイル統一のツール（Prettierや黒魔術的なClippyなど）も喜んで適用します。人間が設定した品質基準にAIが従う仕組みを整えることで、AIが暴走してもすぐ軌道修正される安全網になります。

さらに、Gitのpre-commitフックにテストやLintを組み込んでClaudeの行動をガードする方法も中級者にはおすすめです。例えば、コミット前に自動テスト・型チェック・Lintを走らせ、失敗したらコミットを拒否するようなフックを設定します。Claudeは指示されれば自動でコミットまで実行しますが、その際にフックのおかげでテストやLintに引っかかるとコミットがストップします。Claude自身も「コミットができなかった=コードに問題がある」と理解しますから、直ちにエラーを修正する流れになるわけです。実際に「Claudeはとにかくコミットしたがるので、フックで失敗させてあげると結果的にコードがA+++品質になる」という報告もあります。このように自動チェック環境を整備しておくと、Claudeといえども一発でマージできないので、何度か試行錯誤して最終的にテストをすべて通したコードをコミットするようになります。結果として、人間の手を煩わせずに品質が担保できるのです。

Tip 7: Claude Codeを開発ライフサイクル全体に活用

Claude Codeの能力はコードを書くことだけに留まりません。ソフトウェア開発ライフサイクル全般で役立つ多才なアシスタントとして活用しましょう。具体的には以下のようなシーンで活躍します。

  • ドキュメントやコメントのアップデート: 開発者が後回しにしがちなドキュメント整備も、Claudeに頼めば素早く更新してくれます。「コード変更に合わせてREADMEを最新化して」や「この関数にわかりやすいコメントを付けて」といった依頼もお手の物です。
  • 包括的なテストの作成: 普段なら省略しがちなエッジケースも含め、Claudeは網羅的なユニットテストや統合テストを書いてくれます。「このクラスの全メソッドについて、境界値も考慮したテストを書いて」とお願いすれば、人力では大変な量のテストコードを生成してくれるでしょう。
  • コードレビューとリファクタリング提案: Claudeは単なる静的解析以上の「セマンティックなコードレビュー」が可能です。例えば「この差分をレビューして改善点を指摘して」と頼むと、タイポや不要なコメント、名前の不適切さ、パフォーマンス上の懸念まで含めて指摘してくれることがあります。指摘事項をそのまま修正させることも可能です。
  • コミットメッセージ・PR説明文の自動生成: Claudeはプロジェクト全体の変更を把握しているので、コミットメッセージやプルリク説明も驚くほど丁寧に書き上げます。実際、あるユーザーは「Claudeの書くコミットメッセージは自分よりも詳細で的確だ」と述べています。人間だと漏らしがちな変更点もClaudeはすべて覚えているためです。チーム開発において、このような質の高いコミットメッセージは後々のリファクタやデバッグで大きな助けとなります。
  • 設計図やビジュアルの生成: Claudeはテキストだけでなく簡単な図式も扱えます。例えば「このクラス関係をGraphViz (DOT言語)で図示して」と頼むと、設計ドキュメント用のクラス図やフローチャートを生成してくれます。さらに、そのDOTファイルからPNG画像を生成するシェルスクリプトを書かせ、自動的にドキュメントに埋め込む…といった芸当も可能です。テキストベースのCLIでありながら、画像や図表まで含めたドキュメンテーション支援ができる点は見逃せません。

このように、Claude Codeを開発のあらゆる場面で活用することで生産性が大きく向上します。コード執筆→テスト→ドキュメンテーション→レビュー→リリースノート作成まで、Claudeに任せられる部分はどんどん任せ、人間は最終チェックや創造的な設計・判断に注力するのが理想です。

Tip 8: カスタムコマンドとワークフローの共有

Claude Codeにはスラッシュコマンドによるカスタム機能拡張が用意されています。デフォルトでも/commitや/editなど色々なコマンドがありますが、独自のシナリオに合わせてオリジナルのコマンドを作成できます。やり方はシンプルで、プロンプトテンプレートをMarkdownファイルとして .claude/commands/ ディレクトリに配置するだけです。ファイル名がそのままコマンド名になり、/を押すと補完リストに表示されるようになります。さらにテンプレート内で特殊変数$ARGUMENTSを使えば、コマンド呼び出し時に引数を渡すことも可能です。

例えば、GitHubのIssueを自動で取得して修正まで行うコマンドを作ることもできます。Anthropicの例では、以下のような問題修正用コマンドが紹介されています。

Please analyze and fix the GitHub issue: $ARGUMENTS.

Follow these steps:
1. Use `gh issue view` to get the issue details
2. Understand the problem...
3. Search the codebase for relevant files
4. Implement changes...
5. Run tests to verify the fix
6. Ensure code passes linting
7. Create a descriptive commit message
8. Push and create a PR

このMarkdownを .claude/commands/fix-github-issue.md として保存すれば、以降Claude上で /project:fix-github-issue 1234 のように入力するだけでIssue #1234に対する上記手順を自動で実行してくれるようになります。テンプレートはプロジェクト内に共有できるので、チームで共通のコマンドを使って統一的なワークフローを実現できます。

CLAUDE.mdについても同様で、チーム全体で育てていくことが可能です。Claude.mdをGit管理しておけば、プロジェクトのスタイルガイド・設計指針・禁止事項などを全員が共有できますし、新メンバーへのオンボーディング資料としても役立ちます。実際にオープンソースで高度なCLAUDE.mdを公開している例もあります。ある開発者はCLAUDE.mdにユニークなルールとして、自分を「Mr. Beef」というニックネームで参照する記述を入れています（ドキュメント生成時に「困ったらMr. Beefに相談せよ」という遊び文言が出てくるとのこと）。このようにユーモアを交えつつ、Claude.md上でプロジェクト文化を表現しているケースもあります。

なお、セッション中に「このルールを覚えてほしい」と思ったら、#から始まる入力でそのままメモリに追記できます。例えば対話中に# APIのベースURLは環境変数から取得することと送ると、CLAUDE.mdにその一行が追加されます。/memoryコマンドでCLAUDE.md自体をエディタで開いて編集することも可能です。こうした機能を使いこなし、Claudeにその場で新しい知識やルールを学習させることで、回を追うごとによりプロジェクトに最適化されたアシスタントになっていきます。

上級者向けTips

Tip 9: ヘッドレスモードと自動化活用 (CIへの統合)

Claude Codeは対話的に使うだけでなく、スクリプトやCI環境から**非対話的に呼び出す「ヘッドレスモード」**も備えています。claude -p "＜プロンプト＞"のように-pオプションでプロンプトを直接渡せば、対話なしで一度きりの応答を得ることができます。さらに--output-formatでstream-jsonやmessages-jsonを指定すれば、JSON形式でステップごとの結果を受け取ることも可能です。このモードを利用すれば、CIパイプラインやバッチ処理の中にClaude Codeを組み込むことができます。

具体的な活用例としては、以下のようなものが考えられます。

  • プリコミットフックでのコードチェック: コミット時にclaude -p "Staged changesをレビューしてバグやスタイル違反がないかチェックして"といったコマンドを走らせ、Claudeからの指摘内容によってコミットを中断したり、あるいは警告を表示するといった使い方です。上級者の中には、Claudeをリントのように使い「明らかな問題があればコミットさせない」という運用を試している人もいます。Claude Code自身にも組み込みのLinter機能（コードの主観的なレビューを行うもの）があり、変数名のミスやコメントの不備なども検出できます。

  • Issueの自動トリアージ: GitHubのIssueやPull Requestに対して、自動でClaudeに内容を要約させたりタグ付けさせたりすることも可能です。例えば新規Issueが投稿された時にトリガーして、「バグ報告か機能要望かを判断してラベルを提案して」とヘッドレス実行すれば、ラベル付けの手間が省けます。実際、Claude Codeの公開リポジトリでは、新しいIssueが来るとClaudeが内容を読んで適切なラベルを付与する自動化を導入しています。

  • 自動コード修正・リファクタリング: CI上で定期的にClaudeにプロジェクト全体を点検させ、「依存ライブラリのバージョンアップに追従する修正」や「非推奨APIの一括置換」などを行わせることも考えられます。これを実用するには十分な検証が必要ですが、成功すれば人手では大変な大規模リファクタリングを夜間バッチでAIに片付けさせる、といった夢も広がります。

ヘッドレスモードはセッション間のメモリを引き継がない点に注意してください。毎回新しいセッションとして実行されるため、CLAUDE.mdや必要なコンテキストは都度読み込ませる必要があります。claude -pを使うスクリプト内で"CLAUDE.mdの内容を読込済みと仮定して..."とプロンプトするか、あるいはCLAUDE.mdを分割して必要部分を@import機能で読み込む（CLAUDE.md内で他のファイルを@パス指定するとインポートされます）のも手です。セッションが毎回リセットされることを逆に利用して、並列に複数のClaudeを動かすこともできます（後述のマルチClaude活用）。いずれにせよ、ヘッドレス実行時には--verboseオプションを付けてデバッグしながら設定すると良いでしょう。

Tip 10: 外部MCPサーバーで機能拡張

Claude Codeは標準でローカルのシェル環境やGitコマンド等を扱えますが、それ以上に様々な外部ツールと連携可能なのが強みです。その鍵となるのが**MCP（Model Context Protocol）**による拡張機能です。Claude Code自身がMCPクライアントおよびMCPサーバーの役割を果たし、外部サービスを「ツール」として利用できます。

Remote MCPを活用すると、例えばブラウザ操作やクラウドサービスとの連携といった高度なタスクもClaudeに任せられます。Anthropicのドキュメントによれば、.mcp.json設定ファイルに接続したいMCPサーバーを追記するだけで、Claudeがそれらのツールを使えるようになります。例として、ヘッドレスブラウザ操作のためのPuppeteerサーバーや、エラーログ取得のためのSentryサーバーを追加し、全エンジニアが使える共有ツールにしているケースが紹介されています。設定後は、あたかもローカルコマンドのようにPuppeteer.navigate URLやSentry.getErrorsといった操作をClaudeが実行できるようになります。

MCPサーバーはコミュニティでも活発に開発・公開されています。例えばmacOSの読み上げ機能（sayコマンド）を使ってClaudeに音声発話させる「Say MCPサーバー」があります。これを組み込めば、Claudeに「テスト結果を読み上げて」と頼むとMacの声で結果を喋ってくれる、といったユニークな使い方も可能です。その他にも、Slackメッセージ送信やJiraチケット作成、データベースクエリ実行、果ては別のAIモデルとの連携まで、世界中の開発者が様々なMCPプラグインを公開しています。Glama.aiなどのサイトでは数千を超えるMCPサーバーがリストアップされており、目的に合うものを探して導入できます。

外部ツールを使う際は、まずそのMCPサーバーをローカルまたはリモートで起動し、Claude Code側を適切に設定します。先述の.mcp.jsonに"サーバー名": { "command": "...", "args": [...] }の形で登録し、claudeコマンド起動時にオプションで有効化（または常時有効化）する形です。設定に不備があるとツールが動かないので、その際は--mcp-debugフラグを付けて起動しデバッグ情報を確認します。正しく接続できれば、後は通常の対話で「ブラウザで○○を開いて内容を取得して」と日本語で頼むだけで、Claudeが裏でMCP経由のブラウザ操作ツールを呼び出して結果を返す…というように動いてくれます。

MCP連携は上級者向けの機能ですが、使いこなせばClaude Codeの可能性は飛躍的に広がります。自動テストでスクリーンショットを撮ったり、インシデント発生時にログを調べたり、他のAIと協調動作させたりと、「CLI上で動くエージェント」に様々なスーパーパワーを付与できるのです。

Tip 11: 大規模プロジェクトへの対処とArchitectモード

コードベースが大きくなるほど、Claude Codeに全てを理解させるのは時間がかかります。例えば数十万行規模のプロジェクト全体を解析させようとすると、場合によっては3～6時間以上を要するという報告もあります（Claude 2の100kトークンコンテキストをもってしても、一度に読み込めるのはその程度が限界です）。そこで大規模プロジェクトでは戦略的なアプローチが必要です。

  1. 知識の事前集約: すでに述べたように、重要な構造や設定はCLAUDE.mdに整理しておきます。ファイルの索引や主要クラス・関数の一覧、アーキテクチャの概要などを前もって記載しておくと、Claudeはまずそれを参照してから不足部分のみコードを読むようになります。これにより無駄な全コード走査を避けられます。特に「認証周り」「データベース設定」などカテゴリーごとに要点をまとめておき、再調査時はそれを参照するよう依頼すると効率的です（例: 「CLAUDE.mdの認証関連ファイルリストを参照してJWT検証ロジックを確認して」）。Claudeにとっては人間が渡す短い要約でも貴重な知識源なので、積極的に与えていきましょう。

  2. 差分・部分的な解析: 全体を一度になめるのではなく、変更差分や特定範囲に絞って解析させます。例えば「直近3つのコミットで変更されたファイルだけ調べて互換性問題がないか確認して」や「昨日以降に失敗したテストだけ特定して原因を分析して」といったプロンプトを使えば、不要な範囲に時間を割かずに済みます。ClaudeはGitも扱えるので、git diffやgit logを組み合わせて狭い対象で深く解析させると効率的です。逆に「全ファイルをゼロから解析して」は避けましょう。

  3. 並列処理や分割統治: 上級者になると、Claude Codeを複数並行で走らせて役割分担させるテクニックもあります。Anthropic社内でも、一人のエンジニアが複数の端末で別々のClaudeセッションを開き、それぞれに異なるタスクを与えて同時進行させるという使い方がされています。例えば、ターミナルAではClaudeにバックエンドのリファクタリングをさせ、ターミナルBでは別のClaudeにフロントエンドの新機能実装をさせる、といった具合です。Gitのブランチやワークツリーを活用すれば、同じリポジトリで複数の作業を衝突なく進められます。こうして並列化すれば時間短縮になりますし、互いに結果をレビューさせ合う（Claude同士でクロスレビューさせる）ことも可能です。

  4. Architectモードの活用: Claude Codeにはこっそり存在する**--enable-architectオプション**があります。公式にはあまり説明されていませんが、これを有効にするとClaudeに「Architect（設計者）」ツールが追加され、大規模なリファクタリングや設計変更タスクでのプランニング能力が向上します。実際に試したユーザーからは「大きな変更の際、事前にClaude自身が高レベルな計画を立ててくれるようになり効果を感じた」との声があります。大掛かりな改修に取り組む場合は、このモードも検討してみてください。モデルがあらかじめ設計図を書いてくれるイメージで、タスクを小分けにして遂行してくれるかもしれません。

いずれにせよ、大規模プロジェクトでClaude Codeを使う際は**「全てを一度に」は避け、「必要な知識を与え、小さな範囲から攻める」**のが鉄則です。そして得られた解析結果はきちんと蓄積し、次に生かす。これを徹底すれば、Claudeも徐々にプロジェクトを深く理解し、まるで長年従事してきたチームメンバーのように振る舞ってくれるでしょう。

Tip 12: よくある失敗例と回避策

最後に、Claude Codeのありがちな失敗パターンとその対処法をまとめます。上手に使いこなすには、躓きがちなポイントを事前に知っておくことも重要です。

  • CLAUDE.mdが読み込まれていない: 稀に、新しいセッションを開始したときClaudeがCLAUDE.mdを自動で読まないことがあります。特にClaude Code自体のアップデート直後などに挙動にばらつきが報告されています。そのため、「あれ、プロジェクトルールを無視した答えを返してきたぞ？」という場合は明示的にCLAUDE.mdを読ませるのが確実です。具体的には冒頭で「CLAUDE.mdを読んで、このプロジェクトの設定を理解してください」と一言伝えるだけでOKです。そうすればCLAUDE.md内の規約や知識がコンテキストに入り、以降の応答品質が改善します。将来的なバージョンでこの問題は改善する可能性がありますが、重要なセッションでは最初に手動で読み込み指示をする習慣をつけると安全です。

  • 自動承認モードでの暴走: Shift+Tabで手動承認をオフにする「Auto-accept（自動許可）モード」にすると、Claudeが人間の確認なしにどんどん処理を進めます。便利な反面、誤った変更を大量に適用してしまうリスクもあります。特に初めのうちはAuto-acceptは多用せず、逐一内容を確認しながら進める方が無難です。慣れてきてから、テスト付きで小さな変更を繰り返すような「安全な状況下」でのみ自動化する、といった使い分けをおすすめします。「YOLOモード」（何でも実行させるモード）との呼び名もありますが、文字通り You Only Live Once な危険を伴うので注意してください。

  • 機密情報の扱い: Claude Codeはプロジェクト内のファイルを自由に閲覧・編集できますが、逆に言えばアクセスできる範囲を適切に制限しないと秘密情報に触れる恐れがあります。例えば誤ってリポジトリ外のファイルパスを指定すると、そこにある環境設定ファイルやSSH鍵などを読みに行ってしまう可能性もあります（初期設定では都度許可が必要なので即漏洩はしませんが）。プロジェクトディレクトリ以外には基本触らせない、機密情報はモックやダミーデータに置き換えておく、などの対策を講じましょう。また万一誤って機密データがGitにコミットされた場合、その削除（履歴からの除去）は非常に手間です。そもそもそうしたファイルをコミットしないようClaude.mdに「重要機密ファイルは編集・コミット禁止」と記載しておくのも有効です。

  • 誤った前提に基づく回答: Claudeは与えられた情報に忠実ですが、ときに勘違いして存在しない関数名やクラス名を引用してしまう（いわゆる幻覚）ことがあります。大抵はプロジェクト内検索ですぐ判明するので、見つけたら遠慮なく「その関数Xは存在しません」とフィードバックしてください。Claudeは謝って修正します。また再発防止のため、そうした学習事項をCLAUDE.mdに追記するのも良いでしょう。「関数Xは存在しない」あるいは「モジュールYで提供されるAPIのみ使用すること」といった戒めを書き込んでおけば、次からは避けられます。

  • セッション切り替え時の混乱: Claude Codeはセッション（対話）ごとにコンテキストをリセットします。したがって、あるセッションで途中まで作業したあと一度終了し、次の日に続きを始める場合は前回の内容を思い出させるプロンプトが必要です。Tip 5で述べたようにCLAUDE.mdに作業履歴や要点を記録しておき、新セッションの冒頭で「前回の解析結果を踏まえて作業を続行して」と指示すればスムーズです。逆に何も引き継がないと、Claudeは過去の対話ログを覚えていないため一から説明し直す羽目になります。面倒に思うかもしれませんが、その日の終わりに進捗や発見を書き留めておき、再開時に読み込ませるという運用に慣れると、長期間にわたるタスクでも問題なくClaudeを活用できるでしょう。

以上、失敗例と対策を挙げましたが、総じて言えるのは**「Claude Codeをチームの有能な新人開発者だと思って扱う」**ことです。適切に教え、権限をコントロールし、レビューを怠らなければ、Claudeは驚くほど生産的な成果を上げてくれます。逆に放任すればバグやヒューマンエラー（AIエラー？）も起こり得ます。そのバランス感覚を持って臨むのが上級者への近道と言えるでしょう。

おわりに

Claude Codeは革新的な開発支援ツールであり、正しく使えば「自分専属の超高速ペアプログラマ」を手に入れたような体験ができます。最初は学習コストもありますが、慣れてくると「もう従来のやり方には戻れない」と感じる開発者も多いようです。本記事で紹介したTipsを参考に、ぜひClaude Codeのポテンシャルを引き出してみてください。プロジェクト設定を整え、明確な指示を与え、安全管理をしつつ、テストや自動化を駆使する。最初は戸惑うかもしれませんが、Claudeとの共同作業に慣れれば、反復的な雑務から解放され創造的な部分に集中できるようになります。そして何より、AIと対話しながらものづくりをするプロセスは純粋に楽しい体験でもあります。Claude Codeを相棒に、日々の開発をアップデートしていきましょう！

Discussion