Claude Code はターミナルで動く AI コーディングエージェントで、個人の生産性を引き上げる使い方は広く知られるようになった。一方で「チーム全体で使い倒す」段階に進むと、途端に難しさが跳ね上がる。エンジニアごとに使い方がばらつく、コンテキストが毎回ゼロから説明される、レビュー観点が共有されない、禁止したはずのコマンドを別のメンバーが動かしてしまう——こうした課題は、ツール選定ではなく「チームでの使い方を標準化できていない」ことが原因だ。

実際に導入に成功しているチームを観察すると、共通して 3 つの仕組みを整えている。プロジェクト単位のコンテキストファイル CLAUDE.md、再現性のある作業を切り出した Skills、ツール実行の前後に割り込める Hooks の 3 点セットである。この 3 つを揃えると、誰が会話を開始しても同じ品質で AI が動き、しかもチーム独自のナレッジが自動的に資産化されていく。

本記事では、Claude Code をチーム開発に定着させるための 3 つの仕組みを順に整備する手順と、導入後に陥りがちな落とし穴の回避策を紹介する。読み終えたころには、最初の 1 か月で何から始め、3 か月後にどのような運用に到達すべきかの全体像が把握できるはずだ。

チーム導入の出発点は CLAUDE.md の整備である。CLAUDE.md はプロジェクト共有のメモリとして置き、Claude Code は cwd から親ディレクトリへ遡って関連する CLAUDE.md を読み込む。個人設定は ~/.claude/CLAUDE.md に置くか、CLAUDE.md から @~/.claude/個別ファイル.md を import して使う。CLAUDE.local.md は deprecated ので、新規運用では使わない。サブディレクトリにある CLAUDE.md は、その配下のファイルを扱うときに参照される。ここに「このプロジェクトのスタック」「コーディング規約」「禁止事項」を書いておくと、会話のたびに説明し直す手間がなくなり、誰が実行してもブレない結果が得られるようになる。

CLAUDE.md がない状態でチーム導入を進めると、エンジニアごとに会話冒頭で書くプロンプトが異なってしまい、出力の品質が安定しない。結果として「AI は使えない」という評価が広がり、導入が頓挫する典型的なパターンに陥る。最初にこの共通基盤を作ることが、後工程のすべての成功を決める。

いきなり完成形を目指す必要はない。最初は最低限の情報だけを書き、運用しながら追記・分割していくのが現実的だ。プロジェクトが 1 週間動けば、CLAUDE.md に足りない情報が必ず見えてくる。

CLAUDE.md に書くべき内容は、大きく 4 種類に整理できる。

プロジェクト共有の指示は ./CLAUDE.md に置き、個人設定は ~/.claude/CLAUDE.md に分ける。旧来の CLAUDE.local.md は非推奨なので、必要があれば import を使って個別指示を参照する。

1 つ目はプロジェクトの概要で、技術スタック・パッケージマネージャー・開発サーバーの起動方法を 1 行ずつ明記する。「Next.js + Supabase + Tailwind」「pnpm 使用」「pnpm dev でポート 5000 で起動」のように、チーム全員が前提として扱っている情報を最優先で書く。

2 つ目はコーディング規約で、言語別のインデント、コメントの言語、命名規則を記述する。既存のリンター設定で担保されている部分は短く参照するだけでよく、リンターでは拾えない慣習（「コメントは日本語で書く」「関数名は英語」など）を重点的に書く。

3 つ目は禁止事項で、「npm ではなく pnpm を使う」「.env.local を編集しない」「rm -rf .next でキャッシュを削除しない」など、チームで合意済みのルールをそのまま書き下す。特に効果が大きいのが禁止事項だ。やってほしくないことを明示しておくと、AI がデフォルトで取りがちな選択肢を先回りして封じられる。

4 つ目はよく使うコマンドで、テスト・リント・型チェック・マイグレーション適用・デプロイなどのコマンドを短く列挙する。「どのコマンドでテストを走らせるか」を毎回質問される状態を避けられる。

