Claude Code Best Practice
Claude Code の設定・スキル・サブエージェントと Command → Agent → Skill オーケストレーションのリファレンス。
何か
claude-code-best-practice は、Claude Code（claude.ai/code）向けのベストプラクティスとリファレンス実装を集めたリポジトリだ。アプリ本体ではなく「設定・スキル・サブエージェント・フック・コマンド」のパターンを示す参考実装として使う。
Commandsワークフロー入口
Subagents分離コンテキスト
Skills知識・ツール注入
Hooksイベント駆動
機能と配置
| 機能 | 配置 | 説明 |
|---|---|---|
| Commands | .claude/commands/<name>.md | ユーザーが呼ぶスラッシュコマンド。既存コンテキストにプロンプトを注入し、ワークフローの入口になる。 |
| Subagents | .claude/agents/<name>.md | 独立したコンテキストで動くエージェント。ツール・権限・モデル・メモリを個別に設定できる。 |
| Skills | .claude/skills/<name>/SKILL.md | 知識や手順を注入。エージェントにプリロード（agent skill）したり、Skill ツールで直接呼び出したりできる。 |
| Hooks | .claude/hooks/ | PreToolUse / PostToolUse / SessionStart など、イベント発火時にエージェントループ外で実行するスクリプト（例: サウンド通知）。 |
| MCP | .claude/settings.json, .mcp.json | Model Context Protocol で外部ツール・DB・API に接続する。 |
| Settings | .claude/settings.json | 権限・モデル・出力スタイル・サンドボックス・キーバインドなど階層的に上書きされる。 |
サブエージェント同士の呼び出しは bash ではなく Agent ツールで行う。Agent(subagent_type="agent-name", description="...", prompt="...", model="haiku") のように明示する。
Weather 例
リポジトリ内の Weather システムが、Command → Agent → Skill の流れを実演している。
- Command
/weather-orchestrator: 入口。ユーザーに C/F を聞き、Agent ツールで weather-agent を起動し、返ってきた温度で Skill ツールで weather-svg-creator を呼ぶ。 - Agent
weather-agent: プリロードされたweather-fetcherスキルで Open-Meteo から温度を取得。 - Skill
weather-svg-creator: SVG カードとoutput.mdを生成し、orchestration-workflow/に書き出す。
ここで「エージェントにプリロードされるスキル」と「コマンドから直接呼ぶスキル」の二種類が一つのフローで使われている。
実行例
claude
/weather-orchestrator
設定の優先順位
上から強い順: Managed（MDM 等）→ コマンドライン引数 → .claude/settings.local.json（gitignore）→ .claude/settings.json → ~/.claude/settings.json。Hooks は hooks-config.local.json が hooks-config.json を上書きする。
ワークフロー上のポイント
- CLAUDE.md は 200 行以内を目安にし、必要なら
.claude/rules/に分割する。 - ワークフローは「コマンド」を入口にし、サブエージェントは用途ごとにスキルを載せた特化型にする。
- コンテキスト使用率がおおよそ 50% を超える前に手動で
/compactする。 - 複雑なタスクは plan mode で始め、検証可能な単位でタスクを細かくする。
サブエージェントの起動: サブエージェントから別サブエージェントを「bash で起動」してはいけない。必ず
Agent(...) ツールを使う。