> ## 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 と並んで実行されます。

<Callout icon="alien" iconType="regular">カスタムエージェントはベータ版です。動作や画面は今後変わる可能性があります。</Callout>

## 概要

カスタムエージェントは、チームが 1 つの関心事のために書くレビュアーです。アーキテクチャの境界、重複コード、セキュリティポリシー、E2E テストのカバレッジなどが対象になります。各エージェントには次のものがあります。

* **Instructions**：何を探すか、何を無視するか、指摘にどんな証拠が必要か
* **Files**：レビュー対象の glob。プルリクエストがそのいずれかを変更したときだけ実行されます
* **Skills & docs**：エージェントが従うリポジトリ内のガイド
* **Tools**：読み取り専用のプラグイン、チームの CLI、ast-grep ルール
* **Comments & model**：タグ、形式、最小重大度、コメント上限、書き方、モデル

エージェントは Kody 自身のレビューと並行して実行されます。各エージェントは自分の担当範囲だけを報告し、コメントにはエージェント名のタグが付くため、誰の発言かがチームにわかります。

**Teams および Enterprise** プランと、トライアル期間中に利用できます。Free プランではカスタムエージェントは一切実行されません。レビューでも、`@kody -v` でも、**Try it** でも実行されません。保存済みのエージェント、スキル、ドキュメントは保持され、アップグレード後に再び実行されます。

<CardGroup cols={2}>
  <Card title="Skills、docs、ツール" icon="toolbox" href="/ja/how_to_use/code_review/custom_agents_knowledge_and_tools">
    リポジトリのガイド、プラグイン、チームの CLI、ast-grep ルールを紐付けます。
  </Card>

  <Card title="ベストプラクティス" icon="list-check" href="/ja/how_to_use/code_review/custom_agents_best_practices">
    本当の問題を見つけ、それ以外では静かなエージェントを書きます。
  </Card>
</CardGroup>

## 場所

**Code review → What to review** を開きます。**Custom agents** セクションはレビューカテゴリの下にあり、**New agent** ボタンと **Skills & docs** へのリンクがあります。

各行には、エージェントのスイッチ、タグの色、指示の 1 行目、ファイル・skills・docs・ツールのチップ、最近の実績（例：`9 PRs · 15 posted · 30 days`）が表示されます。行をクリックするとエージェントのページが開きます。**⋯** メニューには **Edit**、**Try it**、**Delete** があります。

