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

# ベストプラクティスドキュメントをレビューガードレールに変換する

> エンジニアリングハンドブックをオプションのMCPプラグインと組み合わせた、生きたKodyルールに変換する方法。

## このガイドが重要な理由

すべてのエンジニアリングチームには、どこかに「ベストプラクティス」ドキュメントがあります。問題は、IDE の提案がそれを読まず、レビュアーが細かいニュアンスを忘れ、ドキュメントが徐々に権威を失っていくことです。このガイドでは、ハンドブックをアクティブなガードレールに変換して、Kodyがそれらのルールを自動的に適用し、コードがルールから外れるたびに関連セクションを引用する方法を示します。

2つの構成要素に焦点を当てます：

* [Kodyルール](/how_to_use/ja/code_review/configs/kody_rules) – 各ポリシーの箇条書きを確定的なファイルレベルまたはPRレベルのチェックとしてエンコードする。
* [カスタムプラグイン](/cookbook/ja/custom-plugin-install) – 信頼できる情報源がGitの外部にある場合、リモートMCPサーバーから標準を取得する。

このフローに従えば、どのリポジトリも「ハンドブックPDF」から「生きたポリシーパック」へと進化できます。

## 事前確認チェックリスト

* **コードレビュー設定 → Kodyルール** を編集する権限がある。
* ポリシーパックがリポジトリ内に存在する（例：`docs/engineering-standards.md`）。別のパスにある場合は適宜調整してください。Notion、Confluence、またはGoogle Docsにある場合は、リモートMCPエンドポイントを通じて公開する計画を立ててください。
* どのトピックをファイルレベル（コントローラー、設定）とPRレベル（フィーチャーフラグ、ロールアウトの説明、アーキテクチャ）で評価すべきかを把握している。

<Callout icon="layers">
  ハンドブックをバージョン管理下に置いてください。すべての編集はオーナーが承認するPRを通じて行うべきです。この規律がルールを現実に根ざしたものに保ちます。
</Callout>

## フェーズ1 – ルールに適したポリシーパックを作成する

1. `docs/engineering-standards.md` のようなマークダウンファイルを作成または再利用します。唯一の要件：Kodyが `@file:...` 経由で参照できることです。
2. コンテンツを短い、チェック可能な箇条書きに整理します：

```md theme={null}
# エンジニアリング標準

## エラー処理
- エラーを握りつぶさない。
- PIIやシークレットをログに記録しない。
- 外部リクエストにはタイムアウトとリトライポリシーが必要。

## アーキテクチャ
- `domain/*` から `web/*` への直接のクロスモジュールインポートは禁止。
- 新しいエンドポイントにはトレースフィールド（例：requestId）と構造化ログが必要。
- リスクの高い変更にはフィーチャーフラグが必須。
```

3. `[Owner: Backend Platform]` や `[Risk: High]` のようなメタデータを追加して、違反のルーティングに役立てます。

<Info>
  信頼できる情報源がGitの外部にある場合は、同じ構造を採用しますが、リモートMCPサーバーを通じて公開してルールが `@MCP:policy_pack.getSection(...)` を呼び出せるようにします。
</Info>

<Tip>
  各箇条書きをアトミックにしてください。ルールが発火したとき、何を変更する必要があるかについて議論の余地がないようにします。
</Tip>

## フェーズ2 – すべてのルールを実際のドキュメントに向ける

ルールはファイルとリモートMCPペイロードを読み取ることができます。各指示にスニペットを貼り付けるのではなく、実際のハンドブックを参照します。

```text theme={null}
@file:docs/engineering-standards.md（アーキテクチャセクション）をポリシーソースとして使用する。
それらの箇条書きを明確に違反するコードのみにフラグを立てる。セクションが見つからない場合はその旨を伝える。
```

* ドメイン固有のパック（例：`@file:docs/mobile.md`）用に他のファイルパスを置き換える。
* ファイルの一部だけが必要な場合は、行アンカーを追加します—`@file:docs/engineering-standards.md#L40-L72`—ルールがそのセクションのみを参照するように。
* ポリシーがNotion/Confluenceなどから来る場合は、ファイル参照を `@MCP:policy_pack.getSection({"id":"security"})` に置き換える。
* ルールが静的テンプレートと動的データの両方を必要とする場合は両方を組み合わせる（例：ログフォーマット用の `@file` + 現在の機密フィールド用の `@MCP:piiRegistry.list()`）。

<Callout icon="link">
  1つの参照ですべてを同期に保てます。ハンドブックを一度更新すれば、すべてのルールが最新バージョンを適用します。
</Callout>

## フェーズ3 – セクションをKodyルールに変換する

**コードレビュー設定 → Kodyルール** を開き、各ポリシーセクションを適切なスコープにマッピングします。

| ポリシーセクション    | ルールタイプ     | スコープの例                            | 重要度 |
| ------------ | ---------- | --------------------------------- | --- |
| エラー処理        | ファイルレベル    | `backend/**/*.ts`                 | 高   |
| アーキテクチャ      | PRレベル      | `pr_files_diff` 経由の全ファイル          | 重大  |
| ロギングとトレーシング  | ファイルレベル    | `web/apps/**/controllers/**/*.ts` | 中   |
| セキュリティ / PII | ファイル + MCP | `**/*` PIIリスト取得付き                 | 重大  |

### ファイルレベルの例

```
Name: 新しいエンドポイントにトレースフィールドを適用する
Scope: File
Paths: web/apps/**/controllers/**/*.ts
Severity: High
Instructions:
  fileDiffを @file:docs/engineering-standards.md の「アーキテクチャ → 新しいエンドポイント」と比較する。
  requestIdトレーシングと構造化ログステートメントの両方が欠けているハンドラにフラグを立てる。
  ポリシーに違反する差分チャンクを引用する。
