Claude Code を大規模コードベースで使うベストプラクティス — Anthropic 公式の7つの拡張機構とAgent Manager役を初心者向けに完全分解

本サイトは Google AdSense による広告が表示される場合があります。本記事は Anthropic 公式ブログ「How Claude Code works in large codebases: Best practices and where to start」（2026-05-14 公開）を一次情報として精読し、公式ドキュメント（code.claude.com/docs）と運営者の Claude Code 運用経験（現役 IT エンジニア・15 年以上）を踏まえて日本語で再構成したものです。仕様は 2026 年 5 月時点。最新情報は 公式ドキュメント をご確認ください。

Tech Notes · Claude Code · Enterprise Practices · 2026.05

数百万行のモノレポ、20 年もののレガシー、何十個ものマイクロサービス——いわゆる「大規模コードベース」で Claude Code を実戦投入してきたチームから、Anthropic が現場の知見をまとめた公式ブログを公開した^[1]。要点は驚くほどはっきりしている。性能はモデル本体だけでは決まらない。Claude を取り囲む「ハーネス（harness）」 ——CLAUDE.md、Hooks、Skills、Plugins、LSP、MCP、Subagents——の設計と運用が、同じくらい重要なのだ。本記事ではこの公式ブログを起点に、初心者の方が「明日から自分のチームで再現できる」レベルまで噛み砕いて 16 章で配る。読了 25 分、最初の設定変更まで 1 時間、組織展開の最小構成まで 1 週間が射程だ。

user@sinyblog:~/article ❯ 01_tldr.md90 秒ダイジェスト：この記事のゴール

本記事のゴールは 1 つ。Claude Code を「個人のチャット相手」から「会社のコードベースを安全にナビゲートできる開発インフラ」へ昇格させること。Anthropic がブログで明かしたのは、次の 3 行に集約できる^[1]。

1. Claude はソフトウェアエンジニアと同じやり方でコードを読む。巨大ベクトルインデックスではなく、ファイルを開き grep し参照を辿る「エージェンティック検索」を採用する。
2. 性能を左右するのはモデルそのものではなく、その周囲のハーネス。CLAUDE.md / Hooks / Skills / Plugins / LSP / MCP / Subagents の 7 つを、コードベースに合わせて整える必要がある。
3. 大規模展開を成功させたチームは「Agent Manager」を立てている。ボトムアップ採用は熱狂を生むが断片化のリスクが高い。設定とポリシーを中央集約する役割が要る。

以降の章では、この 3 つを「初心者でもなぞれる手順」まで落とし込んでいく。途中、コードブロックは必ずコピーボタン付きで配り、専門用語は出てくるたびに 1 行で定義する。難しい単語は無視して構わない、まずコピペで動かしてから理屈を埋めればいい。

user@sinyblog:~/article ❯ 02_large-codebase.mdそもそも「大規模コードベース」って？ — モノレポ・レガシー・マイクロサービス

Anthropic のブログは「数百万行のモノレポ」「数十年もののレガシーシステム」「分散型マイクロサービス」を一括して "large codebases" と呼んでいる^[1]。具体的にどう違うのか、まず単語の輪郭から整理しておこう。

大きさの目安は「ファイル数 1 万以上、開発者 50 人以上、サービス境界が複数」あたり。ただし数十人規模のスタートアップでも、Rails 5 のレガシーモノリス＋新規 Go マイクロサービスのような構成なら、本記事の処方箋はそのまま効く。

user@sinyblog:~/article ❯ 03_agentic-search.mdClaude Code がコードを読む仕組み — 「エージェンティック検索」とは何か

大規模リポを扱う AI ツールの代表的な方式は 2 つに分かれる。埋め込み RAG（Retrieval-Augmented Generation）と エージェンティック検索（agentic search）だ。Claude Code は後者を採用している^[1]。

Claude navigates codebases the way software engineers do — traversing the file system, reading files, running grep for what it needs, and following references throughout the codebase. Agentic search avoids those failure modes.

Anthropic Blog “How Claude Code works in large codebases”（2026-05-14）/ [1]

