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

リポジトリにmarkdownをコミットして、Aikidoエージェントがアーキテクチャ、信頼境界、受容済みのリスクに従えるようにします。

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が読み取れるよう、ドキュメントは含めたままにしてください。

AGENTS.md

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

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

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

具体的に書く。 「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）のルール、カスタムコードルール、.aikidoによる無視設定は、引き続きそれぞれ独立して適用されます。