Claude Code公式ベストプラクティス全訳＋実例補完(2026年5月版)

結論

原文は2026年5月時点で code.claude.com/docs/en/best-practices にホストされており、本記事もその構成と原則に従います。引用箇所は原文出典を都度示します。

大前提：コンテキストウィンドウが速く埋まる

ベストプラクティスのほぼ全項目は、**「Claudeのコンテキストは速く埋まり、埋まると性能が落ちる」**という1つの制約から導かれています。

会話履歴・読み込んだファイル全文・実行したコマンドの出力が全部コンテキストに乗ります。デバッグ1セッションやコードベース探索1回で数万トークン消費することは普通で、上限に近づくとClaudeは前半の指示を「忘れる」ような挙動を示し、ミスが増えます。

原文はこの前提から 「コンテキストは管理すべき第一資源」 と明言しています。/clear、サブエージェント、/compact、/rewind などのコマンドはすべてこの資源を温存するための道具です。

1. Claude に自分で検証する手段を与える

検証手段がない指示は、見た目だけ正しく動かない実装を生み、結果としてあなたが唯一のフィードバックループになります。修正のたびに人間が確認するので、出力量に比例して工数が増えます。

公式が挙げている3つの戦略：

UIの場合、Claude for Chrome 拡張を使うとブラウザでタブを開き、UIをテストして自力でイテレーションさせられます。lint、テストスイート、出力をチェックするBashコマンドでも構いません。要は「Claudeが自分で○×を判定できる」状態を作ることです。

2. Explore → Plan → Implement → Commit

「いきなり書かせる」と、間違った問題を解いた実装が出てきがちです。公式は4フェーズに分けることを推奨しています。

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

Claudeは意図を推測できますが、心は読めません。ファイル名・制約・既存パターンを具体的に指すほど、修正回数が減ります。

公式が挙げる4つの戦略：

• タスクの範囲を絞る："foo.py のテスト書いて" → "foo.py のテスト。ログアウト時のエッジケースをカバー。mock は避けて"
• 情報源を指す："なぜ ExecutionFactory のAPIは変なの？" → "ExecutionFactory のgit履歴を見て、APIがどう成立したか要約して"
• 既存パターンを参照させる："カレンダーウィジェット追加" → "ホームページの既存ウィジェット実装パターンを見て。HotDogWidget.php が良い例。同じパターンで月選択＋年ページネーション付きカレンダーを実装。新しいライブラリは入れず、既存のものだけ使って"
• 症状を記述する："ログインのバグ直して" → "セッションタイムアウト後にログイン失敗する報告あり。src/auth/、特にトークンリフレッシュをチェック。問題を再現する失敗テストをまず書いて、それから直して"

逆に、探索フェーズで方向性を見たい時はあえて曖昧に投げるのも有効です。"このファイルで改善すべき点は？" のような質問は、自分が思いつかなかった視点を出してくれます。

リッチなコンテキストの渡し方

• @ でファイル参照：ファイルの場所を説明するより @src/foo.ts と書いた方が速い。Claudeは返答前にそのファイルを読む
• 画像を直接ペースト：コピペでもドラッグ＆ドロップでも入る
• URLを渡す：ドキュメントやAPIリファレンス。/permissions でよく使うドメインをallowlistしておく
• データをパイプ：cat error.log | claude でファイル内容を直接渡せる
• 取りに行かせる：「必要な情報はBashやMCP、ファイル読みで自分で取って」と明示する

4. 環境構成

ここからは「セッション単位でなく永続的に効く設定」の話です。

4.1 CLAUDE.md を書く

CLAUDE.md は全会話の冒頭で自動的に読み込まれる特別なファイルです。Bashコマンド、コードスタイル、ワークフロー規約を入れる。コードを読んでも推測できない情報を渡す場所です。

/init コマンドでビルドシステムやテストフレームワークを自動検出した雛形を生成できます。形式は自由ですが、短く人間可読に保ちます。

# Code style
- Use ES modules (import/export) syntax, not CommonJS (require)
- Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow
- Be sure to typecheck when you're done making a series of code changes
- Prefer running single tests, and not the whole test suite, for performance

