このガイドは2つのソースからClaude Codeのベストプラクティスをまとめたものだ。Anthropicの公式ドキュメントと、数百のOSSプロジェクトのCLAUDE.mdを分析して得た実際に機能するパターン。
「Claude Code ベストプラクティス」と検索した人が欲しいのは、理論より具体的なルールだろう。このガイドはそれを提供する。
Claude Code設定の3つのレイヤー
Claude Codeの動作は3つのレベルで制御できる。この階層を理解することが最初のベストプラクティスだ：
- CLAUDE.mdファイル — セッションごとに読み込まれる永続的な指示
- Skills（カスタムスラッシュコマンド） — 再利用可能なタスクテンプレート（
.claude/skills/） - Hooks — Claude Codeのイベントをトリガーにしたシェルコマンド
ほとんどの開発者は最初のレイヤーしか使っていない。優れたセットアップは3つ全てを活用する。
CLAUDE.mdのベストプラクティス
500行以内に収める
165以上のリポジトリのCLAUDE.mdを分析した結果、効果的なファイルには共通のパターンがある：簡潔であることだ。500行以内のファイルは全体が読まれ、一貫して守られる。1,000行を超えると、後半のセクションをClaudeが無視したり優先度を下げたりしがちになる。
CLAUDE.mdが長くなりすぎたら分割しよう。プロジェクトレベルのルールはルートのCLAUDE.mdに、ディレクトリ固有のルールはサブディレクトリのCLAUDE.mdファイルに書く。Claude Codeは全てを読んでコンテキストをマージする。
段落よりヘッダーで構造化する
Claude CodeはCLAUDE.mdをMarkdownとして解析する。ヘッダーが意味的な境界を作り、Claudeが情報を優先的に処理しやすくなる。比較してみよう：
悪い例：
TypeScriptはstrictモードを使う。テストは__tests__ディレクトリに置く。
テストフレームワークはvitest。外部APIは必ずモックする。コミット前にnpm testを実行。
Prettierでフォーマット。シングルクォートを使う。良い例：
## Code Style
- TypeScript strict mode
- シングルクォート、セミコロンなし
- Prettierでフォーマット
## Testing
- フレームワーク: vitest
- 場所: `__tests__/` ディレクトリ
- 外部APIは必ずモックする
- コミット前に `npm test` を実行後者は人間が読みやすいだけでなく、Claude Codeも各セクションのスコープが明確なので、より確実に処理できる。
最重要ルールを先頭に書く
Claude CodeはCLAUDE.mdを上から下へ読む。長いセッションでコンテキストウィンドウが圧縮されると、後のセクションが要約される場合がある。絶対に守らせたいルールは先頭に書こう：
- ビルド・テストコマンド — Claudeが自分の作業を検証するために必要なもの
- 絶対的な制約 — あってはならないこと（例：「マイグレーションファイルを削除しない」）
- アーキテクチャの決定事項 — Claudeが従うべきパターン
- スタイルの好み — フォーマット、命名規則
- あれば嬉しいガイドライン — 任意の指針
否定ルールは少なく、しかし正確に
やってはいけないことを伝える方が、やるべきことを伝えるより効果的な場合がある：
## やってはいけないこと
- 自明なコードの説明コメントを書かない
- 一度しか使わない関数のための抽象化レイヤーを作らない
- TypeScriptで`any`型を使わない
- あり得ない状態のエラーハンドリングを追加しない精度が重要だ。「悪いコードを書かない」は役に立たない。「any型を使わない」は実行可能だ。
実行可能なコマンドを入れる
CLAUDE.mdに書ける最もインパクトのある内容は、プロジェクトのビルド・テストコマンドだ：
## コマンド
- ビルド: `npm run build`
- 全テスト: `npm test`
- 単体テスト: `npm test -- --grep "テスト名"`
- Lint: `npm run lint`
- 型チェック: `npx tsc --noEmit`これがないとClaudeは推測する。あればClaudeが自分の作業を自分で検証してからプレゼンできる。
Skillsのベストプラクティス
Skillsは.claude/skills/に置くカスタムスラッシュコマンドだ。複雑な複数ステップのワークフローをワンラインコマンドに変換する。
どんな時にSkillを作るか
同じ複数ステップの指示を2回以上Claudeに与えた時。よくある候補：
/review— 特定のコードレビューチェックリストを実行/deploy— デプロイパイプラインを実行/refactor— チームのリファクタリングパターンを適用/test— 規約に従ったテストを生成/handover— 次の開発者のためにセッションコンテキストを要約
機能するSkillの構造
良いSkillファイルは3つのパートで構成される：
# /skill-name
このスキルが何をするかの簡単な説明。
## Steps
1. まずXをする
2. 次にYを確認する
3. 最後にZを出力する
## Rules
- 実行前に必ず検証する
- 出力は[特定のフォーマット]を使う
- ステップ2を飛ばさないSkillはひとつのことに集中させる
1つのSkillは1つのことをやる。Skillファイルが100行を超えていたら、やろうとしていることが多すぎるサインだ。組み合わせて使える小さなSkillに分割しよう。
Hooksのベストプラクティス
HooksはClaude Codeのイベントに応じてシェルコマンドを実行する。.claude/settings.jsonで設定する：
{
"hooks": {
"on_tool_use:write": "npm run lint --fix $FILE",
"on_tool_use:bash": "echo 'Command: $COMMAND'"
}
}Hooksは自動化された品質ゲートに使う
Hooksの最善の使い方は自動検証だ：
- ファイル書き込み後: Linterやフォーマッタを自動実行
- コミット前: テストを実行
- bashコマンド後: Claudeが実行したことをログ記録
Hooksに複雑なロジックを入れない
Hooksは高速でシンプルなシェルコマンドであるべきだ。条件分岐が必要だったり、数秒以上かかるようなら、それはSkillに書くべき内容だ。
メモリとコンテキストのベストプラクティス
クロスセッションの知識にはメモリシステムを使う
Claude Codeのメモリシステム（.claude/memory/）はセッションをまたいで情報を保持する。使い道：
- 全プロジェクトに適用するユーザーの好み
- フィードバックのパターン（Claudeに覚えておいてほしい修正）
- 時間とともに変化するプロジェクト知識
コードから導き出せるもの（アーキテクチャ、ファイルパス、規約）はメモリに入れないこと。それらはCLAUDE.mdに書くべきだ。
長いセッションでは積極的に/compactを使う
長いセッションはコンテキストが埋まるにつれてパフォーマンスが劣化する。/compactを積極的に使おう：
- 大きなタスクを完了した後
- 別の種類の作業を始める前
- Claudeが繰り返し始めたり、以前のコンテキストを忘れ始めたりした時
ワークフローのベストプラクティス
Claudeに書く前に読ませる
Claude Codeの出力が悪くなる最も一般的な原因は、既存コードを読む前にコードを書くことだ。CLAUDE.mdでこれを強制しよう：
## ワークフロー
- 既存コードを修正する前に読む
- 変更を提案する前に現在の実装を理解する
- 読んでいないファイルへの変更を提案しない複雑な変更にはPlan Modeを使う
3ファイル以上に触れる変更には、Claudeがコーディングを始める前に/planでアプローチを合わせるPlanning Modeを使う。間違ったアプローチで無駄な作業をするのを防げる。
一度に1タスク
Claudeには1つの明確なタスクを与える。「authモジュールをリファクタして、レート制限を追加して、テストも更新して」は、3つの個別でフォーカスされたリクエストより結果が悪くなる。
避けるべきアンチパターン
CLAUDE.mdを過剰設計する
CLAUDE.mdは小説ではない。序文も、哲学的なセクションも、格言も必要ない。全ての行が実行可能な指示であるべきだ。
ドキュメントの重複
プロジェクトにCONTRIBUTING.mdやスタイルガイドがあるなら、内容をCLAUDE.mdにコピーしないこと。参照する：
## スタイルガイド
CONTRIBUTING.mdの規約に従う。重要なポイント：
- [ここには最重要の3〜5ルールのみ書く]フィードバックループを無視する
優れたCLAUDE.mdは進化する。セッション中にClaudeを修正した時は、その修正をCLAUDE.mdに追加して二度と同じ指示をしなくて済むようにしよう。これがAI支援開発の複利効果だ。