CLAUDE.md が 200 行を超えたら、.claude/rules/ 配下にトピック別のファイルへ切り出す。典型的には coding/、testing/、security/、git/ のようにカテゴリ別フォルダを作り、1 トピック 1 ファイルで snake_case で命名する。

ここで読み込み方式を整理しておきたい。CLAUDE.md からは @path/to/file.md で補助ファイルを import できる。条件付きで使い分けたい指示は、用途に応じて CLAUDE.md の中で整理するか、別の手段として subagent や slash command に切り出す。

ルールを分割する理由は 3 つある。1 つは毎回全ルールを読み込むとコンテキスト窓を浪費すること、2 つ目はファイルごとに担当者や更新タイミングが変わっても差分が追いやすくなること、3 つ目は paths: で条件付き読み込みにできることだ。たとえばテスト関連のルールはテストファイル編集時にだけ読み込むように設定でき、常時読み込みの総量を抑えられる。

チームが大きくなるほど、分割のメリットは指数的に効いてくる。目安として、CLAUDE.md から import している常時読み込みルールの総行数は 200 行以内に収め、それを超える内容はすべて paths 付きの条件付き読み込みにする運用が機能しやすい。

CLAUDE.md で「ルール」を揃えたら、次は「よくやる作業」を Skills に切り出して資産化する。再利用したい作業は、明示的に呼び出すなら .claude/commands/*.md の slash command に、特化した自律タスクなら .claude/agents/*.md の subagent に分ける。チーム共通の手順は、用途ごとにどちらへ切り出すかを統一して運用する。

テストの一斉実行、リリースノートの生成、コードレビューの観点チェック、データベースマイグレーションの作成など、再現性のある作業は、明示実行が必要なものは slash command、特化した自律タスクは subagent に切り出し、チーム共通の手順として運用する。必要に応じて、公式の Skills 管理機能の最新仕様も確認したうえで、再利用可能なワークフローを整理するとよい。

再現性のある手順は slash command か subagent に切り分けて形式知化する。どちらを使うかは、明示実行が必要か、自動委譲が適切かで決める。「リリース前のチェックはあの人に聞かないと分からない」状態を、Skill のドキュメントに落とし込めば、レビュー品質がチーム全体で底上げされる。

個人用の特化タスクはユーザー設定で管理し、プロジェクト共有の再利用タスクはリポジトリ内で共有する。サブエージェントはタスク単位で定義し、保存場所と命名規則は Claude Code の最新公式仕様に合わせて運用する。サブエージェントの設定は、先頭の YAML frontmatter に name と description を書き、必要に応じてツール権限を設定する。権限制御は Claude Code の設定ファイル側で管理し、タスク本文には手順だけを記述する。ツール権限は個別の設定やサブエージェントの設定で管理する。本体にはステップ手順を順序立てて書き下す。命名はタスクが一目で分かる動詞または名詞句にする（例: review-pr、test-suite-runner、db-migration-author）。

ここで allowed-tools の意味を取り違えないように注意したい。allowed-tools は「その Skill の実行中に、ユーザー確認なしで使ってよいツールを事前承認する」設定であり、ツールの利用を制限するための仕組みではない。たとえば allowed-tools: Read, Grep, Glob と書いても、別のツールが呼ばれないわけではなく、確認ステップが省略されるのが Read・Grep・Glob だけ、という意味になる。書き換えを本当に禁止したい場合は、settings.json の permissions で deny ルールを明示するか、pre フックで Edit/Write をブロックする、といった別の仕組みで担保する必要がある。

SKILL.md の本体は「何を受け取るか」「どの順序で実行するか」「何を返すか」の 3 点を構造化して書く。ステップ内に判断分岐がある場合は表形式で条件を整理すると、AI が手順をブレなく追える。200 行を超えるような大きな Skill は、詳細パターンを REFERENCE.md など supporting files に分離する Progressive Disclosure パターンを使うと、description バジェットを圧迫せずに済む。

チーム共通の Skill はリポジトリ内の .claude/skills/ に置いてコミットし、個人用は ~/.claude/skills/ に置くと管理が楽になる。

Skills は便利だが、数が増えすぎると Claude が「どの Skill を使うべきか」を見失う。説明文は短く保ち、何をするか・いつ使うか・どのキーワードで呼ぶかを簡潔に書く。メタデータ上限は公式の最新仕様を別途確認し、運用では冗長な説明を避ける。運用上はこの上限に依存しすぎず、個々の description を短く刈り込む方向で揃えるのが安全だ。

個々の description は「何をするか」「いつ使うか」「どのキーワードでトリガーするか」の 3 要素を含め、冗長な前置きは削る。

良い description の例は「テストスイートを並列実行し、失敗を実装の問題とテストの問題に分類する。テスト実行、全テスト、一括テスト、CI 確認、テスト診断が必要な場合に使用。」のように、トリガーワードを末尾に列挙する書き方だ。逆に「このスキルはプロジェクトにおけるテスト実行を支援するための機能を提供します」のような抽象的な description は、発見されにくい。

description が類似した Skill が複数あると、Claude がどちらを呼ぶか迷う原因になる。定期的に使われていない Skill を棚卸しし、用途が被るものは統合する運用ルールを決めておくとよい。四半期に一度、Skill の利用統計をレビューする機会を作ると、肥大化を抑えられる。

最後の仕上げは Hooks だ。Hooks は PreToolUse、PostToolUse、Stop、SessionEnd に加え、必要に応じて Notification や UserPromptSubmit も使い分ける。設定は ~/.claude/settings.json または .claude/settings.json に置き、イベントごとに役割を分けて設計する。人間がレビューで毎回チェックしていた観点を機械的に強制できるため、品質ゲートの自動化と通知連携に大きな効果がある。

Hooks が効くのは、CLAUDE.md と Skills が「指示」であるのに対し、Hooks が「強制」である点だ。ルールに書いてあっても守られないケースでも、Hooks なら機械的に検知して止められる。セキュリティ要件や型安全性など、人手でのチェックが漏れると事故に繋がる領域で特に価値が出る。

最も使いどころが多いのは、ツール実行の直前・直後に走る pre/post フックだ。ファイル編集後の検証は PostToolUse に対して必要なコマンドを設定し、対象ファイル種別ごとに軽量なチェックを走らせる。重い検証は CI に逃がし、フックは短時間で終わる処理に絞る。

具体例として、TypeScript ファイル編集後に pnpm exec tsc --noEmit を走らせ、型エラーがあれば内容を AI に返して修正させる、という構成が考えられる。これだけで、型違反のコミットが実質ゼロになるチームは珍しくない。

pre フックは危険な操作をブロックするのに向いている。Bash ツールの pre フックで rm -rf、git push --force、DROP TABLE といった破壊的コマンドを検知して止める、といった防御ラインを貼ると、事故を未然に防げる。

注意点は「重いコマンドは走らせない」こと。テストスイート全体をここで回すと会話体験が破綻する。pre/post フックには秒単位で終わる検証のみを置き、長時間のチェックは CI に任せる分担にする。

Stop フックは Claude の応答が完了したタイミングの後処理に使い、会話セッション全体の終了は SessionEnd、通知用途は Notification を使い分ける。ここでいう「ターン終了」は会話セッション全体の終了ではなく、Claude が「このターンの応答を打ち終えた」と判断した時点で発火するイベントである点に注意したい。セッション全体の終了を捉えたい場合は SessionEnd フック、ユーザー入力待ちで通知したい場合は Notification フックと使い分けるのが公式の設計になっている。

Stop フックの典型的な使い道は、ターンごとの作業内容を Slack に投稿する、変更したファイル一覧をローカルのログに書き出す、ツール実行ログを構造化して追記する、といった軽量な後処理だ。

長時間タスクの完了通知を受け取りたい場合は、Stop よりも Notification フックのほうが用途に合う。入力待ちで止まったタイミングに curl で Slack や Discord の Webhook を叩くワンライナーで十分機能する。チーム全員に通知すると騒がしくなるので、個人チャンネルや DM への送信に留めるのが無難である。

監査用途で Stop フックを使う例も増えている。ターンごとのサマリーとツール実行ログを構造化してファイルに追記し、月次で集計すると、どの Skill がよく使われているか、どのようなタスクに時間がかかっているかを定量把握できる。このデータが、次の Skill 作成や CLAUDE.md 改善のネタになる。

3 つのステップを踏んでも、導入後に壁にぶつかるチームは多い。ここでは頻出する 2 つの失敗パターンを取り上げ、それぞれの回避策をまとめる。いずれも「仕組みを作ったあとに運用を回せない」ことが根本原因で、事前に対策を知っておけば避けられる。

最も多い失敗はコンテキストが肥大化し、1 会話あたりのトークン消費が跳ね上がるケースだ。CLAUDE.md に「とりあえず全部書く」を続けると、起動時に毎回数万トークンが消費される。対策は、常時読み込むルールと条件付きで読み込むルールを分けること。ファイルパターンごとに読み込むルールは paths: フロントマターで絞り込み、常時読み込みは 200 行以内を目安に抑える。

肥大化のサインは 3 つある。1 つ目は 1 会話の完了までに想定の 2 倍以上のトークンを消費するようになる、2 つ目は応答時間が明らかに遅くなる、3 つ目はルールに書いてあるはずの制約を AI が無視し始める（コンテキスト窓の後半が注意から漏れる現象）。このサインが出たら、まず CLAUDE.md を読み返し、削除できる項目がないか棚卸しする。

定期的に「このルールは本当に毎回必要か？」を棚卸しする習慣を作ると、自然にスリム化が進む。月次レトロで CLAUDE.md の変更履歴を確認し、追加されただけのルールがないか見直すとよい。

もう 1 つの失敗は、AI が書いたコードのレビューが人間任せのまま残ってしまうケースだ。Hooks で自動検証を仕込んでも、レビュー観点がチームで合意されていなければ、AI の出力に対する指摘がレビュアーごとにばらつき、次の改善に繋がらない。

対策は、レビュー観点を専用の Skill（例: /review）に落とし込み、AI にもレビュアーにも同じチェックリストで見させることだ。たとえば「セキュリティチェック」「型安全性」「テスト追加」「パフォーマンスへの影響」の 4 観点に絞った Skill を作り、プルリクエスト作成時に AI に実行させる。人間のレビュアーも同じ観点で見ることで、指摘の粒度が揃う。

指摘が揃うと、次に CLAUDE.md に追記すべきルールが見えてきて、継続的な改善ループが回り始める。レビューで頻出する指摘は、遅かれ早かれ CLAUDE.md の禁止事項か、新しい Skill の元ネタになる。このループが回っているチームは、3 か月で明らかに出力品質の中央値が上がる。

仕組みを作っても、成果を測らなければ経営層への説明責任が果たせない。導入効果を定量化する指標と、改善を継続するためのレトロスペクティブの進め方を押さえておく。測定の目的は、数字で競うことではなく、次の改善点を見つけるシグナルを得ることだ。

KPI は「利用率」と「品質」の 2 軸で設計する。利用率は、週あたりの会話数・Skill の呼び出し回数・コミットのうち AI 支援ありの割合など。品質は、レビュー差し戻し率・テストカバレッジの変化・デプロイ後のバグ発生率などを追う。

具体的な目標値の例として、導入 3 か月後に「エンジニア 1 人あたり週 10 会話以上」「リリースノート・マイグレーションなど定型作業の 70% 以上を Skill 経由で実施」「レビューでの差し戻し率 20% 以下」などが、最初の到達点として現実的だ。この数値はチームの規模や開発スタイルで調整する。

定着のロードマップは、導入 1 か月で CLAUDE.md の整備、2 か月目で Skills を 3〜5 本作成、3 か月目で Hooks とレビュー Skill の連携、という段階を踏むとスムーズだ。月 1 回の短いレトロで「今月追加したルール・Skill」と「効果の手応え」を共有すれば、チーム全体の習熟度が揃ってくる。3 か月を超えたら、「CLAUDE.md の更新頻度」や「Skill の利用率」自体をメタ指標として追うと、運用の健全性が見える。

Q1. CLAUDE.md と README.md の使い分けは？

README.md は人間向けの案内、CLAUDE.md は AI 向けの作業指示と棲み分ける。人間が読むべき概要・貢献方法は README.md に残し、AI に毎回守らせたいルールは CLAUDE.md に集約する。両方に同じ内容を書くと更新漏れの温床になるため、参照で繋ぐのが望ましい。CLAUDE.md から README.md を参照させる、あるいは README.md に「AI 向けルールは CLAUDE.md を参照」と一行書くだけで十分役割分担できる。

Q2. プロジェクトの Skills とグローバルの Skills はどちらに置くべきか？

再現性を重視するならプロジェクト配下（.claude/skills/）に置いてリポジトリにコミットするのが第一選択。特定プロジェクトに依存しない汎用的な Skill のみグローバル（~/.claude/skills/）に置く。迷ったらプロジェクト配下に置き、他プロジェクトでも欲しいと感じた時点でグローバルに昇格させる運用がシンプルだ。

Q3. Hooks が重くて会話が止まるときは？

pre/post フックは秒単位で終わるコマンドのみに絞り、長時間のチェックは CI に移す。どうしてもローカルで走らせたい処理は、バックグラウンド実行にして結果だけ通知する設計にする。Hooks 内で複数のコマンドを直列実行する場合は、失敗時に即座に中断する設計にして、遅い処理を早期に切り捨てる。

Q4. チームメンバーごとに使い方が違ってしまう場合は？

ルールと Skills をリポジトリにコミットし、CI で「CLAUDE.md のリンク切れがない」「Skills の description バジェット超過がない」を検査する。ツールで強制できない振る舞いは、月次レトロで共有して摺り合わせる。特に新メンバーが入った直後は、過去のレトロ議事録を眺めるだけでチームの暗黙知がある程度伝わる。

Q5. 既存プロジェクトへ後から導入するときの注意点は？

既存の README やドキュメントと重複する情報は CLAUDE.md に書かない。重複を避けないと、更新時にどちらが正か分からなくなる。最初の 2 週間は、CLAUDE.md への追記と既存ドキュメントからの削除・リンク化をセットで進めると、情報の分散を防げる。

Claude Code をチームに定着させる鍵は、ツールそのものの使い方ではなく「何を標準化するか」にある。CLAUDE.md でプロジェクトのルールを揃え、Skills で繰り返し作業を資産化し、Hooks で品質ゲートを自動化する——この 3 点セットが揃えば、誰が会話を開始しても同じ品質の出力が得られるようになる。

導入初月は CLAUDE.md の整備に集中し、2 か月目で Skills を数本作り、3 か月目で Hooks と KPI 計測を加える段階的なロードマップを敷けば、3 か月後には「AI が前提のチーム開発」に移行できる。

大切なのは、最初から完璧な仕組みを目指さないことだ。最小限の CLAUDE.md で走り始め、週次のレビューで気づいた点を追記し、月次で棚卸しする。このリズムを作れば、チーム固有のナレッジが自動的に CLAUDE.md と Skills に集約され、ドキュメントが生きた資産に変わっていく。小さく始めて、棚卸しと改善を繰り返すことが、長く使い続けられる運用の出発点となる。