> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kodus.io/llms.txt
> Use this file to discover all available pages before exploring further.

# リンクされたリポジトリ

> レビュー中に Kody が兄弟リポジトリをコンテキストとして読めるようにします — リポジトリ間の契約にも、自分のリポジトリが依存しているのに含んでいないコードにも。

リンクされたリポジトリを使うと、プルリクエストのレビュー中に Kody が組織内の他のリポジトリを**読み取り専用のコンテキスト**として参照できます。これがないと、レビューが見えるのはただ一つ、PR の head にあるレビュー対象リポジトリだけです。別のリポジトリにあるもの — 呼び出しているサービス、インポートしているライブラリ、git submodule — はすべて見えません。

**Teams および Enterprise** プランで利用できます。設定は**リポジトリ単位**です。グローバルなデフォルトはありません。関係は方向性を持つためです。`frontend → backend-api` をリンクすると、*`frontend` のレビュー*が `backend-api` を参照できるようになりますが、その逆にはなりません。両チームがチェックを望むなら、両方向を明示的にリンクしてください。

## どんなときに必要か

どれもよくあり、どれも単一リポジトリのレビューでは見えない 3 つの状況です：

1. **producer/consumer の契約の破壊。** バックエンドが API のフィールド名を変えたのにフロントエンドが古い名前を読み続けている。producer が追加した enum の値をどの consumer も処理していない。writer と reader が同じキャッシュキーを別々の方法で導出している。契約は 2 つのリポジトリに分かれており、何もそれを保証していません。

2. **自分のリポジトリが依存しているコードが、自分のリポジトリにない。** Git submodule、vendor された社内パッケージ、ビルド時に取得される共有ライブラリ。レビューはあなたのリポジトリを *submodule なし*・*パッケージのインストールなし*でクローンするため、submodule やビルド時の依存はレビュー中は空のディレクトリ（あるいはエージェントが辿れない import）になります。正規の型・ルール・クライアントがそうしたリポジトリにあるなら、それをリンクすることがレビューにそれらを読ませる唯一の方法です。

3. **同じビジネスルールがチャネルやサービスごとに再実装されている。** 価格計算、在庫の可否、バリデーション、注文ステータスの遷移。正規の場所に一度だけ存在し、あちこちに「だいたい」コピーされているものです。正規のリポジトリをリンクすれば、エージェントは推測ではなく、正のソースと比較できます。

<Note>
  **この機能がなくてもレビューがすでに見えているもの：** PR の head コミットにおけるレビュー対象リポジトリ全体（diff だけではありません）と、PR の説明文。そのチェックアウト内のどのファイルでも grep・読み取りできます。見えないのは、他のリポジトリ、submodule の中身、インストール済みの依存関係です。
</Note>

リンクされたリポジトリは、コードの外にある契約は**カバーしません**。たとえばサードパーティ API のバリデーション規則は、どのリンク先リポジトリからも見つけられません。

## 何が得られるか

具体例を挙げます。フロントエンドの PR が次のエラーハンドリングを追加したとします：

```ts theme={null}
const isNotApproved =
    error.response?.data?.error === 'INTEGRATION_NOT_APPROVED';
```

バックエンドをリンクしておくと、Kody は契約の反対側を確認し、PR にこうコメントします：

> **Bug · medium** — \[cross-repo] フロントエンドは `error.response?.data?.error` が `INTEGRATION_NOT_APPROVED` かを見ていますが、バックエンドの `sendError`（`src/api/response.ts`）はコードを `message` フィールドで返します。not-approved の分岐は決して一致せず、ユーザーには常に汎用のエラートーストが表示されます。代わりに `data.message` を読んでください。

レビューのサマリーには参照先も表示されます：**Additional context used:** `org/backend-api@main`。

### 指摘はどこに付くか

* すべてのコメントは**あなたの PR の diff** の行に付きます。リンク先リポジトリのコードは `[cross-repo]` タグ付きで、相手側ファイル名とともに、コメント内に根拠として引用されます。Kody がリンク先リポジトリにコメントしたり、指摘を立てたり、変更を加えたりすることはありません。
* 指摘は相手側ファイルの確証が取れた場合にのみ挙げられます。根拠のない「このリテラルはバックエンドと一致していなければならない」は出力されません。
* **Additional context used** の行は、レビュー中にリンク先リポジトリが実際に読まれた場合にのみ表示されます。行がなければ参照されていません（理由は後述）。

