Claude Codeベストプラクティス9選｜効果の大きい順に紹介

Claude Codeのベストプラクティスを効果の大きい順に9つへ絞って解説。すべての土台であるコンテキストウィンドウ管理を軸に、CLAUDE.mdの書き方・セッション管理・パーミッション・Hooks/Skillsの使い分けを具体的な設定例と段階別ロードマップで示します。

Claude Codeの精度を安定させる最大の要因は、コンテキストウィンドウの管理です。使う機能の数でも、プロンプトの巧みさでもありません。

Anthropicの公式ベストプラクティスドキュメントは網羅的で信頼できますが、リファレンスとして書かれているため分量が多く、「結局まず何からやればいいのか」には答えていません。（参考: https://code.claude.com/docs/ja/best-practices）

本記事では、Claude Codeのベストプラクティスを効果の大きい順に9つへ絞り、具体的な設定例と段階別ロードマップで示します。個人開発者から小規模チームが、今日から順番に実践できる形にまとめました。

Claude Codeは、ターミナルやVS Codeから使えるAnthropic公式のAIコーディングエージェントです。ツール自体の概要を先に押さえたい場合は、Claude Codeとは何かを解説した記事を参照してください。

Claude Codeのベストプラクティスは何から始めるべき？｜効果の大きい順に9つ

Claude Codeのベストプラクティスで最優先すべきは、①検証手段を与える、②CLAUDE.mdを簡潔に保つ、③タスクの区切りで/clearする、の3つです。この3つだけで出力の安定度は大きく変わります。

残りの6つは、上位3つが習慣として回り始めてから着手すれば十分です。以下の一覧表は、効果・導入コスト・着手時期の3軸で9つのプラクティスを整理したものです。

#プラクティス効果導入コストいつやるか
1検証手段を与える大中初日
2CLAUDE.mdを簡潔に整える大低初日
3/clearでセッションを切る大低初日
4プロンプトに具体的コンテキストを与える大低初日
5探索→計画→実装→コミット中〜大低慣れてきたら
6パーミッションを設計する中低慣れてきたら
7サブエージェントに調査を委譲中中慣れてきたら
8Hooks／Skillsで拡張を使い分ける中高チーム運用
9非対話モード・並列で自動化中高チーム運用

この表は上から順に読めば問題ありません。下位の項目は、上位の項目が日常の運用として回り始めてから着手してください。

順番を守る理由は単純です。1〜4は設定コストがほとんどかからないのに効果が大きく、8〜9は設定コストが高いうえに、1〜4が欠けたままでは効果が出ないためです。

なぜ「効果の大きい順」で考える必要があるのか

Claude Codeの機能は多いものの、すべてを同時に導入すると設定自体がコンテキストを圧迫し、かえって精度が落ちるためです。機能を増やすことと精度が上がることは、Claude Codeにおいて比例しません。

たとえばMCPサーバーを多数接続すると、ツール定義そのものが毎回のコンテキストを消費します。CLAUDE.mdに独自ルールを詰め込みすぎた場合も同様で、重要な指示が長文のなかに埋もれて無視されます。

公式ベストプラクティスドキュメントが優先順位を明示していないのは、品質の問題ではなく役割の違いによるものです。公式ドキュメントは「何ができるか」を漏れなく示すリファレンスであり、「どの順で手をつけるか」は読者の環境ごとに変わるため、あえて規定していません。（参考: https://code.claude.com/docs/ja/best-practices）

そこで本記事は、個人開発者から小規模チームという読者を固定したうえで、実践の順序を明示します。順序を決めることが、公式ドキュメントを読み切れない人にとって最も価値のある情報だからです。

大原則｜すべての土台は「コンテキストウィンドウの管理」

コンテキストウィンドウとは、Claudeが一度に保持できる情報量の上限です。公式ベストプラクティスドキュメントはコンテキストウィンドウを最も重要なリソースと位置づけており、以降の9つのプラクティスはすべて、この上限を無駄遣いしないための手段だと理解すると筋が通ります。（参考: https://code.claude.com/docs/ja/best-practices）

コンテキストウィンドウには、CLAUDE.mdの内容、読み込んだファイル、これまでの会話履歴、ツールの実行結果がすべて入ります。作業を続けるほど、この領域は自動的に埋まっていきます。

コンテキストウィンドウが満杯になると何が起きるのか

コンテキストウィンドウが満杯に近づくと、Claude Codeの出力精度は明確に劣化します。原因は3つあり、いずれもコンテキストの構造から必然的に生じます。

  • 古い情報が押し出される — セッション序盤に伝えた前提や制約が保持範囲から外れる
  • 指示が埋もれる — 大量のログやファイル内容に紛れ、重要な指示の相対的な比重が下がる
  • 要約で情報が欠落する — 履歴の圧縮時に、細かい決定事項や例外条件が落ちる

コンテキストウィンドウは無限のメモリではなく、有限の作業机です。机の上に資料を積み上げ続ければ、今すぐ必要な1枚が見つからなくなります。

「Claude Codeは最初は賢いのに、作業が長引くと急に的外れになる」という体感は、能力の変動ではなく机が埋まった結果です。したがって対処法は、能力を引き出す魔法のプロンプトではなく、机を片付ける運用になります。

9つのプラクティスは、この原則のどこに効くのか

