Anthropicが公式ドキュメントとして「Claude Code Best Practices」を公開しています。
私はClaude Codeを700時間以上自律稼働させてきた非エンジニアです。公式ベストプラクティスを読んで「そうそう、これ」と膝を打ったポイントと、「ここは補足が要る」と感じたポイントを共有します。
1. 「コンテキスト窓が最重要リソース」は本当
Most best practices are based on one constraint: Claude's context window fills up fast, and performance degrades as it fills.
公式が最初に挙げるのがコンテキスト窓の管理です。
実体験: 3時間の自律セッションで25本のフックを開発・テストしたとき、後半になるほどClaudeの指示遵守が甘くなりました。前半で完璧だった数値統一（「637 hooks」→「637 hooks」のような一括置換）が、後半では古い数値のまま放置されるケースが発生。
対策: 公式は /clear を推奨していますが、自律セッションではフックで強制する方が確実です。
#!/usr/bin/env bash
# compact-reminder.sh — コンテキスト肥大化を検知して警告
# Event: Notification
set -euo pipefail
MSG="${CLAUDE_NOTIFICATION:-}"
if echo "$MSG" | grep -qi "context.*compact\|auto.*compact"; then
echo '{"result":"warn","message":"コンテキストが圧縮されました。重要な変数（hook数、テスト数、バージョン）を再確認してください"}'
else
echo '{"result":"pass"}'
fi
2. 「検証手段を渡せ」が最高レバレッジ
Include tests, screenshots, or expected outputs so Claude can check itself. This is the single highest-leverage thing you can do.
公式が「最もレバレッジの高い施策」と断言しているのがこれです。
実体験: フック1本あたり平均18.8本のテストを書いています（13,931テスト / 637フック）。テストがあるからこそ、Claudeは自分で「壊していないか」を確認でき、自律的にバグを修正します。
テストなしでフックを書いていた初期は、文法エラーやエッジケースの見落としが頻発しました。テストを先に書く運用に変えてから、品質が劇的に改善。
公式の表にある対比が秀逸:
| Before | After |
|---|---|
| 「メール検証関数を書いて」 | 「validateEmail関数を書いて。test@example.comはtrue、invalidはfalse。テスト実行して確認して」 |
「テスト実行して確認して」の一文があるだけで、Claudeの出力品質が変わります。
3. CLAUDE.mdの「肥大化」は本当に起きる
Keep it concise. For each line, ask: "Would removing this cause Claude to make mistakes?" If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions!
これは耳が痛い。
私のプロジェクトのCLAUDE.mdは100行を超えています。公式が警告するとおり、長すぎるCLAUDE.mdはルールが埋もれる原因になります。
公式の判断基準: 「この行を削除したらClaudeがミスするか？」→ NOなら削除。
実体験から得た追加基準:
- Claudeが既にコードから推測できること → 削除（言語規約、標準的なgitフローなど）
- 頻繁に変わる情報 → CLAUDE.mdに書かない（バージョン番号、統計値など）
- 特定の状況でしか使わない知識 → スキルに移動
公式が新たに推奨しているスキル（.claude/skills/のSKILL.mdファイル）は、この問題の正解です。CLAUDE.mdに全部詰め込むのではなく、ドメイン知識はスキルに分離する。Claudeは必要なときだけスキルを読み込むので、コンテキストを汚染しません。
4. 「CLAUDE.mdのルール」と「フック」の決定的な違い
Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens.
公式がはっきり書いています: CLAUDE.mdはアドバイザリー、フックは確定的。
これは637本のフックを開発してきた最大の動機です。
CLAUDE.md: 「rm -rfは使わないでください」
→ Claudeは読むが、コンテキストが埋まると忘れる
フック: rm-safety-net.sh
→ rm -rfを検出したら物理的にブロック。忘却不可能
公式の推奨: 「CLAUDE.mdに書いてもClaudeが従わない」→「フックに変換すべきサイン」
私の経験では、以下のルールはCLAUDE.mdよりフックが適切です:
- セキュリティルール: 破壊的コマンドのブロック、シークレット漏洩防止
- 品質ゲート: テスト実行の強制、lint実行の強制
- ワークフロー強制: コミット前のテスト必須、プッシュ前のレビュー必須
逆に、フックに向かないもの:
- コードスタイルの好み（ESModules vs CommonJS）
- アーキテクチャの判断（「このパターンに従って」）
- 文脈依存のルール（「このリポジトリでは～」）
5. 「探索→計画→実装→コミット」の4フェーズは守るべき
Letting Claude jump straight to coding can produce code that solves the wrong problem.
公式の推奨する4フェーズ:
- 探索: Plan Modeでコードを読む
- 計画: 実装プランを作成
- 実装: Normal Modeで実装+テスト
- コミット: PRを作成
実体験: Issue回答でフックを開発するとき、このフローを厳密に守ります。
1. Issueを読む（gh issue view）
2. 既存フックに似た実装がないか探す
3. 新フックの設計を決める（イベント、条件、出力）
4. テストを先に書く
5. フックを実装
6. テスト実行で検証
7. Issue回答コメントを投稿
公式の注意書きも重要: 「スコープが明確で修正が小さいなら、計画をスキップしていい」。タイポ修正に計画モードは過剰です。
6. サブエージェントは「コンテキスト保護」のため
Since context is your fundamental constraint, subagents are one of the most powerful tools available.
公式がサブエージェントを推奨する理由は調査結果でメインのコンテキスト窓を汚染しないためです。
実体験: Issue回答の候補を探すとき、50件のIssueを1つずつ読むとコンテキストが埋まります。サブエージェントに「リアクション5以上のIssue一覧を取得して」と委任すると、メインセッションのコンテキストは結果サマリーだけで済みます。
公式の新機能: .claude/agents/ にカスタムサブエージェントを定義できるようになりました。
---
name: security-reviewer
description: Reviews code for security vulnerabilities
tools: Read, Grep, Glob, Bash
model: opus
---
セキュリティの観点からコードをレビューしてください。
これは「書いたフックが本当に安全か」のレビューに使えそうです。
7. 「よくある失敗パターン」は全部経験した
公式が挙げる5つの失敗パターン:
| パターン | 私の経験 |
|---|---|
| キッチンシンクセッション: 無関係なタスクを1セッションに詰め込む | 3時間セッションで25フック開発+記事16本+数値統一。後半の品質低下 |
| 何度も修正: 同じミスを繰り返し修正 | フック名の命名規則違反を3回修正。/clearして最初から書き直した方が速かった |
| CLAUDE.md肥大化: 重要なルールが埋もれる | 100行超のCLAUDE.mdでセキュリティルールが無視されたことがある |
| 信頼→検証のギャップ: 検証なしで実装を信頼 | テスト必須の運用で解決済み |
| 無限探索: スコープなしの調査でコンテキスト消費 | サブエージェント委任で解決済み |
公式の対策: 2回修正しても直らなかったら /clear して最初から。これは本当にそう。
まとめ: 公式と実践の差分
| 公式の推奨 | 実践で学んだ補足 |
|---|---|
| CLAUDE.mdを簡潔に | スキルへの分離が本命。100行→30行に削れる |
| フックで強制 | 655本の実例あり。cc-safe-setupで即導入可 |
| テストで検証 | 1フック18.8テストが目安。エッジケースほど重要 |
| サブエージェント活用 | 調査だけでなくレビューにも使える |
/clearでリセット |
自律セッションではフックで自動検知→警告が現実的 |
公式ベストプラクティスは「なぜそうすべきか」の理論。フック655本は「どう実現するか」の実装。両方あって初めてClaude Codeが本領を発揮します。
設定が正しいか不安な方へ
無料で診断: npx cc-health-check で安全スコアを即座に確認できます。プロによる詳細レビュー（$50〜）も受付中。
📖 AIで事業を回す実体験を全記録 → Claude Code×個人事業 800時間の全記録（¥800・第2章まで無料）
自分のトークン消費パターンを確認したい方へ
Token Checkupで5つの質問に答えるだけでトークン消費の診断ができる。Hook Selectorで最適なhookセットも分かる。
🚀 cc-safe-setupがProduct Huntに登場 — Claude Codeの安全hookを一発でインストール。701 hooks / 56セクションのSurvival Guide / 無料ツール7個。upvoteで応援お願いします！
📖 トークン消費に困っているなら → Claude Codeのトークン消費を半分にする——800時間の運用データから見つけた実践テクニック（¥2,500・第1章無料）| Ko-fi $17
📖 非エンジニアがClaude Codeで事業を回した全記録（¥800） — $800のAIコストで¥6,000を稼ぐまでの失敗と改善。第2章まで無料
⚠️ Opus 4.7緊急情報（2026年4月17日）
Opus 4.7のauto mode安全分類器がOpus 4.6にハードコードされている問題が発覚。3日間で23件以上のデータ損失。さらにv2.1.100以降、APIコールごとに約20,000トークンが見えない場所で追加課金されている問題も判明（#46917、GitHub上196件のリアクション）（50GB永久消失含む）。4倍のトークン消費も報告されている。対策: npx cc-safe-setup --opus47（Survival Guide / Safety Scanner）