Anthropic が明確に強調しているのは 「埋め込みパイプラインは活発なチームの変更速度に追いつかない」 という点だ。数千人がコミットする企業環境では、インデックスが古くなって「3 週間前のコードに基づく回答」が返るリスクがある。Claude Code はサーバー側にコードをアップロードせず、開発者のマシン上でローカルに動くため、コミットされた瞬間から最新のコードを使える。

user@sinyblog:~/article ❯ 04_harness.mdなぜ「ハーネス」がモデル本体と同じくらい大事なのか

Anthropic の文章で繰り返される強いメッセージがこれだ。

The harness matters as much as the model.

Anthropic Blog 同上 / [1]

ハーネスとは馬具の「装具」のことで、ここでは Claude Code 本体を取り囲む拡張機構の総称を指す。具体的には以下の 7 つ。

1. CLAUDE.md — セッション開始時に自動ロードされるプロジェクト固有の常識
2. Hooks — 特定イベントで決定論的に走るシェルスクリプト
3. Skills — 必要時のみ読み込まれる「専門知識パッケージ」
4. Plugins — Skills / Hooks / MCP をまとめて配布する単位
5. LSP（Language Server Protocol） — IDE 並みのシンボル単位ナビゲーション
6. MCP servers — 社内ツール・DB・API への接続口
7. Subagents — 隔離された別 Claude を呼び出して並列で動かす機構

同じモデル（例：Claude Sonnet 4.6）であっても、これらが整備されたチームと、まったく整備されていないチームでは 「成功率も、安全性も、開発速度も別物になる」 というのが Anthropic の主張だ。後者は「Claude が遅い・賢くない」と感じるが、原因はモデルではなく装具側にある。本章以降ではこの 7 つを 1 つずつ分解していく。

user@sinyblog:~/article ❯ 05_seven-mechanics.md7 つの拡張機構 — 全体マップ

細部に入る前に、まず一枚絵を見せておく。「いつロードされるか」「何の道具か」「やりがちな失敗」を縦に並べた早見表だ。

表の右端「よくある誤用」は、Anthropic がブログでわざわざ太字にしているくらいの頻発パターンだ。順番を守らずに飛びつくと、複雑さだけ上がって効果が出ない。本記事のオススメは「1 → 7」の順で 1 つずつ、自分のリポに導入してから次に進むこと。

user@sinyblog:~/article ❯ 06_claudemd.md①CLAUDE.md — ルートは「ポインタと地雷」だけにする

大規模リポにおける CLAUDE.md 設計の鉄則は、Anthropic の表現を借りればこうだ。

Keeping CLAUDE.md files lean and layered. Initializing in subdirectories, not at the repo root.

Anthropic Blog 同上 / [1]

つまり 「ルートの CLAUDE.md は小さく・サブディレクトリで初期化する」。なぜか。CLAUDE.md は セッション開始時にディレクトリツリーを上に辿ってすべて連結ロードされる仕様だからだ^[2]。ルートに何百行も書くと、リポのどこで作業しても毎回それが context window を圧迫する。一方サブディレクトリの CLAUDE.md は、そのディレクトリ内のファイルを Claude が読んだときだけオンデマンドでロードされる^[2]。

具体的にはこんな配置が黄金パターンだ。

monorepo/
├── CLAUDE.md                       # ルート: 全体マップとポインタのみ（30〜50行）
├── .claude/
│   ├── settings.json               # permissions.deny で生成物・vendor を除外
│   └── rules/
│       └── shared-conventions.md   # 全チーム共通ルール
├── services/
│   ├── billing/
│   │   ├── CLAUDE.md               # billing 固有: テストコマンド、命名規則、地雷ポイント
│   │   └── src/
│   ├── search/
│   │   ├── CLAUDE.md               # search 固有
│   │   └── src/
│   └── web/
│       └── CLAUDE.md               # web 固有: フレームワーク、デザイントークン
└── infra/
    └── CLAUDE.md                   # IaC 固有: 環境分け、デプロイ手順

ルート CLAUDE.md は次のような「目次＋警告」だけで十分機能する。

# Monorepo Overview