9つのプラクティスは、コンテキストの「消費を減らす」「汚染を防ぐ」「無駄な往復をなくす」の3方向に分類できます。以降の各セクションでは、そのプラクティスがどの方向に効くかを毎回明示します。

  • 消費を減らす — CLAUDE.mdの簡潔化、具体的なプロンプト、MCPの絞り込み
  • 汚染を防ぐ — /clearによるセッション分割、サブエージェントへの調査委譲
  • 往復をなくす — 検証手段の用意、計画フェーズの合意、Hooksによる自動実行

この分類を頭に置いて読み進めると、個々のテクニックが単なる小技ではなく、1つの原理から派生した対策であると分かります。原理を理解していれば、本記事に書かれていない場面でも自分で判断できます。

【最優先1】検証手段を与える｜Claudeに証拠を出させる

Claude Codeのベストプラクティスで最も効果が大きいのは、Claudeが自分で回せるチェック手段を用意することです。テスト・ビルド・リンターがあると、Claudeは推測ではなく実行結果を根拠に自己修正します。

公式ベストプラクティスドキュメントも、検証手段の提供を重要項目として挙げています。（参考: https://code.claude.com/docs/ja/best-practices）

なぜ検証手段がコンテキスト管理に効くのか

検証手段がないと、Claudeは「たぶん動くコード」を出し、人間がエラーを貼り付けて修正を指示する往復が発生します。この往復こそが、コンテキストを最も速く浪費する行為です。

エラーの貼り付けと修正を5往復すれば、その分だけ会話履歴が膨らみます。履歴が膨らめば序盤の前提が押し出され、Claudeは当初の要件を忘れた修正を出し始めます。

検証手段を渡した場合、この往復はClaude Codeの内部で完結します。人間が受け取るのは「テストが通った最終形」だけになり、会話履歴の消費は劇的に減ります。

検証コマンドをCLAUDE.mdに明記する

検証手段を与える最短の方法は、プロジェクトで使う検証コマンドをCLAUDE.mdに正確に書くことです。Claudeがコマンドを推測しなくて済むよう、実際に動く形で記述します。

## Commands

- テスト: `npm test`
- 単一ファイルのテスト: `npm test -- path/to/file.test.ts`
- リント: `npm run lint`（自動修正は `npm run lint:fix`）
- 型チェック: `npm run typecheck`
- ビルド: `npm run build`

## Validation Rule

コードを変更したら、必ず `npm run lint` と `npm test` を実行し、
結果の出力とともに完了を報告する。失敗した場合は自分で修正して再実行する。

ポイントは、コマンドを列挙するだけでなく「変更したら必ず実行して結果を示す」という運用ルールまで書くことです。コマンドの存在を知っていても、実行を指示されなければClaudeは省略する場合があります。

単一ファイルのテストコマンドを併記しておくと、Claudeは変更範囲に応じて軽い検証を選べます。フルテストが数分かかるプロジェクトでは、この一行が待ち時間を大きく減らします。

UI変更はスクリーンショットで視覚的に検証させる

UIの変更では、テストの合否だけでは正しさを判断できないため、スクリーンショットを撮らせて視覚的に検証させます。Claude Codeは画像を読み取れるため、実際の描画結果を根拠に自己修正できます。

# プロンプト例
ヘッダーのレイアウトを修正したら、Playwright で
http://localhost:3000 のスクリーンショットを撮り、
撮った画像を読み込んで、ロゴとナビゲーションが
縦位置で揃っているかを自分で確認して。
ずれていたら修正して、再度撮影して確認する。

「撮る」だけでなく「撮った画像を読み込んで確認する」まで指示するのが要点です。撮影だけを指示すると、Claudeは画像を確認せずに完了報告する場合があります。

プロンプトのBefore／After

検証を促すプロンプトは、完了条件を明示する形に書き換えるだけで効果が出ます。以下は同じ依頼をBefore／Afterで示した例です。

# Before（検証が回らない）
ユーザー登録のバリデーションを実装して。

# After（証拠を出させる）
ユーザー登録のバリデーションを実装して。
実装後に `npm test` を実行し、
全テストが通ったことを実行結果とともに示して。
テストが落ちたら、落ちた原因を説明したうえで修正して再実行する。

Afterのプロンプトは、完了の定義を「実装した」から「テストが通った」へ移しています。完了条件を機械的に判定できる形にすることが、自己修正を働かせる条件です。

やりすぎない線引き

小さなtypo修正にまでフルテストを回させる必要はありません。検証コストが編集コストを明らかに上回る場面では、検証を省く判断が正しくなります。

目安として、コメントの修正・ドキュメントの文言変更・変数名の単純な置換では、リンターだけで十分です。ロジックに触れた場合はテストを回す、と切り分けておくと迷いません。

【最優先2】CLAUDE.mdの書き方｜簡潔さが精度を決める

CLAUDE.mdとは、Claude Codeが起動時に必ず読むプロジェクトのルールファイルです。最大のコツは網羅ではなく簡潔さであり、公式ベストプラクティスドキュメントも簡潔に保つことを明確に推奨しています。（参考: https://code.claude.com/docs/ja/best-practices）

CLAUDE.mdはセッションのたびに読み込まれる固定費です。1回だけ支払うコストではなく、全セッションで繰り返し支払うコストである点が重要になります。

CLAUDE.mdが肥大化すると、重要な指示が長文のなかに埋もれて無視されます。「ルールを書いたのに守られない」という現象の多くは、Claudeの怠慢ではなくCLAUDE.mdの分量が原因です。

/initで雛形を作り、そこから削る

CLAUDE.mdは/initコマンドで雛形を自動生成し、あとは足すのではなく削る運用にします。ゼロから書き始めるより速く、かつ削る前提で臨めるためです。