CLAUDE.md は毎セッションで読まれるので、広く適用される事項のみ入れます。特定タスクでだけ必要な情報は Skills に切り出し、必要な時だけ読み込ませる方が良い。

長くするほど無視率が上がるのがCLAUDE.md運用の鉄則です。原文は「ルールがあるのにClaudeが従わないなら、ファイルが長すぎてそのルールが埋もれている」と明言しています。各行に「これを消したらClaudeがミスするか？」と自問して、ノーなら削る。

調整テクニック：

• IMPORTANT や YOU MUST で強調できる(乱用しない)
• @path/to/file 構文で他ファイルをインポートできる
• 配置場所：
  • ~/.claude/CLAUDE.md：全Claudeセッション
  • ./CLAUDE.md：チームで共有(git管理)
  • ./CLAUDE.local.md：個人用(.gitignore する)
  • 親/子ディレクトリ：モノレポで自動的に拾われる

4.2 権限を設定する

デフォルトでは、ファイル書き込み・Bashコマンド・MCPツールなどシステムを変える可能性がある操作はすべて確認プロンプトが出ます。承認10回目には誰も読んでおらずクリックしているだけ、というのが原文の指摘。3つの緩和手段：

• auto モード：別の分類器モデルがコマンドを審査し、スコープ越権・未知のインフラ・悪意あるコンテンツ誘導の3カテゴリだけブロックする。「方向性は任せたいが毎手は承認したくない」時向け
• /permissions allowlist：npm run lint や git commit のように安全と分かっているコマンドを許可
• /sandbox：OSレベルでファイルシステムとネットワークを制限。境界内で自由に動かす

4.3 CLIツールを使わせる

gh、aws、gcloud、sentry-cli のようなCLIツールは、外部サービスとやりとりする最もコンテキスト効率の良い手段です。GitHubを使うなら gh は入れる。Issue作成、PR、コメント読みすべて理解しています。gh がないとGitHub API直叩きになり、未認証だとレート制限に当たりやすい。

知らないCLIツールでも Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C. と投げると効果的に学習します。

4.4 MCPサーバーを繋ぐ

claude mcp add で外部ツール(Notion、Figma、データベース等)を接続できます。Issueトラッカーから機能要件を引いてくる、DBに直接クエリする、Figmaのデザインを取り込む、といったワークフローが組めます。

4.5 Hooks を設定する

Hooks は Claudeのワークフローの特定ポイントで自動実行されるスクリプトです。CLAUDE.mdの指示は「助言」ですが、hooks は決定的に実行されるので「絶対に毎回起きてほしい」処理に使います。

"Write a hook that runs eslint after every file edit" のように Claude 自身に書かせることもできます。設定は .claude/settings.json、確認は /hooks。

4.6 Skills を作る

Skills は .claude/skills/<name>/SKILL.md に置くドメイン知識や再利用ワークフローです。Claudeは関連時に自動適用するか、/skill-name で明示的に呼びます。CLAUDE.md と違って毎会話ロードされない=コンテキストを汚さない点が肝。

---
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

/fix-issue 1234 で呼べる。副作用のあるワークフローには disable-model-invocation: true を付けて、明示的にしか起動できないようにします。

4.7 サブエージェント（カスタム）を作る

.claude/agents/ 配下に専用エージェントを定義できます。独立したコンテキストと独自のツール許可を持つので、多数のファイルを読むタスクや特化型のレビューに向いています。

---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
You are a senior security engineer. Review code for:
- Injection vulnerabilities (SQL, XSS, command injection)
- Authentication and authorization flaws
- Secrets or credentials in code
- Insecure data handling

Provide specific line references and suggested fixes.

メイン会話で「セキュリティレビューはサブエージェントを使って」と明示的に指示します。

4.8 プラグインを入れる

/plugin でマーケットプレースが開きます。Skills・hooks・サブエージェント・MCPサーバーを1ユニットにまとめた配布物。型付き言語を扱うなら code intelligence プラグインを入れると、シンボル探索や編集後の自動エラー検知が効きます。

5. コミュニケーション

5.1 コードベースに質問する

新しいリポジトリにオンボーディングする時、シニアエンジニアにする質問をそのままClaudeに投げるのが効きます：