## What lives where
- `services/billing/` — 決済（Go）。Stripe Webhook を扱う。詳細は同ディレクトリ CLAUDE.md。
- `services/search/` — 検索（Python, Elasticsearch）。同上。
- `services/web/` — フロント（Next.js, TypeScript）。
- `infra/` — Terraform。本番への apply は CI のみ。手元では plan まで。

## Landmines（地雷ポイント）
- `vendor/` と `dist/` は読みに行かないこと（.claude/settings.json で deny 済み）。
- `legacy/v1/` はサポート切れ。質問されない限り触らないこと。
- データベーススキーマは `services/billing/migrations/` のみが正。他のコピーは古い。

## Per-subdirectory conventions
それぞれのサブディレクトリ CLAUDE.md を参照。本ファイルでは扱わない。

そして 除外設定はテキストではなく .claude/settings.json の permissions.deny でバージョン管理する。Anthropic はこの点を明示的に推奨している^[1]。

{
  "permissions": {
    "deny": [
      "Read(./vendor/**)",
      "Read(./node_modules/**)",
      "Read(./dist/**)",
      "Read(./build/**)",
      "Read(./.next/**)",
      "Read(./coverage/**)",
      "Read(./**/*.min.js)",
      "Read(./legacy/v1/**)"
    ]
  }
}

user@sinyblog:~/article ❯ 07_hooks.md②Hooks — イベント駆動で「セッションの学び」を採取する

Hooks は 特定イベントで Claude の判断とは無関係に走るシェルスクリプトのこと^[4]。CLAUDE.md が「お願い」なら、Hooks は「強制」だ。代表的なイベントは PreToolUse（ツール使用前）、PostToolUse（ツール使用後）、Stop（セッション終了時）、InstructionsLoaded（指示ロード完了時）など。

Anthropic のブログが特に強調するのは 2 つの使い方だ^[1]。

1. 決定論的なルールの強制：lint・フォーマット・テスト実行など、Claude の気分次第ではなく必ず走らせるべきもの。
2. セッションの学びを採取：Stop フックで「今回のやりとりで CLAUDE.md に追加すべき教訓は？」と尋ね、自動で memory ファイルを更新する継続的改善ループ。

最小実装例として、Edit/Write 後に Python リポなら自動で ruff を走らせるフックを置いてみる。

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "ruff check --fix $CLAUDE_TOOL_FILE_PATHS 2>&1 || true"
          }
        ]
      }
    ]
  }
}

このフックを置くと、Claude がコードを書いた直後に必ず lint が走り、エラーが出ればその出力が Claude にフィードバックされる。「お願いしてもたまに lint を忘れる」問題が物理的に発生しなくなる。

user@sinyblog:~/article ❯ 08_skills.md③Skills — オンデマンドで読み込まれる専門知識パック

Skills は 「特定タスク用にパッケージ化された指示」。CLAUDE.md と違って毎セッション自動ロードされず、Claude が「このスキルが今のタスクに関連しそうだ」と判断したときだけ呼び出される^[3]。

大規模コードベースでの典型用途を、ブログから抜粋して整理する。

スキルは .claude/skills/<name>/SKILL.md という形式で置く。最小サンプルはこんな感じ。

---
name: security-review
description: 認証・認可・データ取扱に関する変更があった場合に呼び出すセキュリティレビュー手順
---

# Security Review Skill

このリポでセキュリティレビューを行うときは、必ず以下の順で確認する。

1. 認可（authorization）— Resource owner と current user の突合があるか
2. 入力検証 — ユーザー入力が直接 SQL / shell に渡っていないか
3. 秘密情報 — ハードコードされた key / token がないか（grep "secret|api_key|token"）
4. ログ — 個人情報・PII が平文でログ出力されていないか

レビュー結果は `docs/security-review-log.md` に追記。重大なら GitHub Issue 化する。

user@sinyblog:~/article ❯ 09_plugins.md④Plugins — Skills / Hooks / MCP をまとめてチームに配る

Plugins は Skills・Hooks・MCP 設定をひとまとめにした配布単位。組織内マーケットプレイス経由で配ると、新入社員が初日から同じ「武装」で開発を始められる^[1]。

Anthropic がブログで挙げる具体例：