/initを実行すると、Claude Codeがプロジェクトを解析し、技術スタックや主要コマンドを含むCLAUDE.mdを生成します。生成された内容はあくまで下書きであり、そのまま運用すると冗長になります。

生成直後に、コードを読めば分かる説明を削ってください。ディレクトリ構成の羅列や、一般的なフレームワークの説明は削除対象の典型です。

CLAUDE.mdに書くべきこと・書かないこと

CLAUDE.mdに書くべきは「Claudeが知らないと間違えること」だけです。コードを読めば分かることは書きません。

書くべき書かない
ビルド・テスト・リントの正確なコマンドREADMEに書いてある一般的な説明
独自の命名規則・禁止パターン言語の一般的な作法
技術スタックと主要ライブラリ全ディレクトリ構成の羅列
コミット・PRの規約変わりやすい詳細仕様

判断に迷ったときの基準は、公式ベストプラクティスドキュメントが示す問いが有効です。「この行を消したら、Claudeが間違えるか？」と自問し、間違えないなら削ります。（参考: https://code.claude.com/docs/ja/best-practices）

この基準が優れているのは、迷いを機械的に解消できる点です。「あったほうが親切かもしれない」という感覚で判断すると、CLAUDE.mdは必ず膨らみます。

以下は、Project Overview / Tech Stack / Commands / Conventions / Git Rules の5構成でまとめた記述例です。個人開発であれば、この骨格で十分に機能します。

# CLAUDE.md

## Project Overview

社内向けの請求管理ツール。請求書の作成・承認・PDF出力を行う。
承認フローは 2 段階（作成者 → 経理）で、経理の承認前は PDF を発行しない。

## Tech Stack

- Next.js (App Router) / TypeScript
- DB: PostgreSQL + Prisma
- 認証: Auth.js（セッションは JWT ではなく DB セッション）
- テスト: Vitest

## Commands

- 開発サーバー: `npm run dev`
- テスト: `npm test`
- リント: `npm run lint`
- 型チェック: `npm run typecheck`
- マイグレーション: `npx prisma migrate dev`

## Conventions

- API のレスポンスは必ず `src/lib/api-response.ts` の `ok()` / `fail()` を通す
- 金額は number を使わず、必ず Decimal 型で扱う（丸め誤差の事故があったため）
- コンポーネントは `src/components/` にコロケーションしない。機能単位で `src/features/` に置く
- `any` の使用は禁止。型が不明な場合は `unknown` で受けて絞り込む

## Git Rules

- コミットメッセージは Conventional Commits に従う（例: `fix: 請求書PDFの日付ずれを修正`）
- main への直接コミットは禁止。必ずブランチを切る
- 指示がない限り、こちらからコミットやプッシュは実行しない

## Validation

コードを変更したら `npm run lint` と `npm test` を実行し、結果とともに報告する。

Conventionsの各行に注目してください。「金額はDecimal型」のように、コードを読んだだけでは判断できず、かつ間違えると事故になるルールだけが書かれています。

逆に「関数には適切な名前をつける」のような一般論は書きません。Claudeは一般的な作法をすでに知っており、書けば分量だけが増えます。

CLAUDE.mdはどこに置くのが正解？｜配置場所と階層読み込み

共有ルールはプロジェクト直下の./CLAUDE.md、個人設定は~/.claude/CLAUDE.md、コミットしたくない内容は./CLAUDE.local.mdに分けます。役割で置き場所を分けると、チーム共有と個人の好みが衝突しません。

  • ./CLAUDE.md — プロジェクト共通ルール。リポジトリにコミットしてチームで共有する
  • ~/.claude/CLAUDE.md — 全プロジェクト共通の個人設定。返答は日本語、などの好み
  • ./CLAUDE.local.md — 個人のローカル事情。gitignoreに追加して共有しない
  • サブディレクトリのCLAUDE.md — 特定領域だけの追加ルール

階層読み込みの挙動には、知っておくと事故を防げる特性があります。親ディレクトリのCLAUDE.mdは起動時に読み込まれる一方、子ディレクトリのCLAUDE.mdは、そのディレクトリのファイルに触れたタイミングでオンデマンドに読み込まれます。

注意すべきは、/compactで履歴を圧縮した後、ネストされたCLAUDE.mdが自動で再注入されるとは限らない点です。長時間セッションの途中から子ディレクトリのルールが効かなくなる現象は、この挙動が原因である場合があります。

対処は単純で、重要なルールが効いていないと感じたら/clearでセッションを切り直します。切り直せばCLAUDE.mdは最初から読み込まれます。

なお、@importで別ファイルを読み込む書き方は、ファイルを分割できるだけでコンテキストの節約にはなりません。読み込まれた内容は結局コンテキストに載るため、分量を減らしたい場合は分割ではなく削除が必要です。

分量の目安については、公式ベストプラクティスドキュメントが具体的な行数を定めているわけではありません。一つの目安として200行以下に収める運用が実務でよく採られますが、行数そのものより「この行を消したらClaudeが間違えるか」という基準で判断するほうが確実です。

やりすぎない線引きとして、個人開発でディレクトリごとにCLAUDE.mdを分けるのは過剰です。まず1枚で始め、明確に領域が分かれて内容が衝突し始めてから分割してください。

CLAUDE.md以外の設定項目もあわせて整えたい場合は、Claude Codeの設定おすすめ9選で、精度とコストを両立させる設定を解説しています。

【最優先3】セッション管理｜/clearと/compactの使い分け

無関係なタスクに移るときは/clear、同じタスクを続けたいが履歴が長いときは/compactです。この使い分けが、長時間作業での精度低下を防ぎます。

