言語 / 開発ツール · 最終検証 2026-05-16 · @anthropic-ai/claude-code 2.x · 初公開 2026-05-16

大規模コードベースの Claude Code — モデルではなくハーネスを設計する

Anthropic が「数百万行のモノレポ / レガシー / マイクロサービス分散」で Claude Code を回している企業を観察してまとめたベストプラクティスの日本語要約。CLAUDE.md / フック / スキル / プラグイン / LSP / MCP / サブエージェントの 7 層ハーネス、成功 3 共通パターン、そして同名スキルの優先順位(Enterprise > Personal > Project)の実用ルールまで。

claude-code ai-agents harness skills monorepo best-practices anthropic

著者:TechBook.net編集部

検証日: 2026-05-16

出典: Best Practices for Claude Code in Large Codebases — Anthropic(2026-05 公開、本記事は Anthropic 公式ブログの要約 + 実用追補)

対象: モノレポ / レガシー / 分散サービスのいずれかを抱える環境で Claude Code をチーム導入 したい開発リーダー、Developer Productivity / DX 担当

Anthropic が公開した「大規模コードベース版」のベストプラクティス記事を、実務に効く粒度 で日本語にまとめ直したもの。読み終えた時点で次の 3 つが手に入る:

Claude Code が 大規模 repo でどう動いて、なぜ RAG 系ツールと違う失敗の出方をするか
モデルではなくハーネス(model を取り巻くエコシステム)に投資すべき理由と、7 つの拡張ポイント
「同名スキルが複数箇所にある時、どれが勝つか」の優先順位ルール(地味だが踏み抜きやすい落とし穴)

ハーネスの全体像 — まずはこの図

Claude Code 単体は LLM クライアントに過ぎず、現場で「使える」状態にするには モデルの周りに 7 層の拡張(ハーネス、harness、ボディフレーム)を組む。各レイヤーは独立に強化でき、組み合わせて効く。

Claude Code の 7 層ハーネス — 中心の Model は固定資産、周辺レイヤーで現場適応する (クリックで拡大)

なぜ「agentic search」が大規模で効くか

Claude Code は 人間のエンジニアと同じ流儀でコードを探す: ファイルシステムを辿り、grep で必要箇所を見つけ、参照関係を追う。全部 開発者のローカルマシンで動作 し、コードベースを事前に server へアップロードしない。

これは RAG(Retrieval-Augmented Generation、検索拡張生成。コードを埋め込みベクトル化して類似検索する方式)型ツールとの最大の違い:

観点	RAG 型	Claude Code(agentic search)
鮮度	埋め込みパイプラインの更新待ち	常に最新(その場で読む)
大規模 repo	embedding テーブルが巨大化	local fs を辿るだけ
失敗モード	「数日前の古いコード」を返す	スタート地点が無いとコンテキスト枯渇
対策	embedding 更新頻度を上げる	CLAUDE.md / skill で道標を置く

トレードオフ:Claude が「どこを見ればよいか」のスタート地点を持っていないと、巨大 repo 全体を漠然と探って context window を使い切る。だからこそ CLAUDE.md などへの初期投資がリターン比で大きい。

7 層ハーネスの中身

1. CLAUDE.md(まず最初に整える)

セッション開始時に 自動で読み込まれるコンテキストファイル。

リポジトリ root には全体像、サブディレクトリにはローカル規約を書く
毎回読まれるので、簡潔に保つ(数百行を超えたら分割)
Claude は親方向にディレクトリを辿るので、サブディレクトリで初期化しても root の CLAUDE.md は失われない

2. Hooks(event 連動スクリプト)

「Claude が間違ったことをしないようにする防御策」だけでなく:

セッション終了時に学びを CLAUDE.md に追記 → 自己改善ループ
開始時に動的にコンテキストを読み込ませる(git status / open ticket 等)
linter / formatter のように 決定的に走らせるべきもの は LLM に頼まずフックで確実に

3. Skills(必要時だけ呼び出す専門知)

すべての知識を session に常駐させると context を圧迫する。