• ログはどう動いてる？
• 新しいAPIエンドポイントはどう作る？
• foo.rs の134行目の async move { ... } は何してる？
• CustomerOnboardingFlowImpl はどんなエッジケースを扱ってる？
• なぜここでは foo() を呼んで bar() を呼んでない？

特別なプロンプトは要りません。直接訊くだけです。

5.2 Claudeに自分をインタビューさせる

大きめの機能では、Claudeに先にあなたを面接させるのが効きます。最小限のプロンプトで AskUserQuestion ツールを使わせる。

I want to build [brief description]. Interview me in detail using the AskUserQuestion tool.

Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.

Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.

仕様が固まったら新しいセッションで実装する。クリーンなコンテキストで実装に集中できて、書面化された仕様も手元に残ります。

6. セッション管理

6.1 早く・頻繁にコース修正

最良の結果は短いフィードバックループから来ます。

• Esc：Claudeの動作を途中で止める。コンテキストは保持される
• Esc + Esc or /rewind：rewind メニュー。会話やコードを過去地点に戻すか、選択メッセージから要約する
• "Undo that"：変更を取り消させる
• /clear：無関係タスクの間でコンテキストをリセット

6.2 コンテキストを積極的に管理

• /clear をタスク間で挟む
• 自動圧縮：コンテキスト上限が近づくとClaudeが要約してスペースを開ける
• /compact <instructions>：制御付き圧縮。例：/compact Focus on the API changes
• Esc + Esc の部分要約：選択メッセージ以前/以降だけ要約する
• CLAUDE.mdに圧縮指示："When compacting, always preserve the full list of modified files and any test commands" のように書くと、要約時に守るべき情報を指定できる
• /btw：軽い質問用。回答はオーバーレイで表示され会話履歴に入らない=コンテキストを増やさない

6.3 調査はサブエージェントに渡す

コンテキストが第一資源である以上、サブエージェントは最強の道具のひとつです。コードベースを調査させると大量のファイルを読みますが、その全部があなたのコンテキストに乗ります。サブエージェントは別コンテキストで動き、要約だけ返してきます。

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

実装後のレビュー用にも使えます：use a subagent to review this code for edge cases。

6.4 チェックポイントで巻き戻す

送信したプロンプトごとにチェックポイントが自動で作られるので、Esc 二回または /rewind で会話だけ・コードだけ・両方を任意の地点に戻せます。Claudeは変更前に自動でスナップショットを取っています。

実用上の含意は大きい：「とりあえずやってみて、ダメなら戻す」が安全になります。慎重に計画する代わりに、リスキーな案を試させてから巻き戻す、というスタイルが取れます。

6.5 セッションを再開する

claude --continue で直近セッション、claude --resume で一覧から選んで再開。/rename で oauth-migration のような分かりやすい名前を付けておくと、ワークストリーム単位の永続コンテキストとして扱えます。

7. 自動化とスケール

ここまでは「人間1人 × Claude 1個 × 会話1本」前提でした。Claude Codeは横にスケールするので、ここからは並列化の話。

7.1 非対話モード (claude -p)

claude -p "your prompt" でセッションなしのワンショット実行ができます。CI、pre-commit hook、任意のスクリプトに組み込める。出力形式は plain text / JSON / streaming JSON から選べます。

# 一発質問
claude -p "Explain what this project does"

# 構造化出力でスクリプト処理
claude -p "List all API endpoints" --output-format json

# ログのリアルタイム解析
claude -p "Analyze this log file" --output-format stream-json

7.2 複数のClaudeセッションを並列に走らせる

調整コスト別に4つの選択肢：

• Worktrees：別々のgitチェックアウトでCLIセッションを動かす。編集が衝突しない
• デスクトップアプリ：複数ローカルセッションを視覚的に管理。各セッションが独自のworktreeを持つ
• Claude Code on the web：Anthropic管理のクラウドVMで隔離実行
• Agent teams：複数セッションを自動調整。共有タスク・メッセージング・チームリードを持つ構造

並列化は単に量を増やすだけでなく、品質目的にも使えます。新しいコンテキストでレビューさせると、自分が書いたコードに対するバイアスがかからない。Writer/Reviewer パターン：

テストでも同じことができます。片方にテストを書かせ、もう片方にそれをパスする実装を書かせる。

7.3 ファイル群に対するファンアウト