/clearは会話履歴を破棄してセッションを初期化するコマンドで、/compactは履歴を要約して圧縮するコマンドです。前者は文脈を捨て、後者は文脈を残す点が決定的に違います。

/clearはいつ実行する？

/clearの実行タイミングは、タスクが1つ完了した時点と、同じ問題の修正に2回失敗した時点の2つです。この2つを機械的に守るだけで、精度低下の大半を防げます。

タスク完了時に/clearする理由は、完了したタスクの履歴が次のタスクにとって純粋なノイズだからです。認証機能の実装履歴は、次に着手するCSS修正の精度を1ミリも上げません。

避けるべき典型が「キッチンシンクセッション」です。キッチンシンクセッションとは、1つの会話に無関係な話題を次々と詰め込み、認証・スタイル・デプロイ設定などが混在した状態を指します。

キッチンシンクセッションでは、Claudeが直前の別話題の文脈を引きずり、見当違いのファイルを編集し始めます。会話を分けるコストはコマンド1つであり、精度低下を我慢する理由はありません。

2回失敗したら/clearする理由は、失敗した修正案が履歴に残ると、Claudeが同じ方向の修正を繰り返すためです。履歴を捨て、失敗から学んだ事実を要件に含めた新しいプロンプトで再開してください。

/compactは指示付きで使う

/compactは引数なしで使わず、残したい情報を指定して実行します。引数なしの圧縮では、Claudeが何を重要と判断するかが不安定になるためです。

# 悪い例（何が残るか制御できない）
/compact

# 良い例（残す情報を指定する）
/compact 認証まわりで決めた仕様（DBセッション採用・有効期限7日）と、
残タスク（ログアウト処理とテスト追加）を必ず残して。
デバッグ中に読んだファイルの内容は捨ててよい。

指示のポイントは、残すものと捨てるものを両方書くことです。捨ててよい対象を明示すると、圧縮率が上がり、その後の作業に使えるコンテキストが増えます。

失敗を巻き戻す｜Esc・Esc2回・/rewind

Claude Codeが意図しない方向へ進み始めたらEscで即中断し、加えられた変更を取り消したい場合はEscを2回押すか/rewindでチェックポイントまで戻します。中断が早いほど、無駄なコンテキスト消費を抑えられます。

多くの人が損をしているのは、暴走に気づいても最後まで実行させてしまう場面です。誤った方向の出力が長いほど履歴を汚し、その後の軌道修正も難しくなります。

作業を中断して後日続けたい場合は、claude --continueで直前のセッションを再開し、claude --resumeで過去のセッションを選んで再開できます。ただし再開は履歴も一緒に戻るため、別タスクを始めるなら再開せず新規セッションを使ってください。

コマンド／操作用途使うタイミング
/clear履歴を破棄して初期化タスク完了時、2回失敗した時
/compact <指示>履歴を要約して圧縮同じタスクを続けたいが履歴が長い時
Esc実行の即時中断意図しない方向へ進み始めた時
Esc 2回変更の巻き戻し加えられた編集を取り消したい時
/rewindチェックポイントへ復帰複数の編集をまとめて戻したい時
claude --continue直前のセッション再開同じ作業を後から続ける時
claude --resume過去セッションを選んで再開特定の作業に戻りたい時

【最優先4】プロンプトに具体的なコンテキストを与える

曖昧な指示はClaudeに探索させ、コンテキストを浪費します。対象ファイルを@で指定し、手本となる既存コードを指し示すのが最短です。

「ログイン機能を直して」とだけ伝えると、Claude Codeは関連しそうなファイルを次々と読み込みます。読み込んだファイルはすべてコンテキストに載るため、指示が曖昧なほど本題に使える容量が減ります。

具体化の3要素

プロンプトの具体化は、次の3要素を意識するだけで十分です。長文を書く必要はありません。

  • 対象ファイルを@で参照し、探索範囲を限定する
  • 真似すべき既存パターンを「〜と同じ書き方で」と指し示す
  • バグ修正では、症状・再現条件・期待する挙動を書く

2つめの「既存パターンを指し示す」は特に効果が大きい要素です。プロジェクト固有の書き方をCLAUDE.mdに文章で説明するより、実物のファイルを1つ指すほうが正確かつ短く伝わります。

Before／Afterのプロンプト例

以下に、機能追加・バグ修正・リファクタリングの3場面でBefore／Afterを示します。いずれもAfterのほうが短時間で意図どおりの結果になります。

# 機能追加
## Before
商品の検索機能を追加して。

## After
@src/features/orders/OrderList.tsx と同じ構成で、
@src/features/products/ に商品検索機能を追加して。
検索条件は商品名（部分一致）とカテゴリ（完全一致）の2つ。
API は @src/app/api/orders/route.ts の実装パターンに合わせる。
ページネーションは既存の @src/components/Pagination.tsx を使う。
# バグ修正
## Before
ログインがうまくいかないので直して。

## After
ログイン後にリダイレクトされず、ログイン画面に戻る不具合を直したい。

- 症状: 正しいメールアドレスとパスワードでログインすると
  一瞬ダッシュボードが表示された後、/login に戻される
- 再現条件: Safari のみで発生。Chrome では発生しない
- 期待する挙動: ログイン成功後、/dashboard に留まる
- 関連ファイル: @src/app/login/page.tsx と @src/lib/auth.ts

まず原因を調査して、修正方針を説明してから実装して。
# リファクタリング
## Before
このコードをきれいにして。