A retail company distributes a plugin that connects business analysts to its internal analytics platform; new hires on day one can ask questions about sales data in their own terms.

Anthropic Blog 同上 / [1]

つまり、ある小売企業では「自社の分析基盤に接続するスキル＋認証フック＋クエリ整形スキル」を 1 つのプラグインに束ね、ビジネスアナリスト全員に配布している。アナリストは Claude Code を起動してから何の追加設定もせず、いきなり「先月のカテゴリ別売上を地域ごとに見せて」と日本語で聞くだけで作業できる。

プラグインの最小構成は plugin.json（マニフェスト）＋ skills/・hooks/・mcp.json のディレクトリ群^[5]。詳しい仕様は公式ドキュメントに譲るが、雛形のイメージは以下。

company-analytics-plugin/
├── plugin.json                  # name, version, description, entry points
├── skills/
│   ├── sales-query/SKILL.md
│   └── retention-report/SKILL.md
├── hooks/
│   └── pre-commit-pii-scan.sh
└── mcp/
    └── analytics-server.json    # 社内分析基盤への MCP 接続定義

user@sinyblog:~/article ❯ 10_lsp.md⑤LSP — 「同名関数の混同」を消す唯一の方法

LSP（Language Server Protocol）は VS Code や JetBrains 系 IDE の 「定義へジャンプ」「参照を検索」の裏側で動いている、コードの意味を理解するための共通プロトコルだ。Claude Code は LSP サーバーを統合することで、文字列マッチではなく シンボル単位でリポを読めるようになる^[6]。

Anthropic がブログで強調する具体的なベネフィット：

LSP returns only the references that point to the same symbol, so the filtering happens before Claude reads anything.

Anthropic Blog 同上 / [1]

これがどう効くか、具体例で説明する。大規模リポには、save() という関数が 50 ファイルに同名で存在することは珍しくない（モデルクラス、API ハンドラー、CLI ツール、テスト用フィクスチャ…）。LSP がない場合、Claude は grep save で 50 件のヒットを引き、その中から関係あるものを推測しなければならない。LSP があれば、「同じシンボル定義に紐づく参照だけ」に絞られる。50 件が 3 件になる、それだけで context も時間も節約される。

大規模 C++ コードベースを扱うエンタープライズ企業の事例として、ブログは「Claude Code 本格展開の前に、まず組織全体に LSP 統合を入れた」と紹介している^[1]。「Claude を入れる前の準備段階で LSP」というのは、初心者には意外な順序かもしれない。だが、これを飛ばすと Claude が C++ の関数 1 つ調べるたびに 100 箇所読みに行くような事故が起きる。

user@sinyblog:~/article ❯ 11_mcp.md⑥MCP servers — 社内ツール・チケット・分析基盤への接続口

MCP（Model Context Protocol）は 外部システムを Claude のツールとして使えるようにする標準プロトコル。Slack、Jira、社内 DB、Grafana、社内 wiki など、「コードを読むだけでは答えに辿り着かない情報」へアクセスする橋渡しだ^[7]。

大規模コードベースで MCP が威力を発揮する具体例：

1. チケット連動：「JIRA-1234 を解決して」→ MCP 経由で Jira から要件取得 → 該当コード修正 → コミットメッセージに自動で Issue 番号を入れる
2. 本番ログ参照：エラー原因調査時に「直近 1 時間の 500 エラー」を Datadog/Splunk から取得して該当行を特定
3. ドキュメント参照：「決済の仕様は Notion のどこに書いてある？」→ MCP で社内 Notion を検索 → 該当ページの該当節を引用
4. 構造化検索：grep では不可能な「DB の特定カラムを参照している全関数」のような問いに、社内インデックスサーバーへ MCP で問い合わせ

最小構成の MCP 設定は .mcp.json に書く^[7]。

{
  "mcpServers": {
    "jira": {
      "command": "npx",
      "args": ["-y", "@company/mcp-jira"],
      "env": {
        "JIRA_BASE_URL": "https://company.atlassian.net",
        "JIRA_EMAIL": "${JIRA_EMAIL}",
        "JIRA_API_TOKEN": "${JIRA_API_TOKEN}"
      }
    },
    "internal-docs": {
      "command": "node",
      "args": ["./tools/mcp-internal-docs/server.js"]
    }
  }
}

