Claude Code Best Practice を徹底解剖
— コマンド・サブエージェント・スキル・フック・MCP・RPIをひとつの設計図として読む

1 このリポジトリは何者か

まず重要なのは、このリポジトリが「何を作るアプリか」ではなく、Claude Code をどう使いこなすかを体系化した参照実装だという点である。`README.md` と `CLAUDE.md` は、その意図をかなり明確に書いている。前者は巨大な索引であり、後者は「この repo はベストプラクティスのリファレンス実装である」と位置づけている。

実際に中身を数えると、これは思いつきで増殖したメモ群ではない。` .claude/agents `、` .claude/commands `、` .claude/skills `、` best-practice/ `、` reports/ `、` implementation/ `、` development-workflows/ `、` tips/ ` がそれぞれ役割分担されている。言い換えると、この repo の本体はコードよりもむしろ 構造化された運用知識 である。

ここが本 repo の第一の価値である。多くの「AI コーディング設定 repo」は、プロンプト断片や小手先の alias を並べて終わる。しかしこの repo は、規範・実装・検証・運用の4層を分けている。この分離があるから、知識がメンテナンス可能になり、チームで共有しやすくなる。

2 中核にある Command → Agent → Skill 設計

この repo を象徴するのが、`orchestration-workflow/orchestration-workflow.md` に明示された Command → Agent → Skill パターンである。ここでは weather デモが使われているが、主題は天気ではない。主題は、Claude Code の拡張要素をどう役割分担するかだ。

`reports/claude-agent-command-skill.md` も、この違いをかなり明瞭に整理している。Agent は別コンテキスト、Command は明示呼び出し、Skill は軽量かつ自動発火可能。つまりこの repo は、「全部 Skill に寄せる」でも「全部 Agent に投げる」でもなく、重さに応じて責務を分解する という発想で組まれている。

特に良いのは、Weather デモが「おもちゃ」に見えて実は設計原則のサンプルになっている点だ。`weather-orchestrator` は入口、`weather-agent` は自律的にデータ取得、`weather-fetcher` は事前注入された知識、`weather-svg-creator` は成果物生成に専念する。取得と描画を分け、しかも Agent 内 preloaded skill と 独立 Skill 呼び出し の二種類を同時に見せている。

この repo の核心は、AI を賢くすることではなく、AI に仕事を分担させる設計を持ち込むことだ。

3 コードと設定を読むと何が見えるか

文書だけを読むと「よく整理されたガイド repo」に見えるが、コードと設定を見ると性格がさらに分かる。特に ` .claude/settings.json `、` .mcp.json `、` .claude/hooks/scripts/hooks.py `、` .codex/hooks/scripts/hooks.py ` の4点は、この repo の運用思想をかなり雄弁に語っている。

フックスクリプトは「音を鳴らすだけ」ではない

`.claude/hooks/scripts/hooks.py` は見た目以上に丁寧だ。27 hook event の sound folder をマッピングし、OS ごとに再生方法を切り替え、`hooks-config.local.json` → `hooks-config.json` のフォールバックを持ち、JSONL ログも残す。さらに `git commit` だけ特別音に分岐し、agent hook 用に別 map まで用意している。

つまりこれは「賑やかし」ではない。Agent の内部状態を人間が知覚可能にするための運用観測レイヤーである。AI エージェント運用で本当に辛いのは、失敗したことより「今なにをやっているのか分からない」ことだ。この repo はそこを音・ログ・ステータスで補っている。

presentation-curator は静的 prompt を超えている

もうひとつ面白いのが `presentation-curator` agent である。これは単に「presentation を直す agent」ではない。`presentation/index.html` の構造、レベル遷移、スライド番号、関連 Skill の同期、さらに自分自身の Learnings 更新までタスクに入っている。ここでは agent が単なる worker ではなく、知識の自己同期機構 として設計されている。

この発想はかなり重要だ。AI エージェント運用の難しさは、性能よりも知識ドリフトにある。この repo は「作業が終わったら自分の Skill とルールも直せ」という構造で、ドリフトを局所的に潰そうとしている。

4 RPI・Cross-Model・オーケストレーションの実務性

README の派手さに対して、本 repo の実用性を支えているのは `development-workflows/` である。特に RPI と Cross-Model Workflow は、「Claude Code をどうチーム手順に組み込むか」に対して、かなり実務的な答えを出している。