## After
@src/features/invoice/InvoiceForm.tsx が 600 行を超えているので分割したい。

- バリデーションロジックを `useInvoiceValidation` フックに切り出す
- 金額計算を `src/features/invoice/calc.ts` に純関数として切り出す
- 表示の変更は行わない（振る舞いを変えない）
- 分割後に `npm test` を実行し、既存テストが通ることを確認して

リファクタリングの例では「振る舞いを変えない」と明記しています。制約を書かないと、Claudeは親切心から仕様変更を含む改善を提案し、レビューの手間が増えます。

やりすぎない線引き

毎回これほど長いプロンプトを書く必要はありません。何度も繰り返す指示は、CLAUDE.mdかカスタムコマンドに逃がすのが正解です。

「実装後にテストを実行する」のような毎回同じ指示は、CLAUDE.mdに1度書けば済みます。「この手順でコンポーネントを作る」のような定型作業は、カスタムコマンド化すると1行で呼び出せます。

カスタムコマンドの作り方は、Claude Codeカスタムコマンドの作り方で基礎から実用例まで解説しています。繰り返し作業が多い人ほど効果が出ます。

【中級5】探索→計画→実装→コミットの4フェーズで進める

複雑なタスクは、いきなり実装させず「探索→計画→実装→コミット」の順に区切ります。Plan Modeを使うと、計画に合意してから実装へ進められます。

Plan Modeとは、Claude Codeがファイルを変更せず、調査と計画立案だけを行うモードです。Shift+Tabでモードを切り替えるか、プロンプトで計画のみを求める形でも運用できます。

4フェーズの進め方

4フェーズは、それぞれで求める成果物を変えるのが要点です。各フェーズのプロンプト例を以下に示します。

# フェーズ1: 探索（コードを書かせない）
@src/features/billing/ 以下を読んで、現在の請求処理の流れを整理して。
まだコードは書かないで、処理の流れと関係するファイルだけを説明して。

# フェーズ2: 計画（Plan Mode）
分割請求に対応したい。実装方針を3案考えて、
それぞれのメリット・デメリットと影響範囲を比較して。
まだ実装はしないで。

# フェーズ3: 実装（合意した案だけ）
2案目の方針で実装して。
実装後に `npm test` を実行し、結果とともに報告して。

# フェーズ4: コミット
変更内容を Conventional Commits 形式のメッセージでコミットして。
PR の説明文も、変更理由とテスト結果を含めて作成して。

フェーズ1とフェーズ2で「まだコードは書かないで」と明示するのが重要です。この一文がないと、Claudeは調査の途中で実装を始め、合意前のコードがコンテキストに積み上がります。

なぜ4フェーズがコンテキスト管理に効くのか

計画段階で方針の誤りを潰せば、実装のやり直しに使うコンテキストを丸ごと節約できるためです。誤った方針で書かれた数百行のコードは、修正指示も含めてすべてコンテキストの浪費になります。

計画の文章は、実装コードに比べればはるかに短い情報量です。短い形式で方向性の合意を取るほうが、圧倒的に効率が良いという構造になっています。

やりすぎない線引き

公式ベストプラクティスドキュメントが明記しているとおり、小さなタスクでは計画をスキップして構いません。（参考: https://code.claude.com/docs/ja/best-practices）

判断の目安は「変更するファイルが1つで、やることが明確かどうか」です。文言修正やスタイル調整に計画フェーズを挟むのは、手続きのための手続きになります。

【中級6】パーミッション管理｜承認の中断を減らす3つの方法

承認を求められて作業が止まる問題は、auto mode・/permissionsによるホワイトリスト・/sandboxの3つで解決します。作業の中断が減れば、待ち時間だけでなく集中の分断も減ります。

方法向く場面リスク
auto mode信頼できるリポジトリで一気に進めたい時意図しない編集が進む可能性がある
/permissionsのホワイトリスト特定コマンドを繰り返し使う時登録内容次第。読み取り系なら低い
/sandbox未知のコードや外部リポジトリを扱う時実行環境が制限され一部処理が動かない

3つのうち、日常的に効果が高いのは/permissionsのホワイトリストです。よく使う読み取り系コマンドを登録しておくと、承認プロンプトの大半が消えます。

// .claude/settings.json
{
  "permissions": {
    "allow": [
      "Bash(npm test:*)",
      "Bash(npm run lint)",
      "Bash(npm run typecheck)",
      "Bash(git status)",
      "Bash(git diff:*)",
      "Bash(ls:*)"
    ],
    "deny": [
      "Read(./.env)",
      "Read(./.env.*)",
      "Read(./secrets/**)",
      "Bash(rm -rf:*)",
      "Bash(git push --force:*)"
    ]
  }
}

安全側の原則は言い切っておきます。--dangerously-skip-permissionsは原則として使いません。

すべての承認を飛ばす運用は、誤った削除や意図しないプッシュを止める最後の砦を外す行為です。速度のために安全装置を外すのではなく、安全な操作だけを個別に許可するほうが合理的です。

また、.env・認証キー・node_modulesは除外設定で読ませないでください。機密情報の保護に加えて、巨大なディレクトリを読ませないことがコンテキストの節約にも直結します。

やりすぎない線引きとして、lsやgit statusのような読み取り専用コマンドはホワイトリスト化して構いません。ファイルの削除・強制プッシュ・本番環境への操作といった破壊的コマンドには、常に手動承認を残してください。

【中級7】サブエージェントで調査を切り出す

サブエージェントとは、メインの会話とは別のコンテキストでタスクを実行する仕組みです。調査や探索をサブエージェントに委譲すると、メイン会話のコンテキストを汚さずに結論だけを受け取れます。