<Note>
  カスタムエージェントはアプリでのみ設定します。`kodus-config.yml` の `customAgents` と `knowledge` キーは無視され、レビューの最終コメントでその旨が通知されます。[FAQ](#faq) を参照してください。
</Note>

## レベル

エージェントは、他の設定と同じく **Code review** グループ上部のスコープピッカーに従います。

| レベル | 動作 |
| - | - |
| **グローバル** | 独自のリストを持たないすべてのリポジトリ向けのエージェント。 |
| **リポジトリ** | リストは最初グローバルと同じです。そこで最初に変更を保存すると、リポジトリは独自のリストを持ち、グローバルのリストを**置き換え**ます。以降、グローバルのエージェントへの変更は届かず、画面に "This repository has its own agents list. Changes to the global agents don't reach it." と表示されます。 |
| **ディレクトリ** | リポジトリのエージェントに自分のエージェントを**追加**します。リポジトリのエージェントは **From repository**（または **From repository, off**）と表示され、そこでは読み取り専用です。 |

ディレクトリでは、継承したエージェントは読み取り専用で開き、**Override at this directory** ボタンが表示されます。オーバーライドするとエージェントが同じ id でディレクトリにコピーされ、そのディレクトリではコピーがリポジトリのエージェントを置き換えます。指示を変えたり、オフにしたりできます。オーバーライドを削除すると、リポジトリのエージェントが戻ります。

<Note>
  ディレクトリのエージェントは、レビューがそのディレクトリの設定を使うときに実行されます。プルリクエストがどの設定を使うかは [ディレクトリレベルの設定](/ja/how_to_use/code_review/configs/directory_level) を参照してください。
</Note>

## エージェントを作成する

<Steps>
  <Step title="New agent をクリック">
    **What to review → Custom agents** で **New agent** をクリックします。
  </Step>

  <Step title="出発点を選ぶ">
    **Templates** は書き済みの指示から始まります。

    | テンプレート | 対象 |
    | - | - |
    | **Architecture** | レイヤー境界、依存の方向、新しいコードの置き場所。 |
    | **E2E coverage** | フローの E2E テストなしで出荷されるユーザー向けの変更。 |
    | **Regression & hallucination** | 黙って変わった動作と、存在しない API の呼び出し。 |
    | **Security reviewer** | インジェクション、認可・テナントのチェック、シークレット、安全でない入力処理。 |
    | **Blank** | 何もない状態から自分で指示を書きます。 |

    **Import from repository** は、リポジトリのデフォルトブランチで見つかった skills を一覧表示し、1 つを毎回のレビューでそれを読み込むレビュアーに変換します。skills は各リポジトリにあるため、グローバルレベルでは使えません。
  </Step>

  <Step title="エージェントのページで調整">
    エージェントはすぐに保存され、そのページが開きます。ファイルを設定し、skills と docs を紐付け、ツールを追加します。
  </Step>

  <Step title="Try it で試してからオンにする">
    新しいエージェントは**オフ**で始まります。実際のプルリクエストで [Try it](#try-it) を実行し、コメントが適切ならオンにします。
  </Step>
</Steps>

<Tip>
  エージェント名はコマンド名にもなります。"Data Contracts" は `@kody -v data-contracts` に応答します。同じコマンド名になる 2 つのエージェントは、同じレベルに保存できません。
</Tip>

## エージェントのページ

ページには、ステータス行（オン/オフ、実行対象のファイル、過去 30 日の投稿数）、4 つのカード、**Try it** パネルがあります。ページ上の変更は **Save** で保存します。

### Instructions

| フィールド | 説明 |
| - | - |
| **Name** | エージェントのタグに表示されます。Kody のカテゴリ（Bug、Performance、Security、Business Logic）と同じ名前は避けてください。ページが別の名前を提案します。 |
| **Instructions** | 最大 8,000 文字。コードベースを知るレビュアーへのブリーフです：何を探すか、何を無視するか、指摘にどんな証拠が必要か。 |

### Files & knowledge

| フィールド | 説明 |
| - | - |
| **Files** | エージェントがレビューする glob。例：`src/payments/**`。空ならすべてのプルリクエストで実行されます。 |
| **Except** | スキップする glob。例：`**/*.test.ts`、`**/generated/**`。 |
| **Skills & docs** | エージェントが従うガイド。プルリクエストのターゲットブランチから読み込まれます。[Skills、docs、ツール](/ja/how_to_use/code_review/custom_agents_knowledge_and_tools) を参照してください。 |

glob は、ディレクトリレベルを含むすべてのレベルで、リポジトリのルートからのパスと照合されます。

**無視されたファイル。** リポジトリの無視パス（**General**）は引き続き適用されますが、例外が 1 つあります。ファイルを**名指しする** glob は、リポジトリが無視していてもそのファイルに届きます。パスのセグメントのうち少なくとも 1 つがリテラルで、最後のセグメントが `*` や `**` だけでなければ、その glob はファイルを名指ししています。

| Glob | 無視されたファイルに届くか |
| - | - |
| `package.json`、`apps/web/package.json`、`**/Dockerfile`、`infra/**/*.tf` | はい |
| `**`、`**/*`、`**/*.ts`、`*.{ts,tsx}`、`src/**`、`apps/web/*` | いいえ |

シークレットファイル（`.env*`、`*.pem`、`*.key`、`*.p12`、`*.pfx`、`*.jks`、`*.keystore`、`id_rsa*` などの SSH 鍵）は、名指しする glob があっても、無視パスからエージェントに渡されることはありません。

変更ファイルがすべて無視されているプルリクエストも、そのうちいずれかを名指しするエージェントにはレビューされます。レビューするのはそのエージェントだけで、Kody 自身のレビューには対象がありません。

### Tools

コードを読む以外にエージェントが実行できるもので、すべてチームのシステムに対して読み取り専用です：**Plugins**（MCP）、**CLIs**（最大 3 つ）、そして **Advanced** の下の **Structural search (ast-grep rules)**。[Skills、docs、ツール](/ja/how_to_use/code_review/custom_agents_knowledge_and_tools) を参照してください。

### Comments & model

| フィールド | 選択肢 |
| - | - |
| **Tag** | コメントに付くエージェントのタグの色。 |
| **Format** | **Inline comments**、またはエージェントの指摘を重大度の高い順にまとめた **One PR comment**。 |
| **Minimum severity** | **Team minimum** は What to review の **Minimum severity to post** に従います。**Low (everything)**、**Medium**、**High**、**Critical** はエージェント独自の下限を設定します。 |
| **Max comments per pull request** | 重大度の高いものから投稿します。空なら上限なし。 |
| **Suggested fix** | **When confident**：エージェントが変更に確信を持つときにコードを提案します。**Never**：問題の説明だけをします。 |
| **How it writes** | トーン、長さ、すべてのコメントに含めることを最大 2,000 文字で指定します。空ならチームの書き方設定を使います。コメントは常に **General** で設定した言語で書かれます。 |
| **Model** | **Routing default** は AI プロバイダーのルーティングに従います。BYOK モデルの 1 つを選ぶこともできます。BYOK モデルがない場合は Kodus のモデルを使います。 |

## Try it

**Try it** は、画面上のエージェントを保存の有無にかかわらずそのまま、リポジトリの 1 つのプルリクエストで実行します。何も投稿されません。

<Steps>
  <Step title="プルリクエストのリンクを貼る">
    エージェントのページで、このリポジトリのプルリクエストのリンクを貼り、**Run agent** をクリックします。大きな変更では数分かかります。
  </Step>

  <Step title="結果を読む">
    ヘッダーには、指摘の数、保持された数、投稿される数が表示されます。その下に：

    * **Warnings**：実行で失われたもの。チェックアウトなし（エージェントは diff だけを読んだ）、インストールできなかった CLI、使えなかった skill や doc など
    * **Skills opened**：エージェントが読んだ参照ファイルとともに
    * ツール呼び出し：それぞれの入力と出力（CLI の出力を含む）
    * 指摘：それぞれ **kept**、**dropped**、**unverified** のいずれかで、理由、引用したルール、投稿される **Comment** 付き
  </Step>

  <Step title="変更して再実行">
    指示、glob、ツールを編集して再実行します。実行後に編集すると、結果が以前のバージョンのものであるとページが警告します。
  </Step>
</Steps>

Try it はリポジトリとディレクトリのレベルで使え、コードレビュー設定の編集権限が必要です。エージェントの glob に一致する変更ファイルがない場合、実行はスキップされ、その理由が表示されます。

## プルリクエストで 1 つのエージェントを実行する

1 行目にエージェントのコマンド名を書いて、プルリクエストにコメントします。

```
@kody -v data-contracts
```

Kody はそのエージェントだけを、エージェントがオフでもプルリクエスト全体に対して実行し、コメントを投稿します。Kody 自身のレビュアーは実行されず、このコマンドでプルリクエストが承認されることはありません。その名前に応答するエージェントがない場合、Kody は存在する名前を返信します。

## レビューでの実行の流れ

<Steps>
  <Step title="エージェントの選択">
    glob が少なくとも 1 つの変更ファイルに一致する、オンのエージェントがすべて実行されます。一致するファイルのないエージェントは実行されません。
  </Step>

  <Step title="レビュー">
    各エージェントは Kody のレビューと並行して自分のファイルだけをレビューし、指示が求めることだけを報告します。skills と docs はターゲットブランチから読み、ツールを使います。
  </Step>

  <Step title="指摘ごとのチェック">
    規約に関する指摘は、紐付けたガイドまたはエージェントの指示から、適用したルールを引用する必要があります。ターゲットブランチのガイドにない引用は破棄されます。"..." で短縮した引用は、各部分が順番どおりに存在すれば通ります。その後、検証器がエージェントの担当範囲外の指摘やコードに裏付けのない指摘を破棄します。ast-grep のマッチはそれ自体が証拠になります。
  </Step>

  <Step title="エージェントの設定を適用">
    エージェントの最小重大度、次にコメント上限（重大度の高いものが残ります）。
  </Step>

  <Step title="メインレビューとの統合">
    エージェントと Kody が同じ問題を報告した場合、コメントは 1 つだけ残ります。エージェントの担当範囲内のチームルールならエージェントのコメントが、それ以外は Kody のコメントが残ります。
  </Step>

  <Step title="投稿">
    コメントにはエージェントのタグが付きます。規約のコメントは適用したルール（ガイドとその文言、または "agent's instructions"）を引用します。CLI に基づく指摘は、ファイルを名指しする CLI 出力の行を **Evidence** に表示します。
  </Step>
</Steps>

各エージェントのコメントにはそのタグが付くため、プルリクエスト上でどのエージェントの発言かがわかります。エージェントのページには、過去 30 日間にレビューしたプルリクエストと投稿したコメントが表示されます。

## 制限

| 制限 | 値 |
| - | - |
| Instructions | 8,000 文字 |
| How it writes | 2,000 文字 |
| エージェントあたりの CLI | 3 |
| エージェント（およびメインレビュー）あたりの skills | 20 |
| エージェント（およびメインレビュー）あたりの docs | 10 |
| エージェント（およびメインレビュー）あたりの doc トークン | 20,000 |
| ast-grep ルール | 64,000 バイト |

## FAQ

<AccordionGroup>
  <Accordion title="エージェントが実行されなかったのはなぜですか？">
    次の順に確認してください。

    * **オフ**になっている。新しいエージェントはオフで始まります。`@kody -v <名前>` ならそれでも実行されます。
    * **Files** の glob に一致する変更ファイルがない、またはすべて **Except** に該当する。
    * ファイルがリポジトリの無視パスにあり、glob がそれを名指ししていない。ファイルを明示的に名指ししてください（[Files & knowledge](#files--knowledge) を参照）。
    * プルリクエストでファイルが削除された。
    * 独自のリストを持つリポジトリには、後からグローバルレベルで追加したエージェントは届きません。
    * ディレクトリで、レビューがリポジトリの設定を使った（例：プルリクエストが設定済みの 2 つのディレクトリに触れた）。
  </Accordion>

  <Accordion title="指摘が破棄されたのはなぜですか？">
    同じプルリクエストで **Try it** を実行してください。破棄された各指摘に理由が表示されます。よくある理由：

    * 引用がターゲットブランチのガイドにない（言い換えられた、またはガイドがプルリクエスト内でだけ変更された）。
    * 指摘がエージェントの指示の範囲外。
    * 検証器がコードに裏付けを見つけられなかった。
    * エージェントの最小重大度を下回った、またはコメント上限を超えた。
    * Kody のレビューが同じ問題を報告し、そのコメントが残った。
  </Accordion>

  <Accordion title="kodus-config.yml でエージェントを設定できますか？">
    できません。`kodus-config.yml` の `customAgents` と `knowledge` は読み込まれません。最終コメントに "kodus-config.yml: customAgents is not read from this file; configure custom agents in the app." と表示されます。
  </Accordion>

  <Accordion title="プルリクエストが自分を評価するルールを変更できますか？">
    できません。skills、docs、ast-grep のルールファイルはプルリクエストのターゲットブランチから読み込まれます。プルリクエスト内での編集はマージ後に反映されます。
  </Accordion>

  <Accordion title="エージェントを削除すると過去のコメントはどうなりますか？">
    過去のプルリクエストの指摘はそのまま残ります。skills と docs も Skills & docs ページに登録されたままです。
  </Accordion>
</AccordionGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.