Claude Code を触り始めて「思ったより賢いな」と感じたあと、次に来るのが「これをチームで使いこなすにはどう設計すればいいのか」という悩みではないでしょうか。個人利用なら頭の中の文脈で補えますが、複数人のリポジトリでは、ルールを言語化しないとあっという間に「人によってAIの動きが違う」という事態になります。
本記事では、入門記事の次の一歩として、CLAUDE.md・カスタムエージェント・MCP/フックという三つの仕組みを「どう役割分担させるか」という観点で整理します。
この記事で分かること
- CLAUDE.mdを「個人メモ」から「チームの暗黙知」に育てるための階層設計の考え方
- カスタムエージェント・サブエージェント・スラッシュコマンドの責任分担をどう切るか
- MCPサーバーとフックのどちらで自動化すべきかを判断する具体的な基準
- 運用してみると分かる、ありがちな落とし穴と回避策
なぜ「使ってみた」で止まってしまうのか
Claude Code 導入直後によくある失敗は、「便利な機能を全部詰め込もうとして、結局ルールが守られなくなる」というパターンです。CLAUDE.md に細かいコーディング規約を書き、カスタムエージェントを5本も6本も作り、フックでlintまで走らせる。動いているうちは気持ちいいのですが、PR の指摘事項が増えるたびに CLAUDE.md は肥大化し、誰も読まなくなります。
ここで意識したいのは、Claude Code はあくまで「文脈に従って動く実行者」であり、ルールの設計責任はチームにあるということです。つまり「何を覚えさせるか」より「何を覚えさせないか」を決めるほうが、長く回る運用になります。
CLAUDE.md は三層で考える
CLAUDE.md は「リポジトリ直下」「サブディレクトリ」「ユーザーグローバル(~/.claude/CLAUDE.md)」の三層で読み込まれます。多くの現場ではリポジトリ直下に全部書きがちですが、責務を分けて配置すると変更が楽になります。
| 層 | 書く内容 | 例 |
|---|---|---|
| ユーザーグローバル | 個人の好み、ツール選択 | 「日本語で応答」「git push の前に確認」 |
| リポジトリ直下 | プロジェクト共通の不変ルール | アーキテクチャの方針、禁止依存 |
| サブディレクトリ | その配下だけの局所ルール |
frontend/ の状態管理規約 |
ポイントは、リポジトリ直下の CLAUDE.md には「コードを読めば分かること」を書かないことです。アーキテクチャの大原則や、リポジトリ全体に効く非自明な制約だけに絞り、レビューで揉めた論点が出るたびに追加していく運用に切り替えると、メンテ負荷がぐっと下がります。
サブディレクトリ CLAUDE.md の使いどころ
たとえばモノレポで packages/api/ と packages/web/ を持っている場合、それぞれの配下に CLAUDE.md を置いてしまうのが効きます。
<!-- packages/api/CLAUDE.md -->
## このディレクトリの制約
- DBアクセスは必ず `src/repository/` 経由とし、ハンドラから直接Prismaを呼ばない
- 例外は `AppError` のサブクラスに正規化してから throw する
- テストは `*.integration.test.ts` を Postgres コンテナで実行する
この記述があれば、Claude Code が packages/api/ 配下を編集する際にだけこの制約を踏まえてくれます。逆に packages/web/ のフロント作業時には読み込まれないので、不要な制約でモデルの判断を曇らせずに済むのが利点です。
カスタムエージェントの分担を「責任の粒度」で切る
カスタムエージェント(サブエージェント)を作るときの判断基準は、**「メインの会話文脈から切り離したいかどうか」**で考えると分かりやすいです。具体的には次のような場面が候補になります。
- 大量のファイルを読み込む探索系タスク(メイン文脈を圧迫したくない)
- 独立した役割で動かしたい専門家タスク(レビュアー、テスト書き、SQLチューナーなど)
- 並列で走らせたい独立タスク
逆に、「メインの会話で人間がレビューしながら進めたい作業」はサブエージェントに切り出さないほうが結果が良くなります。エージェントを増やしすぎると、人間側の認知負荷も上がるからです。
スラッシュコマンドとの使い分け
スラッシュコマンドは「同じプロンプトを何度も叩く作業」を畳むためのもので、独立したエージェントとは別物です。次のように使い分けるとシンプルです。
スラッシュコマンド: プロンプトのテンプレ化(/review-pr, /write-tests)
サブエージェント: 独立した文脈・専門責務(コードレビュアー、リサーチャー)
スラッシュコマンドの中でサブエージェントを呼ぶこともできるので、「/review-pr を叩くと、レビュアーエージェントが起動してPR差分を独立文脈でレビューする」といった組み合わせが綺麗に決まります。
MCPサーバーとフックの判断軸
外部システムと連携する自動化は、MCPサーバーで実装するか、フック(PreToolUse / PostToolUse / Stop など)で実装するかの選択を迫られます。基準はシンプルで、**「モデルに判断させたいか、決定論的に走らせたいか」**で切ります。
| 仕組み | 向いている用途 | 例 |
|---|---|---|
| MCPサーバー | モデルが文脈に応じて呼び分けたい | DBクエリ、Issueトラッカー、社内Wiki検索 |
| フック | 必ず実行したい・絶対に止めたい処理 | 編集後にprettier、push前にlint、機密ファイルの保護 |
フックで「絶対に守らせたい規律」を担保し、MCPで「賢く使い分けたい連携」を提供する。この役割分担を意識すると、CLAUDE.md に「pushの前にテスト書いてね」のようなあいまいな指示を書かなくて済みます。守らせたいなら、お願いではなくフックにしてしまうのが運用上は強いです。
ありがちな落とし穴
実際にチーム導入してから気づくことの多い、いくつかの落とし穴を挙げておきます。
- CLAUDE.md の肥大化: 「指示を増やせば賢くなる」と錯覚しがちですが、矛盾する指示が混ざると逆に判断が鈍ります。月に1度は棚卸ししましょう。
- エージェントの過剰分割: 「テスト書き」「実装」「リファクタ」を別エージェントにすると、文脈共有のコストが跳ね上がります。最初は1〜2本で十分です。
- フックでの過剰な禁止: 何でもかんでもブロックすると、モデルが自己修復できず止まります。フックは「最後の砦」だけに絞るのが現実解です。
-
個人設定とチーム設定の混在:
~/.claude/CLAUDE.mdに書くべき個人の好みを、リポジトリ直下に書いてしまうケース。レビューでは「これは個人設定では?」を確認ポイントにすると良いです。
まとめ
最後に要点を振り返ります。
- CLAUDE.md は三層に分割し、「コードを読めば分かること」は書かない方針で運用する
- カスタムエージェントは「メイン文脈から切り離す価値があるか」で粒度を決める
- スラッシュコマンドはプロンプトの定型化、サブエージェントは責務の分離、と役割を分ける
- 外部連携はMCP、規律の担保はフックで切り分け、CLAUDE.mdに頼りすぎない
- ルールは増やすより捨てるほうが難しい。定期的な棚卸しを運用に組み込む
入門記事を一通り読んだあとは、自分のリポジトリの CLAUDE.md を見直して「今これは本当に必要な指示か?」を一行ずつ問い直してみてください。Claude Code を育てる作業は、結局のところチームの暗黙知を言語化する作業そのものだと気づくはずです。