モノレポのClaude Code：コンテキストを制限して精度を保つ

なぜ大規模なモノレポでClaudeは精度を落とすのか

Claude Codeがモノレポで予測しにくく感じられるのは単純な理由です：リポジトリがモデルの作業メモリに一度に収まらないほど大きいからです。

「コンテキスト」とは、このタスクのためにClaudeに見せたファイル、スニペット、ノート、指示の集合と、そこから推測できる内容のことです。重要な詳細が欠けると、Claudeは空白を推測で埋めます。大きなリポジトリではそれが頻繁に起こります。

繰り返し現れる失敗モードは主に三つあります：

まず、見落としたファイル。あるフォルダ内で安全に見える変更が、実は共有の型や設定ルール、別の場所で定義されたビルド手順に依存していることがあります。その依存がコンテキストに無ければ、Claudeは自信を持って間違った箇所を編集したり、本当の情報源が見えないため途中で止まることがあります。

次に、誤った類似性。モノレポには似たパッケージが複数含まれることが多いです：認証モジュールが二つ、APIクライアントが三つ、似たフォルダ構成のReactアプリが複数など。Claudeはそれらのパターンを混同し、別のパッケージのヘルパーを更新したり、「ほぼ正しい」モジュール名からインポートしてしまうことがあります。

三つ目は時間的なズレです。大きなコードベースには古いやり方と新しいやり方が共存しがちです。Claudeが古いファイルしか見ていないと、チームが既に移行していても廃止予定の設定やレガシーAPIをコピーしてしまいます。

実例としてよくあるのは：請求UIの小さな変更を頼んだら、アプリ固有のラッパーを見ておらず、実際は他のアプリでも使われる共有のpaymentsコンポーネントを編集してしまう、というケースです。

目的はClaudeにモノレポ全体を見せることではありません。目的は質問に答えるために必要なより小さく意図的な入力を与えることです：変更するパッケージ、その直接の依存、型や設定の「真実の出どころ」になっている1〜2箇所を含めます。さらに「触ってはいけない」領域（他アプリ、infra、生成コード）を明示し、どのパッケージがその振る舞いを所有しているかを確認します。

タスクを定義することから始める（リポジトリではなく）

精度は貼り付けるコードの量よりも、やるべき作業をどれだけ明確に説明できるかに左右されます。

望む結果をまず定めてください：特定の修正、リファクタ、あるいは回答。『コードについての質問』は高レベルのままで構いません。『変更を加える』要求は境界、入力、成功の判定を必要とします。

何か共有する前に、このフレーズを終える1文を書いてください：「終わったら私は〜できるはずだ」。例：「package Xのユニットテストを失敗なく実行できる」や「エンドポイントYのAPIレスポンスに新しいフィールドが表示される」。リポジトリが巨大なとき、この一文が指針になります。

変更の場合、変更が正しいことを証明できる最小限のアーティファクトを共有します：エントリポイント、関連する型／インターフェースやスキーマ、失敗しているテストまたは再現手順と期待結果、そしてその経路に影響する設定（ルーティング、機能フラグ、ビルドやlintルール）。必要なら、パッケージの短いフォルダマップを追加して、各ディレクトリが何を担っているかをClaudeに理解させます。

何を見ないかを明示してください。「生成ファイル、vendorフォルダ、ビルド出力、スナップショット、lockfileは指示がない限り無視して」と伝えると、無駄な編集や時間の浪費を防げます。

不確実性への期待値も設定しましょう。Claudeに推測させるのではなく、仮定や不明点をフラグにするよう指示します。例：「この関数の呼び出し元が見えない場合はその旨を報告し、見つける方法を2つ提案してください。」

Claudeが越えてはいけない明確な境界を引く

大きなモノレポでは、モデルが「親切に」近くのコードを引き込もうとすると精度が落ちます。対処法は簡単です：変更を依頼する前に、何が対象で何が対象外かを定義してください。

リポジトリの組織に合わせた境界から始めます：パッケージ、サービス、アプリ、共有ライブラリなど。例えば「チェックアウトUIを更新する」なら境界はおそらく1つのアプリパッケージであって、リポジトリ中の“checkout”が現れるすべての場所ではありません。

Claudeがその場に留まるためのシグナルとしては、フォルダ慣習（apps/、services/、packages/、libs/）、パッケージマニフェスト（exportsやdependencies）、公開エントリ（indexファイルやエクスポートされたコンポーネント、ハンドラ）、テスト（意図するサーフェスを示すことが多い）などがあります。フォルダ内のREADMEは最も手早い境界マーカーになり得ます。