RPI で良いのは、単に phases を増やしたことではない。`rpi/{feature}/` に調査・要件・UX・技術設計・実装記録を残すので、会話を artifact に変換する。Agentic 開発では「その場では分かったが翌週には消えている」問題が頻発する。この repo はそこを markdown artifact で止血しようとしている。

一方 Cross-Model Workflow は、AI を単一人格として扱わない。Claude が得意な計画と、Codex が得意な計画レビュー・実装検証を分ける。これは人間のチーム編成に近い。大事なのは「どちらが上か」ではなく、どこで視点を切り替えるか をワークフローに埋め込んでいることだ。

5 Memory / Settings / Monorepo への視線が深い

本 repo の強みは機能網羅だけではない。`best-practice/claude-memory.md`、`reports/claude-skills-for-larger-mono-repos.md`、`reports/claude-global-vs-project-settings.md` は、Claude Code を大規模利用したときにぶつかる本質的な論点を丁寧に分解している。

CLAUDE.md を「一枚の長文」にしない

多くの現場では `CLAUDE.md` を神棚のように肥大化させて破綻する。この repo はそこをかなり意識していて、200 行以内の推奨、ancestor / descendant loading、rules 分割、project / local / user のスコープ分離を一貫して説明している。つまり「Claude に全部覚えさせる」のではなく、どの知識をいつ読み込ませるかを設計する という思想だ。

Skill も CLAUDE.md と同じようには扱わない

`reports/claude-skills-for-larger-mono-repos.md` は特に良い。CLAUDE.md が ancestor loading なのに対し、Skill は nested discovery で見つかること、description だけが常時文脈に乗り、全文は invocation 時に読むことを整理している。これは monorepo で非常に重要だ。全部の skill を最初から読み込めば、文脈はすぐに膨れる。

Global と Project を混ぜない

`reports/claude-global-vs-project-settings.md` は、Tasks / Agent Teams / Auto Memory / Credentials など global-only なものと、Settings / Rules / Agents / Commands / Skills / Hooks の dual-scope を分けている。ここで repo が伝えたいのは単純で、個人状態とチーム共有設定を混ぜるな ということだ。

6 このリポジトリが優れている理由

では、なぜこの repo は多くの Claude Code repo の中でも参照価値が高いのか。結論から言えば、「AI を賢く使う」話を、運用設計の話まで落としているから である。

さらに README は、他の大型 workflow repo との比較表まで持っている。Everything Claude Code、Superpowers、Spec Kit、gstack、HumanLayer などを横並びにし、自 repo の特徴を相対化している。これは重要だ。自分の設計を絶対視せず、設計空間の中で自分の位置を明示している repo は強い。

ただし、万能テンプレートではない

褒めるだけで終わると誤読になる。この repo はかなり情報量が多く、README も非常に長い。そのため、Claude Code 初学者が丸ごとコピーすると、むしろ重すぎる可能性がある。また permissions の allow 範囲は広めなので、そのまま導入するなら各社のリスク許容度に合わせて削る必要がある。

7 何を先に取り入れるべきか

この repo を自社・自チームに取り込むなら、最初から全部入れる必要はない。むしろ次の順で入れると失敗しにくい。

1. CLAUDE.md / rules / settings の整理
   まず人間側の前提を Claude に渡す経路を整える。ここが崩れていると、Agent も Skill も安定しない。
2. よく使う内輪ワークフローを Command 化
   毎日繰り返す作業を slash command に落とし、繰り返し prompt を消す。
3. 特定領域にだけ Agent を切る
   コードレビュー、調査、UI 検証など、分離メリットが大きい領域から始める。
4. MCP は 2〜3 個に絞る
   Context7、Playwright、必要なら DeepWiki 程度で十分。盛りすぎは context を壊す。
5. フックは観測目的から入れる
   最初は block hook ではなく、logging / notification / formatting 程度でよい。

8 まとめ

claude-code-best-practice は、Claude Code の機能一覧 repo ではない。AI コーディングを「便利なチャット」から「運用可能な開発システム」へ押し上げるための設計書である。Commands、Agents、Skills、Hooks、MCP、Memory、RPI、Cross-Model Workflow が、ばらばらの小技としてではなく、ひとつの運用アーキテクチャとして接続されている。

その意味で、この repo が教えてくれる最も大きなことは「Claude Code に何ができるか」ではない。Claude Code をチームで壊れずに使い続けるには、どこに境界を引き、どこに知識を置き、どこに検証を入れるべきか である。そこまで踏み込んでいるから、この repo は流行の設定集ではなく、Agentic Engineering の実務教材になっている。