この記事を書いた理由
Claude Code を業務で使い始めてしばらく経つが、「なんとなく動いている」状態から抜け出せていないチームと、明らかに生産性が上がっているチームの差が、何に起因するのかずっと気になっていた。
モデルの性能ではなかった。差が出ていたのは、Claude Code の周囲に何を整えているか、という部分だった。この記事では、大規模コードベースへの導入で効くことを、自分なりに整理した記録として残しておく。
Claude Code はコードベースをどう読むのか
まず前提として把握しておきたいのは、Claude Code の探索方式だ。
Claude Code はローカルのファイルシステムを直接たどる。必要なファイルを読み、grep のような検索で該当箇所を見つけ、参照を追いかけながら理解を進める。コードベース全体のインデックスをベクトルDBに事前に作る方式ではない。
この方式の利点は、「今この瞬間のコードを見る」ことだ。RAGベースのツールは埋め込みの更新が開発速度に追いつかず、すでに名前が変わった関数や削除済みのモジュールを返すことがある。Claude Code はその代わりに、ファイルシステムを直接見るので常に最新のコードを対象にできる。
ただし、この方式には前提がある。Claude Code がどこを見るべきかを最初に判断できるだけの文脈が必要だ、ということだ。曖昧な依頼をそのまま巨大なコードベースへ投げると、探索だけでコンテキストウィンドウを消耗する。「今触る範囲に寄せて始める」ことが、大規模コードベースでの基本的な姿勢になる。
「モデルよりハーネスが効く」という整理
大規模コードベースでの Claude Code の性能は、モデル単体よりも周囲の設定・拡張の方が大きく左右する。
このモデル周辺の設定・拡張のまとまりを「ハーネス」と呼ぶ。ハーネスを構成する拡張ポイントは以下の5つだ。
- CLAUDE.md：毎回読まれる共通知識
- フック（Hooks）：イベント発生時に自動で走る処理
- スキル（Skills）：必要なときだけ読まれる専門知識
- プラグイン（Plugins）：スキル・フック・サブエージェントの配布単位
- MCPサーバー：社内ツールや外部データへの接続口
加えて、LSP連携がシンボル単位の正確な探索を支え、サブエージェントが探索と編集を文脈ごと分離する。
重要なのは、これらを全部最初から盛り込まないことだ。各拡張ポイントには適切な順番があり、レイヤーの役割を混在させると毎セッション不要な情報を読み込んで重くなったり、チームのノウハウが属人化したりする。
CLAUDE.md の設計：全員が毎回読むファイルだからこそ薄く保つ
CLAUDE.md はすべてのセッションで自動的に読み込まれる。裏を返せば、1行ごとにコンテキストコストがかかる。
CLAUDE.md に書くべきもの
- 技術スタックの概要とエントリポイントの場所
- ビルド・テスト・lintのコマンド（曖昧に書かない。
npm testよりnpm run test:unitの方がいい） - 命名規則・インポート順序・エラーハンドリングのパターン
- 踏んではいけない地雷（非推奨API、廃止されたパターン）
- チームの全員が知っておくべきことのみ
CLAUDE.md に書いてはいけないもの
- プロジェクトの歴史・背景・哲学
- 特定のタスクにしか使わない専門知識（→スキルに分ける）
- 200行を超えるような長大な説明
目安として、CLAUDE.md が200行を超えたら、専門的な内容をスキルに切り出すタイミングだ。
モノレポの場合は階層化する
Claude Code はディレクトリを移動しながら CLAUDE.md を加算的に読むので、サブディレクトリに CLAUDE.md を置いても、ルートの情報は失われない。ルートには全体像と共通の注意点だけを置き、サブディレクトリにはそれぞれのローカルな慣習を書く、という分割が機能する。
モノレポでは「ルートから始める」のではなく「今触る範囲のサブディレクトリから始める」方が探索効率が上がる。
フック（Hooks）：「禁止スクリプト」ではなく「自動改善の仕組み」として使う
フックを「Claude が変なことをしないための番人」として使っているチームが多いが、より価値が高い使い方は継続改善だ。
代表的なフックの種類と使いどころ
| フック名 | 発火タイミング | 主な用途 |
|---|---|---|
| UserPromptSubmit | プロンプト送信時 | プロンプトのブロック・加工 |
| PreToolUse | ツール実行前 | セキュリティチェック、危険コマンドのブロック |
| PostToolUse | ツール実行後 | フォーマッタの自動実行、ログ記録 |
| Stop | セッション終了時 | CLAUDE.md 更新の提案、振り返りの記録 |
特にストップフックの活用が効果的だ。セッション終了時に「今回のセッションで気づいたことを CLAUDE.md に追加すべきか」を確認させると、文脈がまだ新鮮なうちにドキュメントを育てられる。
スタートフックで動的なコンテキストを注入する
スタートフックを使うと、開発者ごと・モジュールごとに必要な文脈を動的に読み込める。全員が同じ CLAUDE.md を手動で設定しなくても、「このサブディレクトリにいるときは自動でこの設定を読む」という運用ができる。
lintやフォーマットの自動化にもフックは有効で、Claude の指示の解釈に依存するよりも確実に実行される。
スキル（Skills）：「毎回教えなくていい専門知識」の置き場所
スキルはプログレッシブディスクロージャーで動く。セッション開始時にはスキルの名前と説明（約100トークン）だけが読まれ、タスクの内容がスキルの説明と合致したときに初めて本体が読まれる。
スキルに向いているのは、「毎回は使わないが、使うときは詳しく必要な手順」だ。
スキルに切り出すべき内容の例
- マイグレーションの手順（「うちのマイグレーションはこう書く」）
- リリースフロー（「本番リリース前のチェックリスト」）
- インシデント対応の手順
- アクセシビリティチェックのパターン
- APIドキュメントの更新手順
スキルのファイル構成は .claude/skills/<名前>/SKILL.md で、YAMLフロントマターに名前・説明・使用するツールのリストを書く。
判断の目安は「同じ指示を Claude に2回書いたことがあるなら、最初の時点でスキルにすべきだった」という基準がシンプルでわかりやすい。
LSP連携：大規模コードベースでの探索精度を上げる
大規模コードベースで共通名の関数を grep すると膨大な候補が返る。LSP（Language Server Protocol）があれば、同名でも別シンボルを区別して定義ジャンプや参照検索が使える。
言語別の対応例は次の通りだ。
- TypeScript → TypeScript Language Server
- Python → Pyright
- C/C++ → clangd
- Java → Eclipse JDT Language Server
多言語コードベースでは、LSPの導入が投資対効果の高い改善になりやすい。Claude Code にはLSPプラグインの仕組みがあり、言語サーバーをつなぐとシンボル単位のコード理解が可能になる。
サブエージェント：探索と編集のコンテキストを分離する
サブエージェントは、新しい独立したコンテキストウィンドウでタスクを実行し、結果のサマリだけをメインセッションに返す仕組みだ。
サブエージェントを使うべき場面
- 大量のドキュメントやファイルを読んで調査したいとき（探索のノイズでメインセッションを汚染しない）
- 複数の実装案を並行して検討したいとき
- PRレビューやテスト実行を並列で走らせたいとき
使い分けの基準は次のように整理できる。
- 「毎ターン適用すべきルール」→ CLAUDE.md
- 「たまにしか使わない手順」→ スキル
- 「イベントで自動化したい処理」→ フック
- 「探索・調査・ノイズの多い作業」→ サブエージェント
MCPサーバー：外部接続は「基本が動いてから」追加する
MCPサーバーは社内ツール・データベース・外部APIへの接続口だ。Slack、GitHub、社内Wikiなど、Claude Code が直接触れない情報源へのブリッジとして機能する。
ただし、「MCP接続を作る前に基本を動かすべきだ」という優先順位が重要だ。派手な外部接続より先に、Claude Code が今のコードベースを読みやすい状態にすることが先決だ。MCPが有効なのは、CLAUDE.md・フック・スキルの基盤が整った後の話だ。
設定は「固定資産」だと思わない
以前のモデル向けに書いた指示が、新しいモデルでは過剰な制約になることがある。
たとえば「リファクタリングは必ず単一ファイルの変更に分ける」というルールは、以前は安全策でも、より高性能なモデルでは複数ファイルをまたぐ整合的な変更を妨げる可能性がある。
実運用では3〜6ヶ月ごと、または大きなモデルアップデートの後に設定の棚卸しをすることを勧めたい。追加した設定ばかり気になりがちだが、「余計な補助輪を外す」メンテナンスも同じくらい重要だ。
導入の責任者を決める
技術設定だけでは導入は広がらない。
現場から使い始めるだけでは、便利な設定やノウハウが個人に閉じてしまいやすい。最低限、DRI（Directly Responsible Individual）を1人置くべきだ。その人が担うのは以下の範囲だ。
- CLAUDE.md の運用方針の管理
- 承認済みスキル・プラグインのカタログ管理
- 権限ポリシーの設定
- チーム間でのノウハウ共有の仕組みづくり
大規模組織では、「どのスキルを許可するか」「AIが作ったコードをどのレビュー工程に乗せるか」という統制の論点も早めに出てくる。最初から承認済みスキルの集合と必須のレビュー工程を決め、信頼度に応じてアクセスを広げていく流れが安定しやすい。
どこから始めるか、具体的な順番
整理すると、最初の一歩はこの順番で考えるのが現実的だ。
- ルートとサブディレクトリの
CLAUDE.mdを整理する（薄く、具体的に） - サブディレクトリ単位でテスト・lint・ビルドのコマンドを分ける
- 生成ファイル・ビルド生成物・外部コードを
.ignore系設定で除外する - ディレクトリ構造だけでは把握しにくい場合は、ルートにコードベースの地図を置く
- 可能なら LSP を導入してシンボル単位の探索を有効にする
- よく繰り返す手順をスキルに切り出す
- 自動化すべき処理をフックに落とす
- 運用責任者（DRI）を決める
- そこまで整ってからプラグイン・MCPサーバーを追加する
振り返って
「Claude Code が賢くなれば勝手にうまくいく」という期待は、大規模コードベースでは成立しにくい。精度の差はモデルではなく、Claude Code がどれだけ迷わずに必要な文脈へたどり着けるかに左右される。
今回整理できたのは、CLAUDE.md の設計・フック・スキル・LSP・サブエージェントの役割分担だ。
まだ自分の中で整理しきれていないのは、プラグインの配布設計だ。チーム内でスキルやフックを共有するプラグインの粒度をどう決めるか、実際に運用して検証していきたい。
この記事を書いた人について
株式会社Flexibilityでエンジニアをしています。
DX推進・システム開発を軸に、エンジニアが自律的に動ける環境を大事にしている会社です。
技術的に面白いことをやっていきたい方や、働き方に柔軟さを求めている方は、
よかったら一度のぞいてみてください。
- 会社サイト: https://www.flexi-inc.com/
- Qiita Organization: https://qiita.com/organizations/flexi-inc