AGENTS.md のベストプラクティスと具体例（C# / ASP.NET Core 想定）

Cursor の Agent に「このリポジトリではこう動いてほしい」を伝える一番手軽な手段が AGENTS.md。プレーンな Markdown なのでチームでも読みやすい。

この記事では、書き方のベストプラクティスと、C# / ASP.NET Core 想定の具体例をまとめる。例として架空プロダクト OrderNest（受注 API + バックグラウンド処理）を使う。

先に結論

AGENTS.md には「このプロジェクトは何か・どこにあるか・どう検証するか」を短く書く
適用条件を細かく分けたい規約は .cursor/rules/*.mdc へ
長くなりすぎたら分割（目安は Rules と同様、肥大化させない）
サブディレクトリの AGENTS.md は親と結合され、より具体が優先
Cloud 用は見出し Cursor Cloud specific instructions を用意する

AGENTS.md とは

プロジェクト（またはサブディレクトリ）に置く Agent 向け指示ファイル。frontmatter 不要の Markdown。.cursor/rules のシンプルな代替として公式に案内されている。

.cursor/rules との使い分け

AGENTS.md … プロジェクト概要、ディレクトリ地図、ビルド／テスト、やってはいけないこと（常に読ませたい文脈）
.cursor/rules/*.mdc … パス glob や適用条件付きの細かい規約（例: EF Core だけ、Tests だけ）
同じ内容を二重に書かない。重複はトークンを食う

目安: 「何のリポジトリ？」→ AGENTS.md。「この層ではこう書け」→ rules。

ベストプラクティス

書くと効くもの

プロダクト目的を1〜2文
ディレクトリ → 責務の地図
ビルド / テスト / 起動の実コマンド
絶対に壊したくない制約（認証、金銭、個人情報など）
参照してほしい既存パターン（パスで示す。コード全文はコピーしない）
Cloud 向けのセットアップ・検証手順（専用見出し）

避けた方がいいもの

スタイルガイドの丸写し（Formatter / Analyzer に任せる）
dotnet / git など一般知識の羅列
まれなエッジケースの百科事典化
コードベースの長い貼り付け（すぐ陳腐化する）
曖昧な「きれいに書いて」「適切に」

分量と育て方

小さく始めて、同じミスが繰り返されたら1項目足す
肥大化したらネストの AGENTS.md や Skills / rules に逃がす
公式の Rules ベストプラクティスに沿い、焦点が明確・実行可能・スコープ限定を意識する

ネスト

OrderNest/
  AGENTS.md                 # 全体
  src/Api/AGENTS.md         # API 固有
  src/Workers/AGENTS.md     # Worker 固有
  tests/AGENTS.md           # テスト固有（任意）

作業中ディレクトリの指示が親と結合され、より具体的な指示が優先される。

想定プロダクト: OrderNest

以降の例で使う架空プロダクト。

内容: B2B 受注の Web API + 非同期ワーカー
スタック: .NET 8 / ASP.NET Core / EF Core / SQL Server（ローカルはコンテナ）
構成: シンプルな Clean Architecture 風（Api / Application / Domain / Infrastructure / Workers）

OrderNest/
├── AGENTS.md
├── OrderNest.sln
├── src/
│   ├── Api/
│   ├── Application/
│   ├── Domain/
│   ├── Infrastructure/
│   └── Workers/
└── tests/
    ├── Api.Tests/
    └── Application.Tests/

具体例: ルート AGENTS.md

OrderNest ルートに置く例。コピーして自プロジェクト名に差し替えれば使える。

# OrderNest — Agent Instructions

## Product
B2B 受注を扱う ASP.NET Core API と、通知・集計用 Worker。
UI は別リポジトリ。このリポジトリは API / Worker / ドメインのみ。

## Stack
- .NET 8 / C#
- ASP.NET Core Minimal APIs + Controllers 混在（新規は Minimal API 優先）
- EF Core + SQL Server
- xUnit / FluentAssertions / Testcontainers（統合テスト）

## Repo map
- `src/Api` … HTTP 入出力。薄い。ビジネス判断をここに書かない
- `src/Application` … ユースケース / バリデーション / DTO 変換
- `src/Domain` … エンティティとドメインルール。インフラ依存禁止
- `src/Infrastructure` … EF Core、外部 API、メール等
- `src/Workers` … キュー消費・定期処理
- `tests/*` … プロジェクト名に対応

## Commands
- 復元: `dotnet restore OrderNest.sln`
- ビルド: `dotnet build OrderNest.sln -c Release`
- 単体: `dotnet test tests/Application.Tests`
- 統合: `dotnet test tests/Api.Tests`（Docker 必須）
- API 起動: `dotnet run --project src/Api`
- Worker 起動: `dotnet run --project src/Workers`

## Invariants（破らない）
- 金額・税計算は Domain / Application。Api で再計算しない
- 個人情報・接続文字列をログに出さない
- 外部決済呼び出しは Infrastructure 経由のみ
- マイグレーション追加時は理由を PR 説明に書く

## Patterns to follow
- 新規ユースケースは `src/Application/Orders/` 配下の既存ハンドラを真似る
- 結果型は `Result<T>`（成功/失敗）。例外は想定外のみ
- DI 登録は `src/Infrastructure/DependencyInjection.cs`

## Do not
- Domain から EF Core / HttpClient を参照しない
- コントローラで DbContext を直接触らない
- 秘密情報を appsettings に直書きしない（User Secrets / 環境変数）

## PR expectations
- 関連テストを更新または追加
- `dotnet build` と関係テストが通る状態にする

ネスト例: src/Api/AGENTS.md

# Api layer

## Scope
HTTP の入出力と認証・認可の配線だけを担当する。

## Prefer
- 新規エンドポイントは Minimal API（`src/Api/Endpoints/`）
- 入力検証の詳細は Application に委譲
- 問題レスポンスは既存の ProblemDetails ヘルパーを使う

## Avoid
- ここで業務ルールや税計算を実装しない
- エンドポイント内で EF Core を new / 直接利用しない

ネスト例: src/Workers/AGENTS.md

# Workers

## Scope
キューとスケジュール起動のホスト。再実行可能（idempotent）を優先。

## Prefer
- 1 メッセージ 1 ハンドラ
- 失敗はログ + 規定のリトライ。無限ループしない
- 長時間処理はキャンセルトークンを必ず繋ぐ

## Avoid
- UI / HTTP 向け DTO を Worker に持ち込まない
- ハンドラから他 Worker を直接 new しない

Cloud 向けセクション例

公式では見出し名として Cursor Cloud specific instructions が推奨されている。ルート AGENTS.md の末尾に足す例:

## Cursor Cloud specific instructions

### Environment
- .NET 8 SDK が使えること
- 統合テストは Docker が必要。使えない場合は Application.Tests のみ実行し、その旨を報告する
- DB 接続情報は Secrets / 環境変数。リポジトリ内のダミー接続文字を本番扱いしない

### Verify before finish
1. `dotnet restore OrderNest.sln`
2. `dotnet build OrderNest.sln -c Release`
3. `dotnet test tests/Application.Tests --no-build`
4. Docker 利用可なら `dotnet test tests/Api.Tests --no-build`

### Notes
- ローカル専用の VPN リソースには触れない
- 大きな手順（リリース手順など）は Skills 側を優先。ここには完了条件だけ書く

rules / Skills への逃がし方

「Infrastructure のリポジトリ実装だけの規約」→ .cursor/rules/ef-core.mdc（globs で絞る）
「障害調査の長い手順」→ .cursor/skills/order-debug/SKILL.md
AGENTS.md は地図と完了条件。百科にはしない

よくある失敗

全部を AGENTS.md に書いて肥大化 → Agent の文脈を圧迫
「クリーンに」「ベストプラクティスで」だけ → 実行不能
コマンドが古いまま → Agent が毎回コケる。CI と同じコマンドを書く
rules と内容が矛盾 → どちらを信じるか不明。片方に寄せる

ざっくりまとめ

AGENTS.md = Agent 向けのプロジェクト説明書（短く具体的に）
必須要素: 目的・地図・コマンド・不変条件・やってはいけないこと
層ごとの詳細はネスト、条件付き規約は rules、長い手順は Skills
Cloud は専用見出しで検証手順を明示
C# では「層の境界」と「dotnet の検証コマンド」を書いておくと効きやすい

まずはルートに1枚、OrderNest 例の見出しだけ埋めるところからで十分。繰り返し直させている指示が出てきたら、そのとき項目を足す。