## 仕組み

リンクされたリポジトリを持つリポジトリのプルリクエストが境界面に触れると、Kody のレビューエージェントは自分のリポジトリを grep するのと同じ要領で、リンクされたリポジトリを検索・読み取り、契約の両側が今も一致しているかを検証できます。リンク先リポジトリは遅延取得され、エージェントが最初に読む時点で初めてフェッチされます。

### 何がこのパスを有効化するか

リンクを設定するだけでは不十分です。レビューの前に、軽量で決定的なチェックが PR diff の**追加行**を走査し、*境界面*が見つかった場合にのみリポジトリ横断ツールを有効にします：

* 文字列リテラル（コード、イベント名、パスのセグメント、ヘッダー名）
* エクスポートされたシンボル（`export function/const/class/type/interface/enum`）
* enum・type・interface のメンバー
* オブジェクト / ペイロード / DTO のフィールドキー
* status・state・エラーコードらしき識別子（`status`、`code`、`errorCode`、`kind`、`event`、`key` など）
* 契約らしきファイルパス（`dto/`、`schema/`、`api/`、`types/`、`clients/`、`openapi`、`proto` など）

内部だけのリファクタリング — プライベートなヘルパーのリネーム、コードの移動、整形 — は通常どれにも当たらないため、リンク先リポジトリはフェッチされず、レビューは単一リポジトリのレビューとまったく同じように動きます。これは意図的なものです。何も見つかりようのない diff ではこのパスをオフに保ちます。

### 何も表示されないとき

リンクされたリポジトリを持つリポジトリの PR に `Additional context used` の行が**ない**場合、おおよその可能性の高い順に、次のいずれかが起きています：

1. diff に境界面がなかった（ゲートがオフのまま — リファクタリングでは想定どおり）。
2. ゲートはオンだったが、エージェントが結論に至るのにリンク先リポジトリを必要としなかった。
3. リンク先リポジトリを取得できなかった（権限、タイムアウト）— レビューはそれなしで続行します。
4. リンク先リポジトリがこの Kodus 組織に接続されていない、または組織のプランにこの機能が含まれていない — リンクは無視されます。

最初の 2 つは機能が設計どおりに動いている状態です。リンクが正しく設定されているか確かめるには、共有リテラル・DTO フィールド・エクスポートされた型を*実際に*変更する PR を開いてください。それがゲートを有効化し、エージェントに反対側を見る理由を与えます。

<Info>
  * リンクできるのは**同じ Kodus 組織にすでに接続されている**リポジトリだけです（Kody は既存の Git 連携を再利用します — 追加のトークンは不要）。
  * 1 リポジトリあたり**最大 3 つ**のリンク先。
  * アクセスは読み取り専用です。Kody がリンク先リポジトリに push・コメント・変更を行うことはありません。
  * リンク先リポジトリを取得できない場合（権限、タイムアウト）、レビューはそれなしで通常どおり続行します。
</Info>

## リンク先リポジトリの追加

### Web アプリで

**Code Review Settings → *対象リポジトリ* → Linked Repositories** を開き、一覧からリポジトリを選んで（接続済みのものだけが表示されます）保存します。各リンクには任意の項目が 2 つあります（下記）。

### `kodus-config.yml` で

`linkedRepositories` は設定ファイルのキーでもあるため、リンクをほかのレビュー設定と一緒にバージョン管理に置けます：

```yaml theme={null}
linkedRepositories:
  - repository: "org/backend-api"
    instructions: "このフロントエンドが利用する REST API"
    ref: main   # 任意のピン。省略すると同名ブランチのカスケード
```

* `repository`（必須）— 組織に接続されているリポジトリのフルネーム（`owner/repo`）。
* `instructions`、`ref` — Web アプリの項目と同じ意味（下記）。