user@sinyblog:~/article ❯ 12_subagents.md⑦Subagents — 「探索」と「編集」を分離して並列化する

Subagents は 親 Claude が別の Claude インスタンスを呼び出して並列で動かす機構。それぞれの subagent は独立した context window を持つため、本体の context を汚さずに「重い探索作業」を肩代わりさせられる^[8]。

Anthropic のブログが具体的な使い方として挙げるのが 「read-only subagent で先にサブシステムをマッピングし、結果ファイルだけを親に渡してから親が編集に入る」 という分離パターンだ^[1]。

A read-only subagent to map a subsystem and write findings to a file. The parent agent then edits with a complete picture.

Anthropic Blog 同上 / [1]

これは大規模リポでの調査・改修の 正攻法だ。たとえば「決済まわり 8 ファイルにまたがるバグを直したい」というとき、いきなり親 Claude に直接やらせると、ファイルを順番に開きながら context が膨らみ、後半で「最初に何を見たんだっけ？」と混乱する。代わりに：

1. 親に「決済まわりの該当バグを調査して」と依頼
2. 親が read-only subagent を呼び、subagent は調査結果を findings.md に書く
3. 親は subagent の戻り値（または findings.md）だけを読む
4. 親は完全な構図を把握した状態で編集フェーズに入る

Subagent 自体は .claude/agents/<name>.md に frontmatter 付き Markdown で定義する^[8]。最小例は次の通り。

---
name: codebase-explorer
description: 読み取り専用でサブシステムを地図化する。編集は一切行わない
tools: Read, Grep, Glob
---

# Codebase Explorer

あなたは読み取り専用の調査エージェントです。役割は次の通り：

1. 与えられたサブシステムの全体像を把握する
2. 関係するファイル一覧、主要な関数、データの流れを Markdown 1 枚に要約する
3. 編集は一切しない（Write/Edit ツールは持っていない）
4. 結論は  タグで括って返す

出力は箇条書きで簡潔に。仮説や推測は明示する。

user@sinyblog:~/article ❯ 13_pattern-legibility.mdパターン①：コードベースを Claude に「読みやすく」する

Anthropic がブログで最初に挙げる成功パターンが "Making the codebase legible to Claude"（コードベースを Claude に判読可能にする）だ^[1]。具体的な内訳を整理しよう。

大事なのは、これらが すべて「事前準備」であること。Claude Code を導入してから「動きが悪いなぁ」と感じて整え始めるのではなく、Claude Code を本格的に開放する前にこの 5 つを通しておくのが成功チームの共通パターンだ^[1]。エンタープライズ展開で「まず LSP を全社展開してから Claude Code を配った」C++ 企業の事例は、その典型例といえる。

user@sinyblog:~/article ❯ 14_pattern-maintain.mdパターン②：モデル進化に合わせて 3〜6 ヶ月ごとに剪定する

2 つ目の成功パターンは 「設定を放置しないこと」。Anthropic は具体的に 「3 ヶ月から 6 ヶ月ごとに見直すべき」と書いている^[1]。理由はシンプルだ。

Instructions optimized for earlier models may constrain newer ones. Skills and hooks addressing specific model limitations become unnecessary overhead once those limitations disappear.

Anthropic Blog 同上 / [1]

具体例で考えると分かりやすい：

1. 古いモデル時代に書いた「リファクタは 1 ファイルずつ」ルール→新モデルは複数ファイルを一貫性をもって編集できるので、このルールが逆に足を引っ張る。
2. VCS（例：Perforce）連携の hook が、以前は手動で p4 edit 必須だった→ Claude Code がネイティブ対応した後はその hook は無駄な時間ロスになる。
3. 「日本語で答えてください」みたいなルール→デフォルトで言語追従するモデルでは冗長。

剪定の運用は次のリズムが現実的だ。

user@sinyblog:~/article ❯ 15_pattern-agent-manager.mdパターン③：Agent Manager を立てて中央化する

Anthropic がブログで最も新しく、最も興味深い指摘がこれだ。

