# リポジトリファイルでエージェントをガイドする

Aikidoエージェントはリポジトリ内のmarkdownを読み取ります。これは、ペンテスト、Code Quality、Deep Review、AI Code AnalysisなどすべてのAI機能に適用されます。これらのファイルを使って、システムの構成、意図された動作、すでに受容しているリスクを説明してください。

Aikidoがコードをレビューするたびに適用すべきガイダンスは、リポジトリにコミットしてください。ソースにないコンテキストで、その実行にのみ適用されるものは、単一実行のノートを使用してください。

## markdownファイルを追加する

恒常的な指示は、リポジトリのルートにある`AGENTS.md`に記述します。Aikidoは、受容済みのリスクについて以下のファイルも確認します：

* `CLAUDE.md`
* `.claude/`
* `.cursor/`

これらのファイルですでに受容されているリスクは、変更によってそのリスクが拡大しない限り、報告されません。

`AGENTS.md`はリポジトリのルートに置いてください。`README.md`、`ARCHITECTURE.md`、`SECURITY.md`も、アーキテクチャや脅威モデルの詳細に引き続き役立ちます。詳細が別のファイルにある場合は、`AGENTS.md`からリンクしてください。

**Exclude Paths**では、関係のないアプリケーションやサービスを除外してください。Aikidoが読み取れるよう、ドキュメントは含めたままにしてください。

{% code title="AGENTS.md" overflow="wrap" %}
```markdown
# Security context

## Trust boundaries

The public API is `api/`. Handlers under `internal/` are only reachable from the service mesh. Missing authentication on `internal/` is accepted. Report the same pattern under `api/`.

## Authentication

End-user requests are authenticated at the gateway. This service trusts the `X-User-Id` header set by that gateway.

## Accepted risks

`scripts/migrations/` is one-off operational code. Do not report missing error handling there.
```
{% endcode %}

## エージェントが従える指示を書く

パス、ロール、またはフローを明示し、エージェントが何を意図された動作として扱うべきかを記述します。また、引き続き報告すべきものも記述してください。

* **具体的に書く。** 「`billing/refunds`の管理者は任意のテナントを読み取れる。他のルートで同じチェックが欠けている場合は報告すること。」
* **意図された動作とバグを区別する。** 「Webhookの署名は、トラフィックがこのサービスに到達する前にゲートウェイで検証される。」
* **見出しを使う。** 1セクションにつき1トピックにして、エージェントが関連部分を見つけられるようにします。
* **シークレットを含めない。** 認証情報、トークン、顧客データ、本番環境の接続文字列はコミットしないでください。
* **例外は狭く保つ。** 「セキュリティの問題を無視する」と書くと、実際の検出結果が隠れてしまいます。フォルダや動作を具体的に指定してください。

## コンテキストの置き場所を選ぶ

| 場所                      | 使用するタイミング                                                                                                                                        |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------- |
| リポジトリ内のmarkdown | Aikidoがこのリポジトリをレビューするたびに適用すべきコンテキスト：アーキテクチャ、信頼境界、受容済みのリスク、フローの意図された動作。 |
| 単一実行のノート      | ソースにはなく、その実行にのみ適用されるコンテキスト。最大2000文字。ランタイム設定、プロキシ、一回限りの例外など。  |
| **Exclude Paths**          | モノレポ内の関係のないアプリケーションを除外します。ドキュメントは含めたままにしてください。                                                                            |

ノートはその実行に適用されます。markdownファイルはリポジトリに残るため、次回のレビューでも使用できます。永続的なガイダンスはファイルに記述し、ファイルでカバーされない内容にはノートを使用してください。

## 含める内容

* リクエストの入り口と、どのフォルダが本番コードであるか。
* 信頼境界、認証、認可、マルチテナントのルール。
* 受容済みのリスクと、引き続き報告すべきもの。
* 意図的に公開または内部扱いとしているデータと、ゲートウェイがフィールドを秘匿する場所。
* リポジトリにコントラクトが含まれる場合は、信頼された管理者、キーパー、オラクルのロール。対象チェーンやデプロイ済みアドレスがリポジトリにない場合は、実行ノートに記述してください。
* クラウドアカウントの分離方針と、どの例外が意図的なものか。Infrastructure as Code（IaC）リポジトリ内のmarkdownで、稼働中の設定がどのように定義されているかを説明します。
* チームがすでに受け入れている品質に関する規約（厳密なエラー処理が適用されない箇所など）。

## FAQ

### Aikidoはすべてのmarkdownファイルを読み込みますか？

Aikidoは、受容済みのリスクについて`AGENTS.md`、`CLAUDE.md`、`.claude/`、`.cursor/`を確認します。`AGENTS.md`は短くしてリポジトリのルートに置き、長い説明はそこからリンクしてください。

### これらのファイルはルールや無視設定に置き換わりますか？

これらのファイルはエージェントをガイドするものです。[静的アプリケーションセキュリティテスト（SAST）](https://help.aikido.dev/docs/docs-ja/code-scanning/scanning-practices/sast-by-aikido-supported-languages-and-security-focus)のルール、[カスタムコードルール](https://help.aikido.dev/docs/docs-ja/code-quality/add-custom-code-rules)、[`.aikido`による無視設定](https://help.aikido.dev/docs/docs-ja/code-scanning/scanning-practices/ignore-via-code-with-aikido-files)は、引き続きそれぞれ独立して適用されます。

## 関連項目

{% content-ref url="../pentests/configure-a-pentest/leveraging-code-and-documentation.md" %}
[leveraging-code-and-documentation.md](https://help.aikido.dev/docs/docs-ja/pentests/configure-a-pentest/leveraging-code-and-documentation)
{% endcontent-ref %}

{% content-ref url="../code-quality/add-extra-code-context.md" %}
[add-extra-code-context.md](https://help.aikido.dev/docs/docs-ja/code-quality/add-extra-code-context)
{% endcontent-ref %}

{% content-ref url="../deep-review/how-deep-review-works.md" %}
[how-deep-review-works.md](https://help.aikido.dev/docs/docs-ja/deep-review/how-deep-review-works)
{% endcontent-ref %}

{% content-ref url="../ai-code-analysis/ai-code-analysis.md" %}
[ai-code-analysis.md](https://help.aikido.dev/docs/docs-ja/ai-code-analysis/ai-code-analysis)
{% endcontent-ref %}

{% content-ref url="../ai-code-analysis/ai-code-audit-overview/create-an-ai-code-audit.md" %}
[create-an-ai-code-audit.md](https://help.aikido.dev/docs/docs-ja/ai-code-analysis/ai-code-audit-overview/create-an-ai-code-audit)
{% endcontent-ref %}

{% content-ref url="../ai-code-analysis/what-is-dspm/data-exposure-audit.md" %}
[data-exposure-audit.md](https://help.aikido.dev/docs/docs-ja/ai-code-analysis/what-is-dspm/data-exposure-audit)
{% endcontent-ref %}

{% content-ref url="../ai-code-analysis/cloud-security-audit/run-a-cloud-security-audit.md" %}
[run-a-cloud-security-audit.md](https://help.aikido.dev/docs/docs-ja/ai-code-analysis/cloud-security-audit/run-a-cloud-security-audit)
{% endcontent-ref %}

{% content-ref url="../ai-code-analysis/smart-contract-audit/run-a-smart-contract-audit.md" %}
[run-a-smart-contract-audit.md](https://help.aikido.dev/docs/docs-ja/ai-code-analysis/smart-contract-audit/run-a-smart-contract-audit)
{% endcontent-ref %}