サブエージェントの価値は、探索の過程がメイン会話に残らない点にあります。50ファイルを読んで得た結論が3行なら、メイン会話に載るのはその3行だけです。

サブエージェントの使いどころは2つ

サブエージェントの使いどころは、広範囲の調査と、実装後の敵対的レビューの2つに絞ると分かりやすくなります。どちらも「大量に読むが、必要な出力は短い」という共通点があります。

  • 広範囲の調査 — 特定の関数がどこから呼ばれているか、影響範囲はどこまでかを洗い出す
  • 敵対的レビュー — 実装済みコードに対し、批判的な視点で問題点を指摘させる

敵対的レビューが有効なのは、実装したClaude自身は自分の実装を肯定しやすいためです。別のコンテキストから、粗探しを役割として与えたエージェントに見せると、指摘の質が上がります。

---
name: code-reviewer
description: 実装済みコードを批判的にレビューする。実装完了後に使う。
tools: Read, Grep, Glob
---

あなたは経験豊富なコードレビュアーです。
実装者の意図に同意せず、批判的な視点で問題点を洗い出してください。

観点:
1. エラーハンドリングの欠落（外部通信・パース・DB アクセス）
2. 境界値の扱い（空配列・null・0・上限超過）
3. 既存の規約からの逸脱（CLAUDE.md の Conventions を参照）
4. テストされていない分岐

出力形式:
- 指摘は「重大 / 中 / 軽微」の3段階で分類する
- 各指摘に該当ファイルと行番号を必ず添える
- 問題がない場合は「問題なし」とだけ書き、無理に指摘を作らない

定義ファイルは.claude/agents/code-reviewer.mdのように配置します。toolsを読み取り系に限定しているのは、レビュー担当に勝手な修正をさせないためです。

「問題がない場合は無理に指摘を作らない」という一文も重要です。この指示がないと、レビュー用エージェントは何かしら指摘しようとして、些末な指摘を並べます。

やりすぎない線引きとして、1ファイルで完結する調査に委譲は不要です。委譲そのものにも起動コストがかかるため、自分で@指定したほうが速い場面は多くあります。

レビューの指摘も全部を追う必要はありません。重大な指摘から順に対応し、軽微な指摘は見送る判断を人間が持ってください。

複数のエージェントを協調させる運用に踏み込みたい場合は、Claude Code Agent Teamsの解説記事で仕組みを詳しく扱っています。

【上級8】拡張機能の使い分け｜CLAUDE.md・Skills・Hooks・MCPの違い

常時必要な短いルールはCLAUDE.md、必要なときだけ読ませたい手順はSkills、必ず実行させたい処理はHooks、外部サービス連携はMCPです。4つを混同すると、書いたルールが機能しない事態が起きます。

手段読まれるタイミング性質向く用途
CLAUDE.md起動時に常時助言的短い共通ルール
Skills必要時にオンデマンド助言的ドメイン知識・長い手順
Hooks指定イベントで必ず決定論的整形・テスト・禁止操作の遮断
MCP／CLIツール呼び出し時実行外部サービス連携

Hooksは決定論的、CLAUDE.mdは助言的

Hooksは指定したイベントで必ず実行される決定論的な仕組みであり、CLAUDE.mdはClaudeが参照する助言にすぎません。必ず実行してほしい処理をCLAUDE.mdに書くのは誤りです。

「変更後は必ずフォーマッタをかける」とCLAUDE.mdに書いても、Claudeが判断で省略する可能性は残ります。100%実行させたいなら、Hooksとして仕組みで強制する必要があります。

// .claude/settings.json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npx prettier --write \"$CLAUDE_FILE_PATHS\""
          }
        ]
      }
    ],
    "PreToolUse": [
      {
        "matcher": "Bash",
        "hooks": [
          {
            "type": "command",
            "command": ".claude/hooks/block-dangerous.sh"
          }
        ]
      }
    ]
  }
}

上記のPostToolUseは、ファイルの編集・作成のたびにPrettierを走らせる設定です。Claudeの意思に関係なく整形されるため、フォーマット差分でPRが汚れる問題が構造的に消えます。

PreToolUseは、Bashコマンドの実行前にスクリプトを挟む設定です。危険なコマンドを検知して遮断する用途に向きます。

Skillsは「必要なときだけ読ませる」ための仕組み

Skillsとは、特定の作業をするときだけオンデマンドで読み込まれる手順書です。長い手順をCLAUDE.mdに書くとコンテキストの固定費になりますが、Skillsにすれば必要なときだけコストが発生します。

---
name: db-migration
description: |
  データベースのマイグレーションを作成・適用する手順。
  スキーマ変更、テーブル追加、カラム変更を依頼されたときに使う。
---
# DB マイグレーション手順
## 1. スキーマを編集する
`prisma/schema.prisma` を編集する。既存カラムの削除は原則禁止。
廃止する場合は `@deprecated` コメントを付けて残す。
## 2. マイグレーションを生成する
```
npx prisma migrate dev --name <変更内容を表す英小文字スネークケース>
```
## 3. 生成された SQL を必ず確認する
`prisma/migrations/` の最新ディレクトリの SQL を読み、
以下が含まれていないかを確認する。含まれていたら中止して報告する。
- DROP TABLE
- DROP COLUMN
- NOT NULL 制約の後付け（既存行があると失敗するため）
## 4. 型を再生成してテストする
```
npx prisma generate
npm test
```

