notes.kodachan.dev
← 一覧に戻る

Claude Code運用ベストプラクティス

#ClaudeCode#リファレンス

概要

Claude Code（Anthropic公式CLI）は、ファイル読み書き・コマンド実行・自律的な問題解決が可能なagentic coding環境。すべてのベストプラクティスは「コンテキストウィンドウ管理」という一つの制約に基づいており、コンテキストが満杯になるにつれてパフォーマンスが低下する。この制約を理解した上で、CLAUDE.md・hooks・スキル・サブエージェント・MCPを組み合わせることで、真に自動化されたワークフローが実現できる。

構造図

flowchart TD
    A["基本原則"]
    A --> B["コンテキスト節約の実践"]
    B --> C["これを削除したらClaudeがミスをするか？"]
    C --> D["詳細情報（DBスキーマ・API仕様）は別ファイルに分離"]
    D --> E["検証手段を必ず提供する（テストケース・期待出力等）"]
    E --> F["`cat error.log | claude` でデー.."]
    style F fill:#c05746,color:#fff,stroke:none

1. CLAUDE.mdの効果的な書き方

基本原則

  • LLMはステートレス：毎回のセッションで「初見」。CLAUDE.mdはその唯一の記憶装置
  • WHY/WHAT/HOW の3要素 を最初に書く：
    • WHAT：技術スタック・プロジェクト構造（迷子にならない地図）
    • WHY：プロジェクト目的・各コンポーネントの役割
    • HOW：検証方法（テスト・ビルドコマンド・型チェック）

サイズ・内容の指針

  • 300行以下、理想は60行程度
  • 各行に問い直す：「これを削除したらClaudeがミスをするか？」→ Noなら削除
  • 重要な情報は先頭に（LLMは先頭と末尾を重視する「Lost in the Middle」問題）

含めるべき vs 含めない

| 含める | 含めない | |------|--------| | 推測できないBashコマンド | コードを読めば分かること | | デフォルトと異なるコードスタイル | 標準的な言語規約 | | よくある落とし穴・非自明な動作 | 詳細なAPIドキュメント（→リンクを貼る） | | プロジェクト固有のアーキテクチャ決定 | 「クリーンなコードを書く」のような自明な指示 |

段階的開示（Progressive Disclosure）

  • 詳細情報（DBスキーマ・API仕様）は別ファイルに分離
  • CLAUDE.mdには参照ポインタだけ置く
  • @path/to/import 構文で追加ファイルをインポート可能

ファイル配置の階層構造

| 場所 | スコープ | |-----|--------| | ~/.claude/CLAUDE.md | 全プロジェクト共通 | | ./CLAUDE.md | プロジェクトルート（チーム共有） | | ./.claude/rules/*.md | パス固有ルール（YAMLフロントマターでglobパターン指定） | | ./CLAUDE.local.md | 個人設定（.gitignore対象） |

2. MCPサーバーの活用法

基本コマンド

claude mcp add [name] --scope user   # 追加
claude mcp list                      # 一覧
claude mcp remove [name]             # 削除
claude mcp serve                     # Claude自体をMCPサーバーとして起動

実用的なMCPサーバー例

| サーバー | 用途 | |--------|-----| | GitHub | PRワークフロー・Issue管理 | | Playwright | ブラウザ自動化・UIテスト | | Sentry | 本番エラー監視 | | PostgreSQL/Supabase | DB直接クエリ | | Notion/Google Calendar/Gmail | 情報管理・スケジュール |

ベストプラクティス

  • チーム共有：プロジェクトスコープ（.claude/settings.json）に記述
  • 信頼できるサーバーのみ有効化
  • MCPよりシンプルなCLIツール（gh, aws等）が使える場合はそちらを優先
  • claude mcp serve でClaude自体をMCPサーバーとしてオーケストレーション可能

3. Hooks（フック）の活用事例

フックは決定論的な制御を提供。CLAUDE.mdの指示と異なり、「必ず実行される」ことが保証される。

主要なフックイベント

| イベント | タイミング | |--------|---------| | SessionStart | セッション開始時 | | PreToolUse | ツール実行前（ブロック可能） | | PostToolUse | ツール実行後 | | Notification | Claude が入力待ち | | Stop | Claude が応答完了時 | | PreCompact / PostCompact | コンテキスト圧縮前後 |

3種類のフックタイプ

  • command：シェルコマンド実行（最も一般的）
  • prompt：LLM（Haiku）での判定
  • agent：サブエージェントでの複雑な検証
  • http：HTTPエンドポイントへのPOST

4. プロンプトの書き方のコツ

探索→計画→実装→コミットの4フェーズ

  1. 探索（Plan Mode / Shift+Tab）：ファイルを読み、変更なしで理解
  2. 計画：詳細な実装計画を作成
  3. 実装（Normal Mode）：計画に対して検証しながら実装
  4. コミット：説明的なメッセージでcommit → PR作成

具体的なコツ

  • ファイル名・スコープ・制約・例を明示する
  • @ファイル名 でファイルを参照
  • 画像をペーストしてUI検証に使う
  • 検証手段を必ず提供する（テストケース・期待出力等）

5. コンテキスト管理

主要コマンド

| コマンド | 用途 | |--------|-----| | /clear | 関連ないタスク間でリセット（最頻用） | | /compact | コンテキスト圧縮（平均70%削減） | | /rewind or Esc+Esc | チェックポイントに戻る | | claude --continue | 最新の会話を再開 | | claude --resume | 最近の会話から選択 |

コンテキスト節約の実践

  • 1タスク1セッションの原則
  • 同じ問題で2回失敗したら /clear して再スタート
  • サブエージェントで調査を別コンテキストに分離
  • 平均50,000トークン消費でリセット推奨

6. スキル（カスタムスラッシュコマンド）

.claude/skills/[name]/SKILL.md 形式が推奨。

フロントマターの主要フィールド

| フィールド | 用途 | |---------|-----| | disable-model-invocation: true | 手動トリガー専用 | | user-invocable: false | Claudeのみ使用 | | context: fork | サブエージェントとして独立コンテキストで実行 |

7. マルチエージェント・サブエージェントの活用

活用パターン

  • 調査の委譲：メインコンテキストを保護
  • Writer/Reviewerパターン：実装とレビューを分離
  • ヘッドレスモード（claude -p）でCI連携

注意：マルチエージェントはトークン消費が急増する。

8. セキュリティ・権限設定

3層の権限ルール（評価順：deny → ask → allow）

  • .claude/settings.json をチームで共有
  • rootで実行しない
  • --dangerously-skip-permissions は本番環境で使わない

9. IDE連携

  • VS Code: Cmd+Esc（Mac）/ Ctrl+Esc（Windows）で起動
  • 自動共有：現在ファイル・選択テキスト・Problemsパネルのエラー

10. コミュニティTips

  • awesome-claude-code（GitHub 21.6k stars）：スキル・フック・コマンドのキュレーション集
  • MCPのシンプル化：ステートレスなツールはCLIの方が良い
  • cat error.log | claude でデータをパイプ

ソース

  • [[Claude Code公式ベストプラクティス|https://code.claude.com/docs/ja/best-practices]]
  • [[Writing a good CLAUDE.md|https://www.humanlayer.dev/blog/writing-a-good-claude-md]]
  • [[50 Claude Code Tips|https://www.builder.io/blog/claude-code-tips-best-practices]]
  • [[awesome-claude-code|https://github.com/hesreallyhim/awesome-claude-code]]
  • [[Claude Codeベストプラクティス7つの鉄則|https://qiita.com/nogataka/items/392934f79e943e8b9228]]