```

### PRレベルの例

```
Name: リスクの高い変更にはフィーチャーフラグが必要
Scope: Pull Request
Severity: Critical
Instructions:
  pr_files_diffs で主要な機能を追加するルート/サービス/ドメインファイルをスキャンする。
  フィーチャーフラグファイルが変更されていない場合、「アーキテクチャ → フィーチャーフラグは必須」を引用し、ロールアウト計画を要求する。
```

ルールを評価するために最新データが必要な場合は、指示内でMCPを呼び出します：

```
@MCP:policy_pack.getSection({"id":"security"}) を使用して最新の制限フィールドを取得する。
```

<Info>
  ルールはすでに変数（`fileDiff`、`pr_files_diff` など）、ファイル参照、MCPの呼び出しを理解しています。完全なマトリックスは [Kodyルールガイド](/how_to_use/ja/code_review/configs/kody_rules) を参照してください。
</Info>

## フェーズ4 – MCP経由で外部標準をミラーリングする（オプション）

ハンドブック（またはその一部）がNotion、Confluence、Google Docs、または別のシステムに残る必要がある場合もあります。それでもKodyに供給できます：

1. `listSections()` と `getSection(id)` を公開するリモートMCPエンドポイントを構築または採用します。
2. **カスタムプラグインを追加** からインストールします。正確なフローについては [カスタムプラグインガイド](/cookbook/ja/custom-plugin-install) に従ってください。
3. `@file` 参照を `@MCP:policy_pack.getSection({"id":"architecture"})` に置き換えます。
4. MCPサーバー上でレスポンスをキャッシュして、複数のルールがレビューごとにペイロードを共有できるようにします。

これで、ドキュメントがどこにあるかに関わらず、Kodyは同じ標準を適用します。

## フェーズ5 – テスト、観察、維持

<AccordionGroup>
  <Accordion title="検証PRを作成する">
    各セクションに違反する使い捨てPRを作成します。@kodyをメンションして、インラインとPRレベルのコメントが正しい箇条書きを引用していることを確認します。
  </Accordion>

  <Accordion title="ノイズと重要度を調整する">
    ロールアウト中に、各ルールが発火する頻度を観察します。シグナルが期待に合うまで、ファイルグロブを絞り込み、除外を追加するか、重要度を調整します。
  </Accordion>

  <Accordion title="ドキュメントとルールを一緒に更新する">
    ハンドブックが変更されるたびに、レビュアーがパイプライン全体を検証できるよう、マークダウン（またはMCPペイロード）と関連ルールを同じPRで更新します。
  </Accordion>
</AccordionGroup>

## クイックチェックリスト

* [ ] `docs/engineering-standards.md`（またはMCP相当）が、スキャン可能でタグ付きの箇条書きで存在する。
* [ ] すべてのルールが `@file` または `@MCP` 経由でポリシーパックを参照し、最新のテキストを読み取ることを保証している。
* [ ] ファイルレベルとPRレベルのKodyルールが重要なセクションをカバーしている。
* [ ] オプションのMCPプラグインが必要に応じてリポジトリ外の標準をミラーリングしている。
* [ ] ドライランPRが広範なロールアウト前にインラインコメントとPRサマリーを確認した。