An emerging role in several organizations is an agent manager: a hybrid PM/engineer function dedicated to managing the Claude Code ecosystem. Bottoms-up adoption generates enthusiasm but can fragment without someone to centralize what works.

Anthropic Blog 同上 / [1]

つまり、複数の企業で 「Agent Manager」という新しい職種が立ち上がっているという。PM とエンジニアの中間で、Claude Code のエコシステム——設定、権限ポリシー、プラグインマーケットプレイス、CLAUDE.md 規約——を一手に管理する役割だ。

なぜ専任が要るのか

ボトムアップ採用（個々のエンジニアが勝手に使い始める）は熱量を生み出す反面、「断片化」を生む。A チームの CLAUDE.md と B チームの CLAUDE.md が矛盾し、C チームが秘伝の hook を抱え込み、D チームは怖くて Claude を使えない、という状態に陥る。これを中央集約せずに放置すると、半年後には「同じ会社の Claude Code 設定が 30 通り存在する」という悪夢になる。

最小実行版：「DRI 1 人」から始める

いきなり Agent Manager 専任を雇うのは多くの組織で難しい。Anthropic は 「最小は DRI（Directly Responsible Individual）1 人」と示唆している^[1]。最初は誰かのサイドプロジェクト 20% でいい。設定、決定、権限、現状維持の責任が 「あの人」と決まっていることが重要だ。

user@sinyblog:~/article ❯ 16_dont-and-checklist.mdやってはいけない 8 選 + Getting Started Checklist

ここまでの内容を「やらかしリスト」と「立ち上げチェックリスト」の 2 つに圧縮しておく。明日から見返せる現場用の道具として使ってほしい。

やってはいけない 8 選

Getting Started Checklist（最小ロードマップ）

Anthropic がブログ末尾で示すチェックリストを、初心者向けに番号順に並べ直したのが下記。上から順にやれば 1 週間で「最低限の装具」が揃う。

1. Day 1：ルート CLAUDE.md を 50 行以内で書く（ポインタ＋地雷ポイントのみ）。.claude/settings.json に permissions.deny でビルド成果物・vendor を除外
2. Day 2：主要サブディレクトリ 3〜5 箇所で /init し、ローカル CLAUDE.md を生成。テスト/lint コマンドを各サブに移す
3. Day 3：使っている言語の LSP サーバーを 1 つ統合（例：Python なら pyright、TypeScript なら typescript-language-server）
4. Day 4：最小 Hook を 1 本だけ書く（PostToolUse で lint）。動作確認
5. Day 5：チームに最も頻出する作業手順を 1 つ Skill 化（例：security-review）
6. Day 6：read-only subagent を 1 つ定義（codebase-explorer）。実際に大きめのバグ調査で使ってみる
7. Day 7：Agent Manager の DRI を 1 人決める。次回剪定を 3 ヶ月後にカレンダー登録

user@sinyblog:~/article ❯ 99_summary.mdまとめ：30 日ロールアウトプラン

本記事を 3 点に集約する。

1. 性能はモデルではなく「ハーネス」で決まる。CLAUDE.md / Hooks / Skills / Plugins / LSP / MCP / Subagents の 7 つを、コードベースに合わせて段階的に整えるのが大規模運用の本質。
2. 「Claude に読みやすく」「設定を剪定し」「中央集約する」の 3 パターンを順序立てて実装する。とくに最初の "legibility" は Claude Code 本格展開の前に準備しておく。
3. Agent Manager を立てる。DRI 1 人からでいい。設定責任者がいないと、ボトムアップの熱は半年で「30 通りの秘伝設定」という負債に変わる。

明日から始める 30 日プラン

大規模コードベースで Claude Code を活かす道は、派手な機能ではなく「地道なハーネス整備」の積み上げだ。本記事の手順をそのまま 1 日 1 つ進めれば、1 ヶ月後には「Claude が賢くなった」のではなく「Claude にコードベースを読ませる準備が整った」状態になる。準備さえ整えば、あとはモデルが進化するたびに勝手にチームの生産性が上がっていく。これが Anthropic が「ハーネスはモデルと同じくらい大事」と繰り返す本当の意味だ。