境界はブリッジ（境界間で触れてよい点）を名前で示すとより効果的です。具体的に触れてよいインターフェースを明記し、それ以外は許可しないでください。典型的なブリッジはHTTP API契約、イベントトピックとペイロード、共有型、あるいは限定されたエクスポート関数の集合です。

また、変更が影響すべきでない「触るな」ゾーンを常に示してください。一般的にはインフラやデプロイ設定、セキュリティ／認証ロジック、請求や支払い、データ移行や本番スキーマ、多くのチームが使う共有ライブラリなどです。

役立つ具体的なプロンプトの例：

「packages/cart/ とそのテスト内のみ変更してください。packages/types/ の共有型は参照してよいが変更しないでください。infra、auth、billingは編集しないでください。」

有用なローカルサマリーの書き方

正確さは、触りたい範囲の小さく安定した地図を与えることで向上します。ローカルサマリーはその地図です：読みやすく、推測を防ぐのに十分具体的であること。

各サマリーは10〜20行程度にまとめます。境界だけを触る新しい同僚にコードを渡すつもりで、平易な言葉と実際のコード名（フォルダ、パッケージ、エクスポート関数）を使って書いてください。

有用なローカルサマリーは次の5つの問いに答えます：

• このパッケージ／サービスは何のためで、何のためではないか（スコープ）
• 作業の始点はどこか（主要なエントリポイント：ファイル、ルート、コマンド、コンポーネント）
• 外部から安全に呼び出せるものは何か（公開API、エクスポート、イベント）
• 依存先は何か（DB、キュー、キャッシュ、設定、外部サービス）
• ここで重要なルールは何か（命名、エラーの扱い、ロギング、テストの書き方）

1行の「Gotchas（注意点）」を加えてください。隠れたキャッシュ、機能フラグ、移行手順、静かに壊れるものなど、手痛いミスを防ぐための場所です。

使える簡潔なテンプレートは次の通りです（このブロックはそのままコピーして使えます）：

Local summary: <package/service name>
Purpose: <1 sentence>
Scope: <what to touch> | Not: <what not to change>
Entry points: <files/routes/commands>
Public surface: <exports/endpoints/events>
Data sources: <tables/collections/queues/caches>
Conventions: errors=<how>, logging=<how>, tests=<where/how>
Gotchas: <flags/caching/migrations/edge cases>

例：請求パッケージを編集するなら、請求書を作成する正確な関数、書き込むテーブル名、再試行可能なエラーに関するルールを明記してください。そうすればClaudeは共有認証や設定、無関係のパッケージに迷わず集中できます。

サマリーの置き場所と更新方法

最良のサマリーは、必要なときにClaudeが目にするものです。説明するコードの隣に置いて無視しづらく、更新しやすくしてください。例えば各パッケージ／サービス／アプリディレクトリ内に短いSUMMARY.md（またはREADME.mdの一節）を置く方法が有効です。

シンプルで繰り返し可能な構造が長続きします。短く保つことで人が手入れしやすくなります：

• このフォルダが何であるか（目的を1〜2文で）
• 公開サーフェス（主要なエントリポイント、エクスポートモジュール、API）
• 主要依存（内部・外部）
• 境界（何をimport/変更してはならないか）
• テスト方法（最速のローカルチェック）
• Last updated: YYYY-MM-DD - <何が変わったか1文>

サマリーは予測できる理由で古くなります。サマリーの更新を作業の一部として扱い、型定義の更新と同じようにPRで完了させる習慣を付けてください。

更新が必要なタイミング：リファクタで構造や名前が変わったとき、新しいモジュールが主要な方法になったとき、API／イベント／スキーマが変わったとき（テストが通るままでも）、パッケージ間の境界が移動したとき、依存が追加・削除・置換されたとき。

実用的な習慣：マージ時に1行の「Last updated」を追加して何を変えたかを書いておくこと。Koder.aiのようなツールはコード変更を速める手助けになりますが、将来の変更を正確に保つのはサマリーです。

正しいコンテキスト内にとどまるためのステップバイステップワークフロー

精度は会話のペース配分にも依存します。大きなスナップショットから推測させるのではなく、小さな断片でClaudeにコンテキストを獲得させていきます。

ステップ1：まずは短いマップを頼む

編集の前に、Claudeに見えているものと必要なものを説明させます。良いマップは短く、関与する主要パッケージ、フローのエントリポイント、テストや型の場所を示します。

プロンプト例：

「この変更のマップを作ってください：関与するパッケージ、主なフロー、考えられるタッチポイント。まだコードは提案しないでください。」

ステップ2：1つのスライスと1つの境界から始める