Skillsで重要なのはdescriptionです。Claudeはdescriptionを見てSkillを読むかどうかを判断するため、「どんなときに使うか」を具体的に書く必要があります。

Skillファイルは.claude/skills/db-migration/SKILL.mdのように配置します。手順が20行を超えるなら、CLAUDE.mdではなくSkillsへ移すことを検討してください。

やりすぎない線引き

個人開発であれば、CLAUDE.md 1枚とHooks 1〜2本で十分です。Skillsやサブエージェントは、同じ手順を3回以上繰り返したと気づいた時点で作れば間に合います。

MCPサーバーの入れすぎには注意が必要です。接続したMCPサーバーのツール定義は毎回コンテキストに載るため、使わないサーバーを繋いだままにすると、本題に使える容量を静かに削ります。

【上級9】自動化とスケール

定型作業はclaude -pの非対話モードでスクリプト化し、独立したタスクはgit worktreeで並列セッションに分けます。どちらも、人間が待つ時間を減らすための手段です。

非対話モードは、プロンプトを引数で渡して結果を標準出力で受け取る実行形式です。シェルスクリプトやCIに組み込めるため、定型作業の自動化に向きます。

# 変更されたファイルのレビューを自動実行する
git diff --name-only main | while read file; do
  claude -p "$file の変更をレビューし、重大な問題だけを箇条書きで指摘して。問題がなければ「問題なし」とだけ出力して。"
done

git worktreeによる並列化は、同じリポジトリの複数ブランチを別ディレクトリに展開し、それぞれで独立したClaude Codeセッションを動かす方法です。互いに干渉しないため、独立した機能開発を同時に進められます。

git worktree add ../project-feature-a feature-a
git worktree add ../project-feature-b feature-b

# それぞれのディレクトリで別々に claude を起動する
cd ../project-feature-a && claude

ただし並列化は、人間側のレビュー能力が律速になります。同時に3つ動かしても、結果を確認できなければ意味がないため、まずは2つまでで試してください。

自動化を実際の業務に組み込んだ例として、非エンジニアがClaude CodeでWordPress自動投稿を作った話で、非対話モードとカスタムコマンドを組み合わせた運用の実体験をまとめています。

Claude Codeのよくある失敗パターンと対処法

Claude Codeの精度が落ちる原因の大半は、コンテキストの汚染・肥大・検証不足の3つに集約されます。原因が3つに絞れるということは、対処も3方向で足りるということです。

失敗パターン症状対処
キッチンシンクセッション話題が混ざり指示がずれるタスクの区切りで/clear
同じ問題を何度も修正修正が堂々巡りになる2回失敗したら/clearし、学んだ点を含めた新プロンプトで再開
過剰に長いCLAUDE.md書いた指示が無視される容赦なく削る
検証なしで信頼動かないコードが完成扱いになる検証手段を用意し証拠を出させる
無限探索調査が終わらず本題に進まないスコープを絞るかサブエージェントに委譲

キッチンシンクセッションへの対処が/clearである理由は、混ざった話題を後から分離する手段が存在しないためです。汚染されたコンテキストは修復できないので、捨てて作り直すほうが速くなります。

同じ問題を何度も修正してしまう場合、失敗した修正案が履歴に残り続けることが堂々巡りの原因です。/clearで履歴を捨て、「Aという方法は〇〇の理由で失敗した」という学びだけを新プロンプトに書き写して再開してください。

過剰に長いCLAUDE.mdで指示が無視されるのは、重要な指示の相対的な比重が下がるためです。指示を強調する言葉を足すのではなく、他の行を削って比重を上げるほうが確実に効きます。

検証なしで信頼してしまう失敗は、往復の手戻りとしてコンテキストを二重に消費します。検証手段の用意は初期コストがかかりますが、支払うのは1回で、回収は毎回です。

無限探索が起きるのは、探索の終了条件が与えられていないためです。「関連しそうなファイルを探して」ではなく「@src/features/auth/ の中だけを見て」とスコープを切れば、探索は必ず終わります。

段階別ロードマップ｜初日・慣れてきたら・チーム運用

初日は「CLAUDE.md作成・検証コマンド明記・/clearの習慣化」の3つだけで十分です。Hooksやサブエージェントなどの拡張機能は、後から足せば間に合います。

以下のロードマップは、上から順に消化するチェックリストとして使ってください。前の段階が終わっていない状態で次に進むと、設定だけが増えて効果が出ません。

初日にやること（所要30分）

初日の目標は、Claude Codeが「検証できる状態」と「余計な情報を読まない状態」を作ることです。所要時間は30分程度で完了します。

  • /initでCLAUDE.mdを生成し、コードを読めば分かる記述を削る
  • ビルド・テスト・リントのコマンドをCLAUDE.mdに正確に明記する
  • 変更後に検証を実行して結果を報告する、というルールを1行追加する
  • .env・認証キー・node_modulesを除外設定に登録する
  • タスクが1つ終わるたびに/clearを実行する習慣をつける

この5項目のうち、効果を最も早く体感できるのは/clearの習慣化です。設定が一切不要で、実行した直後から出力の一貫性が変わります。

慣れてきたらやること（1〜2週間目）

1〜2週間目は、作業の進め方そのものを設計する段階です。初日の3つが習慣として定着してから着手してください。

  • 複雑なタスクでPlan Modeを使い、探索→計画→実装→コミットの4フェーズで進める
  • /permissionsで、よく使う読み取り系コマンドをホワイトリストに登録する
  • 広範囲の調査と実装後のレビューをサブエージェントに委譲する
  • /compactを、残す情報を指定した指示付きで使う
  • 繰り返す指示をカスタムコマンドに切り出す