ファイルと Web 設定の関係は通常の[設定ファイルのルール](/ja/how_to_use/code_review/configs/general#設定の優先度)に従います。ファイルは、そのリポジトリで `kodusConfigFileOverridesWebPreferences` が有効なとき（**Settings → Code Review → 対象リポジトリ → General**）にのみ読まれ、リポジトリの**デフォルトブランチ**から読まれ、ファイルの `linkedRepositories` リストはそのリポジトリの Web 側リストを**置き換え**ます（リストはマージされません。ファイルの `linkedRepositories: []` は機能をオフにします）。プランの要件は、リンクをどこで宣言しても同様に適用されます。

### Instructions（指示）

このリンクが**何のためのもので、どこを見ればよいか**をレビューエージェントに伝える自由記述のヒントです。なくても Kody は動きますが、良い指示があるとリポジトリ横断のパスが速く正確になります。エージェントがリンク先をゼロから探索するか、関連コードに直行するかの差です。

良い指示は、関係と要となるパスを名指しします：

```text theme={null}
このダッシュボードが利用する REST API。エラーレスポンスは
src/api/response.ts が組み立てる — エラーコードはそこと突き合わせること。
```

```text theme={null}
共有の注文ステートマシン。ステータスの enum は
src/domain/order-status.ts にある。定義された値をすべて処理する必要がある。
```

リンク先がライブラリや submodule の場合（上記ケース 2）は、コードがこのリポジトリに*ない*ことと、エージェントが何と突き合わせるべきかを書きます：

```text theme={null}
ビジネスルール・型・クライアントの正規ライブラリ。ここでは git submodule として
利用しているため、ソースはこのリポジトリにない。バリデーションルールは src/rules/、
API クライアントは src/clients/ にある — フィールド名とステータス値はそこと
突き合わせること。
```

弱い指示は自明なこと（「バックエンドのリポジトリ」）を繰り返すだけで、何も足しません。

<Note>
  リポジトリ横断のパスが探すのは**境界をまたいだ不一致**です。片側のフィールド名・キー・エンコーディング・ステータス値が、もう片側が実際に生成・期待するものと一致しない、というものです。正規ライブラリをリンクすれば盲点はなくなります（エージェントがそれを読めるようになります）が、それだけで「正規の実装がすでに存在し、この PR はより弱い再実装をしている」とレビューが指摘するようにはなりません。そのチェックが欲しければ [Kody Rule](/ja/how_to_use/code_review/configs/kody_rules) として書き、指示で正規実装の場所を示してください。
</Note>

### Ref pin（ブランチの選択）

Kody がリンク先リポジトリのどのブランチ（"ref"）を読むかを制御します。**多くのチームは空のままにします**。その場合 Kody は、自分の PR のブランチと同名のブランチが存在すればそれを読み（マージ前に複数リポジトリの協調変更が互いを見えるように）、なければデフォルトブランチにフォールバックします。

解決順序は次のとおりで、最初に一致したものが採用されます：

1. **PR 説明文での上書き** — レビュー対象 PR の説明に、リンク先のブランチや PR を書きます（例：`org/backend-api#123` や `org/backend-api@feature-x`）。単発かつ最優先。すでにリンク済みのリポジトリにのみ適用されます。
2. **設定の `ref` ピン**（この項目）が設定されていれば。
3. **一致するブランチのオープン PR** — リンク先リポジトリで、head ブランチが自分の PR の head ブランチと一致するオープンなプルリクエスト。
4. リンク先リポジトリの**同名ブランチ**。
5. リンク先リポジトリの**デフォルトブランチ**（次いで `main`/`master` にフォールバック）。

複数リポジトリにまたがる機能開発の足並みを揃えるのが 3〜4 です。まだ変更を含まないデフォルトブランチではなく、マージ*前*の対になる変更をレビューが見られます。

**ref ピン**（例：`main`、`develop`、`release/2.x`）は、安定ブランチに対して決定的なレビューを行いたいときに設定します。たとえば、無関係な作業でリポジトリ間にブランチ名が使い回されていて、同名一致が誤ったものを拾ってしまう場合です。単発のケースでは PR 説明文での上書きがピンより優先されます。

<Tip>
  submodule の場合、追跡しているバージョンがライブラリのデフォルトブランチより遅れているなら、`ref` を実際に追跡しているコミットまたはブランチに固定してください。そうしないと、まだ取り込んでいないコードと比較されることがあります。
</Tip>

レビューのサマリーには、実際に使われた ref が常に表示されます。例つきの手順は [リンクされたリポジトリの使い方](/ja/knowledge_base/how-to-use-linked-repositories-in-code-review) を参照してください。