セキュリティレビュー用 / ドキュメント更新用など、タスク文脈に応じて段階読み込み
特定の ディレクトリにスコープを限定 することも可能(allowed-paths で apps/web/** のみ等)

4. Plugins(skill + hook + MCP の bundle)

「良い設定」が tribal knowledge(部族知、属人化したノウハウ)になるのを防ぐ仕組み。skill / hook / MCP 設定を 1 パッケージにまとめて社内配布できる。

新人エンジニアが 初日からベテランと同じ環境 を手にできる
バージョン管理可能、roll-back 可能
plugin 由来の skill は plugin-name:skill-name という namespace を持ち、他階層と名前衝突しない設計

5. LSP 連携(シンボル単位の検索)

IDE の「定義へジャンプ」「参照を探す」と同等の能力を Claude に与える。

テキストマッチング(grep)だけだと 同名関数の取り違い が起きる
特に C / C++ / 多言語混在 の codebase で効果が大きい
TypeScript 系でも、interface 実装の探索 / リネームの安全性で効く

6. MCP サーバー(社内データ源への接続口)

MCP(Model Context Protocol、Anthropic 由来のオープン標準)サーバーを介して、外部の社内ツール / データソース / API に Claude を接続する。

構造化検索(社内 wiki / chat / ticket)を MCP ツールとして提供
分析基盤(BigQuery / Snowflake)接続で「prod のメトリクス見ながらコード書く」
セキュリティスキャナ / ライセンスチェッカの起動

7. Subagents(独立 context の別 Claude)

サブエージェント(subagent、独立 context window を持つ別 Claude インスタンス)で「探索と編集の分業」が可能。

探索専用の subagent にサブシステムを調査させ、結果ファイルを書かせる
本体のエージェントはその結果を読んで編集に集中
本体の context が探索ノイズで埋まらない

成功している組織に共通する 3 つのパターン

パターン 1: コードベースを Claude に読ませやすくする

具体的な実装テクニック:

CLAUDE.md を薄く階層化 して保つ(root + サブディレクトリ)
リポジトリの root ではなくサブディレクトリで初期化(Claude は親方向に辿る)
テスト / lint コマンドをサブディレクトリ単位 でスコープ
.ignore / .claude/settings.json の permissions.deny で 生成物 / build 成果物 / 3rd-party コードを除外
ディレクトリ構造で意図が伝わらない場合、リポジトリ直下に 「目次」となる軽量 markdown を置く
LSP を有効化 して文字列ではなくシンボル単位で検索させる

パターン 2: モデルの進化に合わせて CLAUDE.md を能動的にメンテ

古いモデルの弱点を補うために書いた指示は、新しいモデルでは 足かせ になる。

例:「リファクタは必ず 1 ファイルずつ」というルールは、複数ファイル協調編集が得意な新モデル の能力を抑え込む
3〜6 ヶ月ごと、もしくはメジャーリリース後 に性能が頭打ちに感じたら設定を見直す
「過去にうまく行かなかったから禁止」ルールは、それが新モデルでも有効か再評価する

パターン 3: Claude Code 管理の DRI を立てる

技術設定だけでは普及しない。導入が速かった組織には、全社展開の前に小さなチーム(時には 1 人)が事前に必要なプラグイン / MCP を整え、開発者が初日から生産的に使えるようにしていた。

担当は Developer Experience / Developer Productivity 部門に置かれることが多い
新興役職 「エージェントマネージャー」(PM とエンジニアのハイブリッド)も登場
専任チームを置けない場合でも、最低限 1 人の DRI(Directly Responsible Individual)を立てる
規制業種なら エンジニアリング × 情報セキュリティ × ガバナンスの横断 WG を早期に立ち上げる

スキル優先順位 — 同名スキルはどれが勝つか

公式ドキュメントに明記された優先順位。Enterprise > Personal > Project、そして Plugin は別 namespace で衝突しない設計:

優先順位 — 上(Enterprise)が勝つ。Plugin は namespace 付きで衝突しない (クリックで拡大)

階層	配置場所	適用範囲	同名衝突時
Enterprise	管理者設定	組織全体	最強(他をすべて上書き)
Personal	`~/.claude/skills/<name>/SKILL.md`	自分の全プロジェクト	Project に勝つ
Project	`.claude/skills/<name>/SKILL.md`	そのプロジェクトのみ	Personal にいる同名に負ける
Plugin	`<plugin>/skills/<name>/SKILL.md`	plugin が有効な場所	`plugin-name:skill-name` で別 namespace

実務での踏み抜きポイント

「プロジェクト固有の最新版を .claude/skills/ に置いたのに、なぜか古い挙動になる」 → グローバル(~/.claude/skills/)に 同名スキルが残っている 可能性。ls ~/.claude/skills/ で確認
バージョン番号は 見られていない。「Project に新版」「Personal に旧版」だと 旧版が勝つ
確実に Project 版を使わせたいなら グローバルから同名を削除 or リネーム
配布する場合は Plugin として配ると namespace 衝突回避(<plugin>:<skill> で呼べる)

まとめ — 1 行でいうと

モデル単体に期待しない。CLAUDE.md → Hooks → Skills → Plugins → LSP → MCP → Subagents の順にハーネスを組み、組織側に DRI を立てる。

特に新規導入時の優先度は:

CLAUDE.md を最小から始める(数十行 OK、徐々に育てる)
lint / format / test の決定的処理は Hooks に渡す(LLM に頼らない)
権限スコープを .claude/settings.json で最初から絞る(permissions.deny で 3rd-party を切る)
DRI を 1 人立てる(エンジニアリング部門所属、設定と権限を統括)
3 ヶ月後に CLAUDE.md を見直す(新モデルが出ていれば古い禁止ルールを見直す)

慣例的でない構成(ゲームエンジン等のバイナリ資産多めの環境、非標準の VCS 等)は個別判断が必要で、Anthropic Applied AI チームが伴走する旨も原文にあった。

大規模コードベースの Claude Code — モデルではなくハーネスを設計する

ハーネスの全体像 — まずはこの図

なぜ「agentic search」が大規模で効くか