この段階で効果が大きいのは、Plan Modeによる計画フェーズの導入です。実装のやり直しが減るため、1タスクあたりの所要時間が明確に短くなります。

チームで運用するなら

チーム運用の目標は、個人の工夫を仕組みとして共有し、品質のばらつきをなくすことです。小規模チームであれば、以下の4項目で十分に機能します。

  • CLAUDE.mdをリポジトリにコミットし、チーム共通のルールとして共有する
  • 個人の好みや環境依存の設定はCLAUDE.local.mdに分離し、gitignoreに追加する
  • Hooksでフォーマッタとテストを強制し、レビューで指摘する手間をなくす
  • レビュー用サブエージェントを共通定義としてリポジトリに置き、全員が同じ基準でレビューする

CLAUDE.mdをコミットして共有する運用では、通常のコードと同じくPRでレビューしてください。ルールの追加は容易ですが、削除の判断は個人では下しにくいため、レビューの場を用意することが肥大化の抑止になります。

Hooksによる強制は、チームで最も費用対効果が高い施策です。フォーマットや基本的なチェックが自動化されると、人間のレビューは設計や仕様の議論に集中できます。

よくある質問（FAQ）

CLAUDE.mdとSkillsはどちらに書くべきですか？

判断基準は「毎回必要か、たまに必要か」です。毎回参照する短いルールはCLAUDE.mdに書き、特定の作業のときだけ必要な長い手順はSkillsに切り出します。

CLAUDE.mdは起動のたびに読み込まれる固定費であるため、たまにしか使わない手順を置くと毎回コンテキストを浪費します。目安として、手順が20行を超えて、かつ使用頻度が週に数回以下ならSkillsが適しています。

CLAUDE.mdを書いても指示が無視されるのはなぜですか？

主な原因は2つあり、CLAUDE.mdの肥大化による指示の埋没と、/compact後にネストしたCLAUDE.mdが再注入されないことです。まずCLAUDE.mdを削って分量を減らしてください。

長時間セッションの途中から指示が効かなくなった場合は、/clearでセッションを切り直すと、CLAUDE.mdが最初から読み込まれて解決します。それでも守られない処理は、助言的なCLAUDE.mdではなく、決定論的に実行されるHooksで強制してください。

/clearと/compactはどちらを使えばよいですか？

タスクが変わるなら/clear、同じタスクの続きなら指示付きの/compactです。迷った場合は/clearのほうが安全です。

/compactは要約の過程で情報が欠落するため、残したい決定事項があるなら必ず引数で指定してください。/clearで失われて困る情報は、会話履歴ではなくCLAUDE.mdやコミットメッセージに残すのが本来の運用です。

利用上限のあるプランでもベストプラクティスの効果はありますか？

効果はあります。むしろ利用上限のあるプランほど、コンテキスト節約の効果は大きくなります。

本記事のプラクティスは、いずれも無駄なやり取りと無駄な読み込みを減らすものです。同じ作業をより少ない消費で終えられるようになるため、上限に達するまでの実作業量が増えます。

テストがないプロジェクトでも検証手段は用意できますか？

用意できます。テストがなくても、ビルドが通ること、リンターが通ること、実行して期待する出力が出ることは、いずれも検証手段として機能します。

まずはビルドコマンドをCLAUDE.mdに書き、「変更後に必ずビルドを通してから報告する」というルールを1行追加してください。それだけで、動かないコードが完成扱いになる事故は大きく減ります。

小さな修正でもPlan Modeを使うべきですか？

小さな修正にPlan Modeは不要です。公式ベストプラクティスドキュメントも、小さなタスクでは計画をスキップしてよいと明記しています。（参考: https://code.claude.com/docs/ja/best-practices）

判断の目安は「変更するファイルが1つで、やることが明確な場合」です。文言の修正やスタイルの微調整に計画フェーズを挟むと、確認の往復が増えて逆に遅くなります。

まとめ｜まず3つだけ実践する

Claude Codeのベストプラクティスは、すべてコンテキストウィンドウ管理という1つの原理に還元されます。まずは検証手段の用意・CLAUDE.mdの簡潔化・/clearの習慣化の3つから始めてください。

検証手段を与えれば、Claudeは推測ではなく実行結果を根拠に自己修正し、人間との往復が減ります。CLAUDE.mdを簡潔に保てば、重要な指示が長文に埋もれることがなくなります。/clearをタスクの区切りで実行すれば、無関係な履歴による汚染が起きません。

この3つが習慣として回り始めてから、Plan Mode・パーミッション設計・サブエージェントへ進んでください。順番を守ることが、設定だけが増えて効果が出ない状態を避ける唯一の方法です。

設定面をさらに詰めたい場合はClaude Codeの設定おすすめ9選、繰り返し作業を効率化したい場合はカスタムコマンドの作り方を参照してください。

Claude Codeを業務やWebサイト運用にどう組み込むかで迷っている場合は、当サイトの問い合わせフォームからご相談ください。実際にClaude Codeで自動化の仕組みを構築・運用している立場から、環境に合わせた進め方を提案します。

野本一貴
野本一貴

Webディレクター／SEOライター｜2018年〜フリーランス｜法律・金融など専門領域のSEO記事制作が得意｜最近はClaude Codeでシステムの自動化にハマり中｜この記事もClaude CodeからWordPressへ自動投稿しています

記事本文: 13

関連投稿

返信を残す

メールアドレスが公開されることはありません。 ※ が付いている欄は必須項目です

CAPTCHA