> ## 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.

# ベストプラクティス

> プルリクエストの本当の問題を見つけ、それ以外では静かなカスタムエージェントを書きます。

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

## 1 つの関心事に 1 つのエージェント

アーキテクチャ、セキュリティ、テストカバレッジを一度に見るエージェントは、曖昧な指示を持ち、曖昧な指摘を返します。分割してください。関心事ごとに 1 つのエージェントを作り、それぞれにファイル、ガイド、タグを持たせます。タグで誰の発言かがわかり、各エージェントのページに過去 30 日間の投稿が表示されるので、どのエージェントがうるさいかがわかります。

## 焦点を絞った指示を書く

指示は、コードベースを知るレビュアーへのブリーフとして書きます。次の 3 点をカバーしてください。

1. **何を探すか**を具体的に：「アーキテクチャの問題」ではなく「`src/domain` から `src/http` への import」。
2. **何を無視するか**：スタイル、命名、他のエージェントや Kody がすでにカバーしていること。
3. **指摘にどんな証拠が必要か**：「既存のパターンを示すファイルを挙げる」「ソースからシンクまでの経路を示す」「`docs/ledger.md` のルールを引用する」。

エージェントは指示が求めることだけを報告し、検証器はその範囲外のものを破棄します。指示が求めていない指摘は、目にすることがありません。

<Tabs>
  <Tab title="曖昧">
    ```text theme={null}
    Review the code for quality and best practices.
    ```
  </Tab>

  <Tab title="焦点が明確">
    ```text theme={null}
    Flag code in src/http/** that imports from src/infra/** directly.
    Handlers reach infrastructure only through the ports in src/domain/ports.
    Ignore tests, generated code and naming.
    For each finding, name the port the handler should use, or say that
    none exists yet.
    ```
  </Tab>
</Tabs>

## 指摘に必要な証拠を書く

指摘は投稿前にチェックされます。エージェントが証明できるものを与えてください。

* **ガイドのルール**：doc や skill を紐付け、ルールを引用するよう指示します。引用はターゲットブランチのガイドで確認されます。
* **CLI の結果**：ファイルを名指しする CLI 出力の行が、証拠としてコメントに入ります。
* **ast-grep ルール**：マッチはそれ自体が証拠で、モデルによるチェックは不要です。

誰かの頭の中にしかないルールは引用できないので、指示か doc に書いてください。

## glob を明示する

* **Files** にはエージェントが気にするコードを設定します。空ではなく `src/payments/**` のように。glob のないエージェントはすべてのプルリクエストで実行されます。
* テスト、フィクスチャ、生成コードには **Except** を使います。
* 無視パスにあるがエージェントには読ませたいファイルは、明示的に名指しします：`package.json`、`infra/**/*.tf`。`**/*.ts` のような広い glob や `src/**` のようなフォルダ指定は、無視されたファイルに届きません。
* ディレクトリレベルでも、glob はリポジトリのルートから書きます。

## Skill か doc か

| **doc** を使うとき | **skill** を使うとき |
| - | - |
| ガイドが短く、エージェントがレビューするすべての変更に当てはまる。 | ルールが多い、または一部の変更にだけ当てはまる。 |
| 毎回全体を読ませたい。 | 変更が必要とするときだけ、参照ファイルとともに開かせたい。 |

docs はエージェントごとに 20,000 トークンの予算を消費します。長いハンドブックは、参照ファイル付きの skill にするほうが適しています。

## オンにする前に実際のプルリクエストで試す

新しいエージェントはオフで始まります。オンにする前に：

1. エージェントのファイルに触れる最近のプルリクエストを選びます。良いレビュアーなら何を言うか分かっているものが理想です。
2. **Try it** を実行します。ツール呼び出し、開いた skills、すべての指摘を読みます。
3. 指示、glob、最小重大度を調整して、再実行します。
4. 投稿されるコメントがプルリクエストに付いてほしいものになったら、オンにします。

`@kody -v <名前>` は、エージェントがまだオフの状態で、実際のプルリクエストに同じことを行い、コメントを投稿します。

## 破棄の理由を読む

破棄された指摘は、エージェントの何を直すべきかを教えてくれます。

| 理由 | 変えること |
| - | - |
| 引用が見つからない | ターゲットブランチのガイドにその文言がありません。正しいガイドを紐付けるか、ルールを指示に書きます。 |
| エージェントの担当範囲外 | 指示が求めていません。追加するか、Kody に任せます。 |
| コードに裏付けがない | エージェントが推測しました。指示で具体的な証拠を求めます。 |
| 最小重大度未満、またはコメント上限超過 | 想定どおりのフィルタリングです。もっと見たいなら下限を下げます。 |

## 量を適切に保つ

* 重複コードのエージェントのように多くの指摘を出しうるものには **Max comments per pull request** を設定します。重大度の高いものが残ります。
* カバレッジレポートのように、まとめて読むほうがよい指摘には **One PR comment** を使います。
* アーキテクチャの移動のように修正が推測になる場合は **Suggested fix: Never** を使います。


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