結論: Claude Code Best Practicesとは、CLAUDE.md・Hooks・Plugins・Subagentの4層を設計原則に従って組み合わせることで、AIコーディング環境の品質・速度・コストをすべて最適化する実践知識体系です。
この記事の要点:
- 要点1: CLAUDE.mdは「200行以内・削れる行は全部削る」がAnthropic公式の鉄則（長すぎると重要ルールが無視される）
- 要点2: Hooksは「アドバイスではなく強制」——CLAUDEへの指示では守られないが、Hookは100%実行される
- 要点3: コスト管理と/clearの使い方を知るだけで月次利用料を40〜70%削減できる
対象読者: Claude Codeを導入済み・使い始めた中小企業のエンジニア・非エンジニア担当者、法人でのチーム展開を検討している責任者
読了後にできること: 本記事の10原則をもとに、今日からCLAUDE.mdとHooksの設定を見直し、チームで再現性ある開発環境を構築できる
「Claude Codeを使い始めたけど、なんか思ったより指示を聞かないな…」
先日、ある企業のシステム部門でClaude Codeの社内展開を支援しているとき、担当者からこんな声を聞きました。CLAUDE.mdに詳しいコーディングルールを書いたのに、Claudeが全然従ってくれない。プロンプトを使うたびに同じ説明を繰り返している。コストも想定より高い——。
その方のCLAUDE.mdを見せてもらったら、すぐ原因が分かりました。700行以上ありました。Anthropicが公式に「200行以内を目安に」と推奨しているのに、全プロジェクトのドキュメント解説・APIリファレンス・コーディング規約のすべてを詰め込んでいたんです。これだと、重要なルールが「ノイズ」に埋もれて、Claude自身が読み飛ばすようになります。
逆に、Best Practicesを正しく理解して設計し直した後は、同じチームが「指示に対する応答精度が明らかに上がった」「繰り返し説明が不要になった」と報告してくれました。Claude Codeはツールの使い方より、設計思想を理解することが先です。
この記事では、Anthropic公式ドキュメント（code.claude.com/docs）を完全精読した上で、100社以上の法人AI研修・導入支援で得た現場知見を加えた10原則を体系的に解説します。CLAUDE.md・Hooks・Plugins・Subagent・MCP・Skill・セキュリティ・コスト・チーム共有・レビューの全領域をカバーします。コピペで使える設定例7つと、よくある失敗パターン4つも収録しています（参照日: 2026-06-04）。
まず、Claude Codeの全体像を把握しておきたい方は【2026年最新】Claude Code完全ガイドもあわせてご覧ください。
Claude Code Best Practicesの全体マップ
Claude Code Best Practicesを理解する前に、「なぜBest Practicesが必要なのか」を押さえておく必要があります。
Claude Codeは従来のチャットボットと根本的に異なります。ファイルを読み・コマンドを実行し・変更を加え・自律的に問題を解決します。この「自律性」はパワフルである一方、最大の制約がコンテキストウィンドウです。
Anthropic公式が明言しています。「LLMの性能はコンテキストが埋まるにつれて低下する。コンテキストウィンドウこそが最も重要なリソースだ」と。デバッグセッション1回で数万トークンを消費することもあります。Best Practicesの多くは、このコンテキスト管理という一点に帰結します。
10原則は次の4層構造で整理できます：
| 層 | 原則 | キーワード |
|---|---|---|
| 設定層 | 原則1〜2 | CLAUDE.md・Hooks |
| 拡張層 | 原則3〜5 | Plugins・Subagent・MCP・Skill |
| 運用層 | 原則6〜8 | セキュリティ・コスト・チーム共有 |
| 品質層 | 原則9〜10 | プロンプト設計・レビュー |
原則1: CLAUDE.mdは「削除できる行はすべて削除する」
Anthropic公式の鉄則：200行以内、1行ごとに問い直す
CLAUDE.mdはClaudeが毎セッション開始時に読み込む特殊ファイルです。プロジェクトの作業慣行・技術的な判断・「このプロジェクトのやり方」を伝える唯一の場所です。
Anthropic公式ドキュメント（code.claude.com/docs/en/best-practices、参照日: 2026-06-04）は、CLAUDE.md設計で最も重要なルールを明確に述べています：
「各行について問い直せ：この行を削除したらClaudeが間違いを犯すか？そうでなければ削除せよ。膨らんだCLAUDE.mdはClaudeが重要な指示を無視する原因になる」
つまり、削除してもClaudeが正しく動くなら、その行は不要なのです。
書くべき内容 vs 書いてはいけない内容
| 書くべき内容 ✅ | 書いてはいけない内容 ❌ |
|---|---|
| Claudeが推測できないBashコマンド | コードを読めば分かること |
| デフォルトと異なるコードスタイル規則 | Claudeが既に知っている標準的言語規約 |
| テスト指示・優先するテストランナー | 詳細なAPIドキュメント（リンクを貼るべき） |
| リポジトリのエチケット（ブランチ命名・PR規約） | 頻繁に変更される情報 |
| プロジェクト固有のアーキテクチャ判断 | 長い説明やチュートリアル |
| 開発環境の癖（必要な環境変数） | コードベースのファイル一覧説明 |
コピペ可能: 実際のCLAUDE.mdテンプレ（ES Modules / TypeScript版）
# コードスタイル
- ES modules (import/export) を使う。CommonJS (require) は使わない
- 可能な限りdestructure import: import { foo } from 'bar'
- TypeScript strict モード必須: tsconfig.json の strict: true
# ワークフロー
- 変更後は必ずtypecheckを実行: npx tsc --noEmit
- テスト実行は単体テストのみ（全スイートは実行しない）
- コミット前に npm run lint を通すこと
# プロジェクト固有
- 環境変数: .env.local を参照。直接ハードコードNG
- APIエンドポイント: /api/v2/ 配下のみ使用
# 詳細ガイド
- Gitワークフロー: @docs/git-workflow.md
- APIコンベンション: @docs/api-conventions.md
ポイントは@path/to/file でのインポート構文を活用することです。詳細なドキュメントは外部ファイルに分離し、CLAUDE.mdはポインタだけを持つ設計にすると、本体を短く保てます。
CLAUDE.mdを置ける場所（多層設計）
~/.claude/CLAUDE.md— 全セッションに適用（個人設定）./CLAUDE.md— プロジェクトルート（チーム共有、gitにコミット）./CLAUDE.local.md— プロジェクト固有の個人メモ（.gitignore推奨）- 子ディレクトリの
CLAUDE.md— Claudeが当該ディレクトリのファイルを読む際に自動読み込み
モノレポではルートと各サブディレクトリの両方に置けます。
【失敗パターン1】CLAUDE.mdの肥大化
❌ よくある間違い：全社コーディング規約・APIリファレンス・FAQ・オンボーディング資料をすべてCLAUDE.mdに詰め込む（700行超）
⭕ 正しいアプローチ：CLAUDE.mdは200行以内。専門的なドキュメントはSkillsに移す（後述の原則5参照）。1行追加するごとに「この行がなければ何か壊れるか？」と自問する
なぜ重要か: CLAUDE.mdは毎セッションのコンテキストに全ロードされます。長すぎると重要なルールが埋もれ、Claudeが実際には指示を「読んでいない」状態になります
原則2: Hooksは「アドバイスではなく強制」——毎回必ず実行される自動化ゲート
Hooksとは何か
Hooks（フック）は2026年初頭にリリースされた、Claude Codeのライフサイクルの特定ポイントで自動実行されるユーザー定義コマンド・HTTPエンドポイント・LLMプロンプトです（出典: Anthropic Claude Code Hooks公式ドキュメント code.claude.com/docs/en/hooks、参照日: 2026-06-04）。
CLAUDE.mdの指示はアドバイス（Claudeが従うかどうかは状況次第）。一方、HooksはClaude Code自体のライフサイクルに直接組み込まれる強制処理です。例外なく実行されます。
5種類のHookイベント（ライフサイクル）
| タイミング | イベント名 | 典型的な使用例 |
|---|---|---|
| セッション開始 | SessionStart | ブランチ情報・未解決Issueのロード |
| セッション終了 | SessionEnd | ログ記録・作業サマリー生成 |
| ツール実行前 | PreToolUse | 危険コマンドのブロック（唯一のブロック可能Hook） |
| ツール実行後 | PostToolUse | Lint・テスト・フォーマットの自動実行 |
| セッション停止前 | Stop | テスト合格まで停止をブロック |
4種類のHookハンドラー
- command: シェルスクリプト（最も汎用）
- http: HTTPエンドポイントへのPOST（外部サービス連携）
- mcp_tool: 接続済みMCPサーバーのツール呼び出し
- prompt: Claude自身へのYes/No評価プロンプト
コピペ可能: settings.json Hooks設定例（ESLint自動実行）
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [
{
"type": "command",
"command": "npm run lint -- --fix ${CLAUDE_TOOL_INPUT_PATH} && echo 'Lint OK'"
}
]
}
],
"PreToolUse": [
{
"matcher": "Bash",
"hooks": [
{
"type": "command",
"command": "${CLAUDE_PROJECT_DIR}/.claude/hooks/block-dangerous.sh"
}
]
}
]
}
}
コピペ可能: 危険コマンドブロックHookスクリプト
#!/bin/bash
# .claude/hooks/block-dangerous.sh
COMMAND=$(echo "$CLAUDE_TOOL_INPUT" | jq -r '.command // empty')
# rm -rf / df など危険パターンをブロック
if echo "$COMMAND" | grep -qE 'rms+-rfs+/|DROPs+TABLE|shutdown|reboot'; then
echo "安全上の理由でブロックしました: $COMMAND" >&2
exit 2 # exit 2 = ブロッキングエラー（Claudeに通知される）
fi
exit 0
exit 2はブロッキングエラーです。Claudeとユーザーの両方にエラー内容が表示され、処理が停止します。exit 0は成功、それ以外は非ブロッキングエラー（処理は継続）です。
Hookの設定場所と共有範囲
| 場所 | 適用範囲 | チーム共有 |
|---|---|---|
~/.claude/settings.json | 全プロジェクト | 不可（個人マシン限定） |
.claude/settings.json | 単一プロジェクト | 可（gitコミット） |
.claude/settings.local.json | 単一プロジェクト | 不可（gitignore推奨） |
チームで共通ルールを強制したい場合は.claude/settings.jsonにHookを定義してgitにコミットします。
【失敗パターン2】HookでのInfinite Loop
❌ よくある間違い：PostToolUse(Write)でファイルを書き換えるHookを設定 → そのWriteがまた同じHookを発火 → 無限ループ
⭕ 正しいアプローチ：Hookスクリプト内でファイルを変更する場合は、専用の「Hook用ファイル」を作るか、環境変数で「Hookによる書き込み」フラグを立てて二重発火を防ぐ
なぜ重要か: Claude Code自体が無限ループに気づいて自動停止するまで時間がかかり、その間ずっとAPIコストが発生し続けます
原則3: Pluginsは「設定不要の即戦力」——インストールだけで機能が追加される
PluginsとはSkills・Hooks・Subagents・MCPのバンドル
Pluginsは、Skills（プロンプトベースの知識）・Hooks（自動化ゲート）・Subagents（専門エージェント）・MCPサーバー（外部ツール連携）を1つのインストール可能ユニットにまとめたものです（出典: code.claude.com/docs/en/plugins、参照日: 2026-06-04）。
コミュニティおよびAnthropicが提供するPluginは、/pluginコマンドでマーケットプレイスを閲覧できます。
今すぐ使えるPlugin例
- Code Intelligence: TypeScript・Python等の型安全なシンボルナビゲーションと自動エラー検出。静的型付け言語のプロジェクトなら即インストール推奨
- GitHub統合: gh CLIとの連携を深め、Issue・PR・コメントをClaude Codeから直接操作
- Database Query: DBスキーマを読み込み、SQLクエリの生成・実行を支援
コピペ可能: Plugin設定の構造
## Plugin ディレクトリ構造（例: my-plugin）
.claude/plugins/my-plugin/
├── PLUGIN.md # メタデータ（name, description, version）
├── hooks/
│ └── hooks.json # Hookイベント定義
├── skills/
│ └── api-conventions/
│ └── SKILL.md # 再利用可能なスキル定義
├── agents/
│ └── reviewer.md # サブエージェント定義
└── mcp/
└── config.json # MCPサーバー設定
PluginとSkillの使い分け
「Pluginは配布・再利用に向いたコンテナ、Skillは単体の専門知識」と覚えてください。チーム内で使う自分たちのルールはSkillで定義し、外部に配布したり複数のコンポーネントをまとめる場合はPluginにします。
詳しいPlugins運用についてはClaude Code Plugins完全ガイド2026を参照してください。
原則4: Subagentsは「コンテキストの汚染を防ぐ専門家」——調査は別コンテキストで
Subagentsとはなにか
Subagents（サブエージェント）は、独自のコンテキストウィンドウと許可ツールセットを持つ専門エージェントです（.claude/agents/配下に定義）。メインセッションとは独立して動作し、作業後に要約をメインに返します。
なぜ重要か？ — コードベースを調査するとき、Claudeは大量のファイルを読み込みます。それがすべてメインセッションのコンテキストに入ると、実装に使えるコンテキストが急速に消費されます。Subagentsは「調査の汚れ」をメインに持ち込まない設計です。
コピペ可能: セキュリティレビューSubagent定義
---
name: security-reviewer
description: コードセキュリティ脆弱性をレビュー。SQLインジェクション・XSS・認証バグ・シークレット漏洩に特化
tools: Read, Grep, Glob, Bash
model: opus
---
あなたはシニアセキュリティエンジニアです。以下を確認してください：
- インジェクション脆弱性（SQL, XSS, コマンドインジェクション）
- 認証・認可の欠陥
- コード内のシークレット・クレデンシャル
- 安全でないデータハンドリング
具体的な行番号と修正提案を日本語で報告してください。
利用するには：Use a subagent to review this code for security issues. とメインセッションで指示するだけです。
Subagentの効果的な使い方（3パターン）
- コードベース調査: 「認証システムのトークンリフレッシュ処理を調査してサマリーを返して」→ 大量ファイル読込の汚染ゼロ
- 品質検証: Writer/Reviewer パターン——実装したClaudeとは別のSubagentが差分をレビュー。実装バイアスなしの客観的評価
- 並列実行: 独立したタスクを複数Subagentに同時委任してスループット向上
【失敗パターン3】Subagentの過剰委任
❌ よくある間違い：あらゆるタスクをSubagentに委任する。単純な1ファイル修正も「念のため」でSubagentを起動
⭕ 正しいアプローチ：Subagentを使うべき条件は「大量ファイル読込が必要な調査」か「実装とは独立した検証・レビュー」の2ケースに絞る。それ以外はメインセッションで直接処理する方が速くてコストも低い
なぜ重要か: Subagentの起動には追加のAPIコストが発生します。単純タスクへの過剰適用は費用対効果が悪くなります
原則5: MCPとSkillは「CLAUDE.mdの分離戦略」——on-demandロードで基礎コンテキストを守る
MCP（Model Context Protocol）——Claudeに外部ツールを与える
MCPサーバーはClaude Codeに全く新しいツールを追加します。Notionへのアクセス・DBクエリ・Figmaデザイン取得・監視ダッシュボードの分析など、Claude Code自体が持たない能力を外部プロセス経由で付与する仕組みです。
# MCPサーバーの追加（Notion連携の例）
claude mcp add notion
# 設定確認
claude mcp list
MCPサーバーはプロセスベース（独立したプロセスとして動作）、Skillはプロンプトベース（ClaudeのプロンプトコンテキストへのインジェクションはClaude自体が処理）という根本的な違いがあります。
Skills——on-demandで専門知識をロード
CLAUDE.mdは毎セッション全ロードされます。一方、Skillsは「必要なときだけ」ロードされます（.claude/skills/配下に定義、または/skill-nameで直接呼び出し）。
PRレビューのフロー・DBマイグレーションの手順・特定フレームワークのコンベンションなど、常時必要ではない専門ワークフローはSkillsに移すことで、CLAUDE.mdを軽量に保てます。
コピペ可能: API設計コンベンション Skill定義
---
name: api-conventions
description: 自社REST APIの設計規約。新規エンドポイント作成時に自動適用
---
# API設計規約
## URLパス
- ケバブケースを使用: /user-profiles/ ✅ /userProfiles/ ❌
- バージョニングはURLパスに: /v1/users/, /v2/users/
- リソース名は複数形: /users/ ✅ /user/ ❌
## JSONプロパティ
- キャメルケース: userId ✅ user_id ❌
- 日時はISO8601: "2026-06-04T09:00:00Z"
## リストエンドポイント
- 必ずページネーション: ?page=1&per_page=20
- レスポンスに total, page, per_page を含める
## エラーレスポンス
{ "error": "error_code", "message": "人間が読めるメッセージ", "details": {} }
原則6: セキュリティはHooksとPermissionsで「構造的に」担保する
Permission Modesの3択
Claude Codeはデフォルトで、ファイル書き込み・Bashコマンド・MCPツール実行などシステム変更の可能性があるアクションに対して毎回許可を求めます。これは安全ですが、10回目には形骸化します。
Anthropicは3つの許可モードを提供しています（出典: code.claude.com/docs/en/best-practices、参照日: 2026-06-04）：
- Auto Mode: 別の分類モデルがコマンドをレビューし、リスクのあるものだけをブロック。日常作業の確認ダイアログを排除しつつ安全を担保
- Permission Allowlists: 安全と判断した特定ツール・コマンドを許可リストに追加（例: npm run lint, git commit）
- Sandboxing: OS レベルのサンドボックスでファイルシステム・ネットワークアクセスを制限。Claude が制限内で自由に動作
コピペ可能: 安全なsettings.json（許可リスト設定）
{
"permissions": {
"allow": [
"Bash(npm run lint)",
"Bash(npm run test:unit)",
"Bash(git add *)",
"Bash(git commit *)",
"Bash(git diff *)",
"Bash(git status)",
"Bash(cat *)",
"Bash(ls *)",
"Read(*)",
"Glob(*)"
],
"deny": [
"Bash(rm -rf *)",
"Bash(curl * | bash)",
"Bash(wget * -O- | sh)",
"Bash(sudo *)"
]
}
}
企業導入でのセキュリティ設計の優先順位
法人でClaude Codeを展開する場合、セキュリティ設計は次の優先順位で考えます：
- Denyリストで危険コマンド・パターンをブロック（PreToolUse Hook）
- Allowリストで安全と確認したコマンドを明示的に許可
- 本番環境・機密データへのアクセスはSandboxingで物理的に遮断
- CLAUDE.mdにシークレット取り扱い禁止ルールを明記（補助的）
セキュリティ設定の詳細についてはClaude Code セキュリティ設定完全ガイド2026もご参照ください。
原則7: コスト管理の「3つのレバー」——/clear・Skill分離・Thinking制御
コストの実態
Anthropicが公開しているエンタープライズ利用統計によれば、平均的なエンジニアのClaude Code利用コストは1アクティブ日あたり約13ドル、月間150〜250ドル（90%のユーザーは月30ドル/日以下）とされています（出典: code.claude.com/docs/en/costs、参照日: 2026-06-04）。
正しくBest Practicesを実践すると、これを40〜70%削減できます。
レバー1: /clearの戦略的な使い方
最も即効性が高いのが/clearの使い方です。無関係なタスクに切り替える際は必ず/clearを使います。
典型的な無駄パターン：
- あるバグ修正セッション（大量ファイル読込済み）のまま、全然違うドキュメント生成タスクを依頼 → バグ修正の残骸コンテキストがノイズになりClaude品質が下がりトークンも無駄
- 2回以上同じ間違いを修正しているのに/clearしない → 失敗アプローチが蓄積されてさらに悪化
コピペ可能: /btw（サイドクエスチョン）の活用
# 通常の質問（コンテキストに入る）
"この関数のアルゴリズム複雑度は？"
# /btwで聞く（コンテキストに入らない）
/btw "この関数のアルゴリズム複雑度は？"
/btwはオーバーレイで回答を表示し、会話履歴には一切入りません。詳細の確認・軽い疑問解消には/btwを使うだけでコンテキスト節約になります。
レバー2: CLAUDE.mdを200行以内に保つ（直接的なコスト削減）
Anthropicの試算によれば、300〜500ワード（約200行目安）のCLAUDE.mdは、毎セッションの最初の説明を不要にし、セッションあたり500〜2,000トークンを節約します。一方で肥大化したCLAUDE.mdはセッションごとに余分なトークンを消費し続けます。
レバー3: Extended Thinking（推論モード）の制御
拡張思考（Thinking）は出力トークンとして課金されます。デフォルトの予算は「深く考える」タスクでは数万トークンになることも。
# 思考レベルを下げる（簡単なタスクに）
/effort low
# 思考を無効化
/config thinking=false
# 最大トークン数を制限
export MAX_THINKING_TOKENS=8000
単純な1ファイル編集・変数名変更・ログ追加などでは思考を無効化するとコストが大幅に下がります。
5ステップ: TCO（総保有コスト）試算フロー
- 現状把握:
/usageで今のトークン使用量確認。ステータスラインに常時表示設定 - ベースライン計測: 1週間の実使用コストを記録
- /clearルールの確立: タスク切替時の/clearをチームの作業標準として文書化
- CLAUDE.md最適化: 200行以下に削減し1週間の効果計測
- Extended Thinking設定: タスク種別ごとに最適なレベルを設定し効果計測
原則8: チーム共有の設計——gitで管理すべきファイルとすべきでないファイル
gitにコミットすべきファイル
| ファイル | 用途 | コミット |
|---|---|---|
CLAUDE.md | プロジェクト規約・チーム共通ルール | ✅ 必須 |
.claude/settings.json | チーム共通のHooks・Permission設定 | ✅ 必須 |
.claude/agents/*.md | チームで使う専門Subagent定義 | ✅ 推奨 |
.claude/skills/*/SKILL.md | プロジェクト固有のSkill定義 | ✅ 推奨 |
CLAUDE.local.md | 個人メモ・個人設定 | ❌ .gitignore |
.claude/settings.local.json | 個人のPermission設定 | ❌ .gitignore |
CLAUDE.mdの「gitコミット」によるチーム効果
Anthropic公式が強調しているのが「CLAUDE.mdをgitにコミットすること」です。これにより：
- チームメンバー全員が同じClaude動作を得られる
- プロジェクト規約がコードと一緒にバージョン管理される
- 新メンバーのオンボーディング時に「Claudeへの教育」が自動化される
- CLAUDE.mdの改善をPRレビューで品質管理できる
コピペ可能: チーム展開時の.gitignore設定
# .gitignore への追加
CLAUDE.local.md
.claude/settings.local.json
.claude/tmp/
# APIキーや個人認証情報が入る可能性があるファイルは除外
.claude/mcp-credentials.json
原則9: プロンプト設計の「3つの上位法則」——探索・計画・実装の分離
上位法則1: 「探索してから計画、計画してから実装」
Anthropic公式のワークフローとして推奨されているのが、4フェーズ分離です（出典: code.claude.com/docs/en/best-practices、参照日: 2026-06-04）：
- Explore（探索）: Plan Modeでファイルを読む。変更はしない
- Plan（計画）: 詳細実装計画の策定。Ctrl+G でエディタに出してレビュー
- Implement（実装）: Plan Modeを解除して実装。テスト実行まで含める
- Commit（コミット）: 説明的なコミットメッセージでPR作成
ただし、1ファイル・単純タスク（タイポ修正・ログ追加）では計画フェーズは不要です。「変更を1文で説明できるなら計画を省く」が目安です。
上位法則2: 「検証手段をClaude自身に与える」
Claudeは「できたように見える」ところで止まります。テスト・ビルド・スクリーンショット比較など「パス/フェイル」が返るものを必ず渡してください。
# ❌ 曖昧な指示
"validateEmail関数を実装して"
# ✅ 検証付き指示
"validateEmail関数を実装して。テストケース: user@example.com は true、
invalid は false、user@.com は false。実装後にテストを実行して。"
上位法則3: 「2回修正してダメなら/clearして再スタート」
同じ問題を2回以上修正しているなら、コンテキストが失敗アプローチで汚染されています。/clearして、学んだことを組み込んだより具体的なプロンプトで再スタートする方が、蓄積修正を続けるより速く正確に解決できます。
コピペ可能: 「Claudeにインタビューさせる」大規模機能設計プロンプト
[機能の概要を1-2文で書く]を作りたいです。
AskUserQuestionツールを使って詳細にインタビューしてください。
技術実装・UI/UX・エッジケース・トレードオフについて質問してください。
明らかな質問は不要。私が考えていない難しい部分を掘り下げてください。
十分に話し合えたら、SPEC.mdに完全な仕様書を書き出してください。
この「Claudeにインタビューさせる」手法で、自分では気づかなかったエッジケースや技術的トレードオフが必ず出てきます。仕様書完成後、新規セッションで実装に移ります（実装用の清潔なコンテキスト確保のため）。
原則10: 「敵対的レビュー」——実装したClaudeとは別のコンテキストで検証する
なぜ実装したClaudeのセルフレビューは信頼できないか
実装を担当したClaudeは自分が作ったコードに「実装バイアス」があります。同じコンテキストのまま「このコードは正しいか？」と聞いても、客観的な検証になりません。
Anthropic公式の推奨は「別のSubagentコンテキストで差分を検証」です。レビュアーは差分と評価基準だけを見て、実装の理由を知りません。だから実装バイアスなしに評価できます。
コピペ可能: 敵対的レビュー指示プロンプト
Subagentを使って、この変更をPLAN.mdと照合してレビューしてください。
確認ポイント：
- すべての要件が実装されているか
- 記載のエッジケースにテストがあるか
- タスクのスコープ外の変更がないか
報告すること：ギャップのみ（スタイルの好みではなく正確性に影響するもの）
重要な注意: 「ギャップを見つけろ」と指示されたSubagentは、コードが正しくても何かを報告しようとします。「正確性または要件に影響するギャップのみ報告」と明示することが重要です。過剰なレビュー追求は過度な抽象化・防衛的コード・不要なテストの増殖を招きます。
Writer/Reviewerパターンの運用
大規模開発では「書くClaude」と「レビューするClaude」を別セッションで運用します：
| Session A（Writer） | Session B（Reviewer） |
|---|---|
| 「APIエンドポイントにレートリミッターを実装して」 | — |
| — | 「@src/middleware/rateLimiter.ts をレビュー。エッジケース・競合状態・既存ミドルウェアとの一貫性を確認」 |
| 「レビューフィードバック: [Session B出力] これらの問題に対処して」 | — |
【失敗パターン4】コスト爆発パターン
❌ よくある間違い：「調査してから実装して」と1プロンプトで両方を依頼 → コードベース全体を読み込んだ後に実装するため、コンテキストが調査ゴミで溢れてコスト爆発 + 品質低下
⭕ 正しいアプローチ：調査はSubagentに委任（別コンテキスト）、サマリーだけをメインセッションに受け取り、清潔なコンテキストで実装
なぜ重要か: コードベース調査で数万トークン消費した後に実装を始めると、コンテキストウィンドウの後半で実装しているためパフォーマンスが低下し、かつコストも最大化します
5ステップ: Best Practices実装フロー（今日から始める順番）
- CLAUDE.mdの棚卸し（Day 1）: 現在のCLAUDE.mdを全部読んで、「この行を削除したらClaudeが間違いを犯すか？」を1行ずつ問い直す。200行以下になるまで削除する。削除した内容はSkillsに移すか捨てる
- 基本Hooksの設定（Day 1〜2）: PostToolUse(Write/Edit)でLint自動実行。PreToolUse(Bash)で危険コマンドブロック。この2つだけで開発品質が大幅向上する
- /clearの習慣化（Day 2〜3）: タスク切替時・2回修正失敗時は必ず/clear。チームのワークフロー文書に明記する
- よく使うワークフローのSkill化（Day 3〜7）: PRレビュー手順・DBマイグレーション・デプロイチェックリスト等をSkillsに移動。CLAUDE.mdをさらに軽量化
- コスト計測と最適化（Day 7〜）: /usageでベースラインを計測し、1週間後の変化を確認。Extended Thinkingの設定をタスク種別ごとに調整
まとめ：10原則のクイックリファレンス
| 原則 | 核心ルール | 即効度 |
|---|---|---|
| 1. CLAUDE.md | 200行以内・削れる行は全部削る・@importで分離 | ★★★★★ |
| 2. Hooks | Lint/フォーマット/危険ブロックはHooksで強制 | ★★★★★ |
| 3. Plugins | /pluginで即使えるものから導入・型付き言語はCode Intelligenceを最初に | ★★★☆☆ |
| 4. Subagents | 調査と検証は別コンテキスト・実装はメインセッション | ★★★★☆ |
| 5. MCP・Skill | 常時不要な専門知識はSkillsへ・on-demandロードで基礎コンテキスト節約 | ★★★★☆ |
| 6. セキュリティ | Denyリスト→Allowリスト→Sandbox の優先順で設計 | ★★★★★ |
| 7. コスト | /clearの徹底・200行以内・Thinking制御で40〜70%削減 | ★★★★★ |
| 8. チーム共有 | CLAUDE.md・settings.jsonはgitコミット必須 | ★★★★☆ |
| 9. プロンプト設計 | 探索→計画→実装を分離・検証手段を必ず渡す | ★★★★★ |
| 10. レビュー | 敵対的Subagentレビュー・Writer/Reviewerパターン | ★★★☆☆ |
まとめ：今日から始める3つのアクション
- 今日やること: 現在のCLAUDE.mdを開いて、「削除してもClaudeが間違わない行」を全部削除する。まずは200行以下を目標に
- 今週中: settings.jsonにPostToolUse(Write)でLint実行・PreToolUse(Bash)で危険コマンドブロックの2つのHooksを設定する
- 今月中: チームでCLAUDE.mdをgitにコミットし、PRレビューで維持するフローを確立。Subagentを使ったWriter/Reviewerパターンを1つのプロジェクトで試す
あわせて読みたい:
- 【2026年最新】Claude Code完全ガイド — Claude Codeの全体像・始め方・基本操作
- Claude Code セキュリティ設定完全ガイド2026 — 法人導入時のセキュリティ設計詳細
- Claude Code Plugins完全ガイド2026 — Pluginsの詳細運用ガイド
参考・出典
- Best practices for Claude Code — Anthropic Claude Code Docs（参照日: 2026-06-04）
- Hooks — Claude Code Docs（参照日: 2026-06-04）
- Manage costs effectively — Claude Code Docs（参照日: 2026-06-04）
著者: 佐藤傑（さとう・すぐる）
株式会社Uravation代表取締役。X（@SuguruKun_ai）フォロワー約10万人。
100社以上の企業向けAI研修・導入支援。著書『AIエージェント仕事術』（SBクリエイティブ）。
SoftBank IT連載7回執筆（NewsPicks最大1,125ピックス）。
ご質問・ご相談は お問い合わせフォーム からお気軽にどうぞ。