狭いスライスを選びます：一機能、一パッケージ、一ユーザーフロー。境界は明確に述べてください（例：「packages/billing-apiのみ変更。shared-uiやinfraには触らない」）。

制御を保つワークフロー例：

• ゴールと境界を1文で定義する。
• Claudeに仮定と不明点を列挙させる（必須）。
• 次に必要なファイルを正確に求めさせる（3〜6個に制限）。
• それらのファイルだけを提供して繰り返す。
• パッチの前に短い計画を必須にする。

ステップ3：仮定とファイル要求を明示させる

欠けている情報があればClaudeに明言させます。書かせる内容は：(1) 立てている仮定、(2) それを否定する条件、(3) 確認のために次に必要なファイルです。

例：あるパッケージでInvoiceレスポンスにフィールドを追加する必要がある場合、Claudeがハンドラ、DTO/型定義、テストを要求したら、その三つのみを共有します。チャットベースのビルダー（例：Koder.ai）を使う場合も同じルールが適用されます：最小限のソースファイルを渡し、本当に必要になったら拡張する。

プロンプトに制約と契約を入れる

誤った編集に対する最良の防御は、プロンプト内に小さな「契約」を書くことです：どこを触ってよいか、成功はどう判定するか、守るべきルールを明記します。

守りやすく検証しやすい境界から始めてください。編集許可のある場所を明示的にし、「触るな」エリアを示して迷わせないようにします。

契約テンプレート例：

• packages/payments/ 以下のみを変更してよい。
• packages/auth/、infra/、共有設定は編集しない。
• スコープ外の変更が必要なら必ず確認する。
• 変更は最小限に：バグ修正を行い、リファクタは避ける。

その後に受け入れチェックを定義します。これがないと表面的には正しく見えるが組織の実際のルールを壊すコードが出てきます。

• パッケージのユニットテストを実行する（使用するコマンドを明記）。
• lint/formatを実行する（ツールを明記するか「既存設定を使う」と記載）。
• パッケージの型チェック／ビルドを実行する。
• アプリが起動するか確認する（単純な実行コマンドで十分）。

スタイル制約も重要です。既存コードベースのパターンに合わせる指示を出してください。例：「このパッケージでは既存のエラーヘルパーを使い、新しい依存を追加しない。関数名はcamelCaseに揃える。新しいアーキテクチャ層を導入しない」など。

最後に、編集前に短い変更計画を義務づけます：

「編集前に触る予定のファイル3〜5件と正確な振る舞いの変更点を列挙し、承認を待つ」

例：

「請求の丸め誤差を修正します。packages/billing/src/ と packages/billing/test/ のみを編集。受け入れ条件：pnpm -C packages/billing test と型チェック。既存のマネー util を使い、API型を書き換えない。まず4ステップの計画を示してください。」

ドリフトや誤った編集を招く一般的な罠

Claudeに一度に大量を与えると、最も早く間違えるのはそれです。大量のコードをペーストすると、モデルは特有の設計ではなく一般的なパターンに頼りがちになります。

別の罠はアーキテクチャを勝手に推測させることです。実際のエントリポイントを示さないと、最初にもっともらしく見えるファイルを選んで処理をそこに繋げてしまいます。実務での精度は、エントリモジュール、ルータ、サービスレジストリ、パッケージ境界のドキュメントといった少数の「真実の出どころ」から来ます。これらがコンテキストに無ければモデルは穴を埋めてしまいます。

名前も誤誘導の原因になります。モノレポにはui、ui-kit、shared-uiのような似た名前のパッケージや、複数箇所にあるdate.tsのような重複ヘルパーが存在します。両方のスニペットを混ぜると、Claudeは片方のファイルをパッチしながらもう片方を前提に推論してしまいます。例：ボタンのスタイル変更を頼んだらpackages/ui/Button.tsxを編集してしまい、アプリは実際にpackages/ui-kit/Button.tsxをインポートしている、ということが起こります。diffは正しく見えるが、本番では何も変わらないのです。

設定も静かなドリフトの原因です。挙動は環境変数、機能フラグ、ビルド設定、ワークスペースツールに依存することがあります。これらに触れないと、Claudeは「奇妙な」チェックを削除したり、ビルド手順を壊すコードを追加するかもしれません。

ドリフトの赤信号：

• 回答が「典型的なパターン」について語り、あなたの実ファイル名を出さない
• 既存ユーティリティを使わず新しい共有ユーティリティを導入する
• パッケージ境界を越えてインポートを変更する
• 機能フラグや環境依存分岐を無視する
• コア共有パッケージへの依存追加を提案する