大規模マイグレーションや解析では、claude -p をループで複数並列起動できます：

for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

最初の2-3ファイルで失敗を見ながらプロンプトを調整し、全件に展開する流れ。--allowedTools で実行可能な操作を絞っておくのが、無監視で動かす時の安全策。

データパイプラインへの組み込みも：

claude -p "<your prompt>" --output-format json | your_command

開発時は --verbose でデバッグ、本番では外す。

7.4 autoモードで完全自律実行

--permission-mode auto を使うと、分類器モデルが背後で実行前にコマンドを審査します。スコープ越権・未知のインフラ・悪意あるコンテンツ誘導をブロックしつつ、ルーチンワークは止まらない。

claude --permission-mode auto -p "fix all lint errors"

-p(非対話)との組み合わせでは、分類器が繰り返しブロックした場合自動的に中断します(フォールバック先の人間がいないため)。

8. よくある失敗パターン

原文末尾に5つ並んでいます。記事執筆者の経験からも頻発します：

• キッチンシンクセッション：1タスクで開始 → 関係ない質問 → 元タスクに戻る、を繰り返してコンテキストに無関係情報が溜まる。 対処：無関係タスク間で /clear
• 延々と修正：Claudeがミス → 修正 → まだミス → また修正。失敗アプローチでコンテキストが汚染される。 対処：2回失敗したら /clear して、教訓を込めた新しい初回プロンプトを書く
• 過剰仕様のCLAUDE.md：長すぎてClaudeが半分無視する。重要な規則がノイズに埋もれる。 対処：容赦なく刈り込む。Claudeが指示なしでも正しくできることは消すか、hookに変換
• 信用→検証ギャップ：もっともらしい実装がエッジケースを処理していない。 対処：必ず検証手段(テスト、スクリプト、スクリーンショット)を付ける。検証できないものはマージしない
• 無限探索：「調査して」とスコープなしで投げる→数百ファイル読んでコンテキスト消費。 対処：調査範囲を絞るか、サブエージェントに渡してメインを汚さない

9. 直感を養う

原文の締めは「これらのパターンは固定ルールではなく出発点」というメッセージです。

時にはコンテキストを溜め続けた方が良い場面もあります(1つの複雑な問題に深く潜っていて履歴に価値がある時)。プランをスキップした方が良い場面もあります(探索的タスクでClaudeの解釈を見たい時)。曖昧なプロンプトが正解の場面もあります(制約をかける前に解釈を見たい時)。

Pay attention to what works.

良い出力が出たら、何をしたか観察する：プロンプト構造、コンテキストの渡し方、使ったモード。失敗したら、なぜか問う：コンテキストがノイジーだったか、プロンプトが曖昧だったか、一度に大きすぎたか。

まとめ

公式ベストプラクティスの背骨を一行に圧縮すると、「コンテキストを管理し、Claudeに自分で検証する手段を渡せ」 に尽きます。

その上で：

• 環境構成(CLAUDE.md、権限、MCP、hooks、skills、サブエージェント、プラグイン)は一度作れば永続的に効く
• セッション運用(/clear、サブエージェント調査、checkpoint、auto モード)は会話単位の道具
• スケール(claude -p、worktree、agent teams、fan-out)は1セッションでは届かない量と質の両方に効く

最初に整えるべきは「検証手段」と「CLAUDE.mdの最低限の規約」、次に「権限の緩和(auto モードか allowlist)」、その後で MCP・hooks・skills・サブエージェントと環境を作り込んでいく順序が、コスト対効果が高いです。

関連記事

• Claude Code導入ガイド：Windows/macOS/WSLと初期設定 — まだ環境ができていない場合の前段
• AGENTS.md / CLAUDE.md / メモリ運用プレイブック — CLAUDE.md の書き方をさらに深掘り
• Claude Code のサブエージェント設計 — 本記事の4.7・6.3で触れたサブエージェントの実装パターン
• CLAUDE.md ジェネレーター + 採点 — 本記事の規約を踏まえて CLAUDE.md の雛形生成と採点ができる無料ツール

参考

• Best practices for Claude Code(Anthropic公式、本記事の原文)
• How Claude Code works
• Extend Claude Code
• Common workflows
• CLAUDE.md