跨パッケージのインポートはデフォルトではなく意思決定として扱ってください。意図的にスコープを広げる場合を除き、編集はローカルに留めてください。

Claudeに何かを頼む前のクイックチェックリスト

正しい編集を得る最速の方法は、多さではなく制限から始めることです。良いプロンプトはやや厳格に感じられます：どこを見るか、何を無視するか、そして「完了」が何を意味するかを示します。

コードを貼る前に、作業をリポジトリの一箇所に固定する短い前書きを書いてください。パッケージ名、正確なフォルダ、具体的なゴールを明記します。次にローカルサマリー（目的、主要依存、重要な慣習）と変更をアンカーするエントリファイルを含めます。

チェックリスト：

• Boundary（境界）：作業は \u003cpackage\u003e/\u003cpath\u003e のみ。ゴール：\u003cone sentence\u003e。それ以外は無視。
• Context starter（コンテキスト開始）：ローカルサマリー \u003c5-10 lines\u003e。エントリファイル：\u003cpath/to/file\u003e。
• Constraints（制約）：許可されたフォルダ：\u003c...\u003e。変更禁止：\u003cfolders/files or APIs\u003e。維持すべき振る舞い：\u003cwhat must stay true\u003e。
• File requests first（まずファイル要求）：「変更を提案する前に、見る必要最小限のファイル（最大5つ）と理由を列挙してください。」
• Output format（出力形式）：「まず短い計画で返答。承認後にファイルごとのパッチ形式の提案。」

Claudeが境界外の変更を提案したら、それは信号です：プロンプトをより厳密にするか、境界を意図的に広げて再度明記してください。

例：モノレポ全体を起こさずに1パッケージの変更を行う

例として、モノレポにapps/web-store（Reactアプリ）とpackages/ui-kit（共有ボタン、入力、スタイル）があるとします。目的はカートページに「あとで保存」ボタンを追加し、ui-kitの新しいSaveIconを使うことだけで、他は一切変えたくないとします。

編集を依頼する前に、境界として働く2つのローカルサマリーを作成します。短く、具体的で、重要な点に意見を持たせます。

# apps/web-store/LOCAL_SUMMARY.md
Purpose: Customer shopping UI.
Entry points: src/routes.tsx, src/pages/cart/CartPage.tsx
Cart rules: cart state lives in src/cart/useCart.ts
Do not touch: checkout flow (src/pages/checkout), payments, auth.
Tests: npm test -w apps/web-store

# packages/ui-kit/LOCAL_SUMMARY.md
Purpose: shared UI components.
Exports: src/index.ts
Icons: src/icons/*, add new icons by exporting from index.
Do not touch: theming tokens, build config.
Tests: npm test -w packages/ui-kit

そしてループを短く保ちます：

1. Map（地図）：「この変更はCartPageとui-kitのアイコンに限定。checkout/authは触らない。」
2. Assumptions（仮定）：仮定の一覧を要求し、確認を待つ。
3. File requests（ファイル要求）：本当に必要な少数のファイル（CartPage、useCart、ui-kitのアイコン、ui-kitのindex）だけを承認して提供する。
4. Plan（計画）：境界に合致するか確認する。
5. Edits（編集）：最小差分を作り、更新されたテストを要求する。

変更後は将来のコンテキストを小さく保つためにドキュメント化します：

• 変更したエクスポートと正確なファイルを両方のローカルサマリーに追記する。
• カートページのコメントヘッダにボタンの振る舞いとステートの扱いを短く記述する。
• 合格したテストコマンドと更新したスナップショットを記録する。

次のステップ：チームとして再現可能にする

一人ではうまくいってもチームで再現できないなら、欠けているのは再現性です。「良いコンテキスト衛生」を個人の癖ではなくデフォルトにしましょう。

ベストなプロンプトをチームテンプレートにする

誰でもコピーして使えるプロンプトの骨子を保存します。短く、しかし厳格に。ゴール（完了の定義）、許可されたスコープ、不可侵の境界（理由）、ローカルサマリー、出力契約（まず計画、次にdiff形式の編集とテスト）を含めます。

軽量な頻度でサマリーを更新する

誰もやらない大きな月次レビューは避けてください。変更が振る舞い、依存、APIを変えるたびにサマリーを更新するルールを設けます。

シンプルなルール：同僚が「これってどこにあるの？」や「何が依存しているの？」と尋ねたくなったら、そのサマリーは古くなっています。

チャット優先のワークフローが好みならKoder.aiはこの反復スタイルを安全にする助けになります。Planning Modeは編集前にスコープと境界の合意を助け、スナップショットとロールバックは推測が外れたときの行き詰まりを防ぎます。