はじめに
前回の記事「AGENTS.md入門」では、AGENTS.mdの基本的な役割、配置ルール、スコープと優先順位について解説しました。本記事では、実際のプロジェクト構成に合わせたAGENTS.mdの具体的な記述例を紹介します。
フロントエンド、バックエンド、フルスタック、そしてモノレポ構成と、さまざまなプロジェクトタイプに対応したテンプレートを用意しました。これらをベースに、自分のプロジェクトに最適化されたAGENTS.mdを作成し、Codexのパフォーマンスを継続的に改善していきましょう。
フロントエンドプロジェクトのAGENTS.md
フロントエンド開発では、コンポーネント設計、状態管理、スタイリング、ビルド設定など、Codexに伝えるべきコンテキストが多岐にわたります。
React + TypeScript プロジェクト
|
|
src/ ├── components/ # 再利用可能なUIコンポーネント │ ├── ui/ # shadcn/uiベースの基本コンポーネント │ └── features/ # 機能固有のコンポーネント ├── hooks/ # カスタムReact Hooks ├── lib/ # ユーティリティ関数 ├── pages/ # ルーティングされるページ ├── services/ # APIクライアント ├── stores/ # Zustandストア └── types/ # 型定義
## コンポーネント設計規約
### ファイル命名
- コンポーネント: PascalCase（例: `UserProfile.tsx`）
- フック: camelCase、useプレフィックス（例: `useAuth.ts`）
- ユーティリティ: camelCase（例: `formatDate.ts`）
- 型定義: PascalCase（例: `User.ts`）
### コンポーネント構造
1. 型定義（Props）
2. コンポーネント本体
3. サブコンポーネント（必要な場合）
\`\`\`typescript
// 推奨パターン
type UserCardProps = {
user: User
onSelect?: (id: string) => void
}
export function UserCard({ user, onSelect }: UserCardProps) {
return (...)
}
\`\`\`
### 状態管理の使い分け
- **ローカル状態**: useState（コンポーネント内で完結）
- **グローバル状態**: Zustand（認証、UIテーマなど）
- **サーバー状態**: TanStack Query（API由来のデータ）
### 禁止パターン
- `any`型の使用
- インラインスタイル（Tailwindを使用）
- useEffectでのデータフェッチ（TanStack Queryを使用）
- propsのスプレッド展開（明示的に記述）
## スタイリング規約
- Tailwind CSSのユーティリティクラスを使用
- カスタムCSSは`src/styles/`に配置
- レスポンシブはモバイルファーストで設計
- カラーはテーマ変数を使用（`bg-primary`など）
## インポート順序
1. React関連
2. 外部ライブラリ
3. 内部モジュール（`@/`エイリアス）
4. 型定義
5. スタイル
各グループ間に空行を入れてください。
Vue 3 + Nuxt 3 プロジェクト
|
|
├── components/ # Vueコンポーネント（自動インポート） ├── composables/ # Composition API関数（自動インポート） ├── layouts/ # レイアウトコンポーネント ├── middleware/ # ルートミドルウェア ├── pages/ # ファイルベースルーティング ├── plugins/ # Nuxtプラグイン ├── server/ # サーバーAPI（Nitro） ├── stores/ # Piniaストア └── types/ # 型定義
## コーディング規約
### コンポーネント
- `<script setup lang="ts">` を使用
- Composition APIのみ（Options APIは禁止）
- defineProps / defineEmitsで型安全に
- コンポーネント名はPascalCase
### Composables
- `use`プレフィックス必須
- 単一責任の原則に従う
- 戻り値はリアクティブな参照をそのまま返す
### 状態管理
- Piniaストアは`defineStore`で定義
- ストア名は`use[Name]Store`形式
## 禁止パターン
- Options API
- Vuex（Piniaを使用）
- `ref`の`.value`への直接代入（スプレッド構文を避ける）
- テンプレート内での複雑なロジック（computedに抽出）
Next.js App Router プロジェクト
|
|
app/ ├── (auth)/ # 認証関連ルートグループ ├── (dashboard)/ # ダッシュボードルートグループ ├── api/ # API Routes ├── layout.tsx # ルートレイアウト └── page.tsx # ホームページ
components/ ├── ui/ # 汎用UIコンポーネント └── features/ # 機能固有コンポーネント
lib/ ├── actions/ # Server Actions ├── db/ # Prismaクライアント └── utils/ # ユーティリティ
prisma/ └── schema.prisma # データベーススキーマ
## Server Components vs Client Components
### Server Components（デフォルト）
- データフェッチを直接実行
- 機密情報（API Key等）を安全に使用可能
- `'use client'`ディレクティブなし
### Client Components
- インタラクティブな機能が必要な場合のみ
- ファイル先頭に`'use client'`を記述
- 最小限のコンポーネントに限定
## データフェッチ規約
\`\`\`typescript
// Server Componentでの直接フェッチ
async function UserList() {
const users = await prisma.user.findMany()
return <ul>{users.map(...)}</ul>
}
// Server Actionsでのミューテーション
'use server'
export async function createUser(formData: FormData) {
// バリデーション + DB操作
}
\`\`\`
## 禁止パターン
- Client Componentでの直接DB接続
- getServerSideProps / getStaticProps（App Router形式を使用）
- useEffect内でのサーバーデータフェッチ
- 環境変数の`NEXT_PUBLIC_`なしでのクライアント使用
バックエンドプロジェクトのAGENTS.md
バックエンド開発では、API設計、データベース操作、認証認可、エラーハンドリングなどの指示が重要です。
Node.js + Express プロジェクト
|
|
src/ ├── controllers/ # リクエストハンドラ ├── middlewares/ # Expressミドルウェア ├── models/ # Prismaモデル拡張 ├── routes/ # ルート定義 ├── services/ # ビジネスロジック ├── validators/ # Zodスキーマ ├── utils/ # ユーティリティ └── types/ # 型定義
## API設計規約
### エンドポイント命名
- リソース名は複数形: `/users`, `/posts`
- ネストは最大2階層: `/users/:id/posts`
- アクションは動詞: `/auth/login`, `/auth/logout`
### レスポンス形式
\`\`\`json
{
"success": true,
"data": { ... },
"meta": { "page": 1, "total": 100 }
}
\`\`\`
### エラーレスポンス
\`\`\`json
{
"success": false,
"error": {
"code": "VALIDATION_ERROR",
"message": "入力値が不正です",
"details": [...]
}
}
\`\`\`
## エラーハンドリング
- カスタムエラークラスは`src/errors/`に定義
- 全エラーはグローバルエラーハンドラで処理
- 本番環境ではスタックトレースを隠蔽
## セキュリティ規約
- SQLインジェクション: Prismaのパラメータ化クエリを使用
- XSS: レスポンスヘッダーでContent-Type指定
- CORS: 許可オリジンをホワイトリスト管理
- レート制限: express-rate-limitを適用
## 禁止パターン
- 生SQLクエリの直接実行（Prismaを使用）
- コントローラ内でのビジネスロジック（サービス層に分離）
- try-catchなしの非同期処理
- console.log（Winstonロガーを使用）
Python + FastAPI プロジェクト
|
|
app/ ├── api/ │ ├── deps.py # 依存性注入 │ └── v1/ │ ├── endpoints/ # エンドポイント │ └── router.py # ルーター集約 ├── core/ │ ├── config.py # 設定 │ └── security.py # 認証関連 ├── crud/ # CRUD操作 ├── models/ # SQLAlchemyモデル ├── schemas/ # Pydanticスキーマ └── main.py # アプリケーションエントリ
## コーディング規約
### 型ヒント
- 全ての関数に型ヒントを付与
- `Any`型は原則禁止
- `Optional`より`X | None`を使用
### 非同期処理
- DB操作は全て`async`/`await`
- 同期関数はスレッドプールで実行
### Pydanticモデル
- 入力: `XxxCreate`, `XxxUpdate`
- 出力: `XxxResponse`, `XxxList`
- DB: `XxxInDB`
## エラーハンドリング
\`\`\`python
from fastapi import HTTPException, status
raise HTTPException(
status_code=status.HTTP_404_NOT_FOUND,
detail="User not found"
)
\`\`\`
## 禁止パターン
- 同期DB操作（asyncioを使用）
- グローバル変数での状態管理
- `*`インポート
- printデバッグ（loggingを使用）
Java + Spring Boot プロジェクト
|
|
src/main/java/com/example/app/ ├── config/ # 設定クラス ├── controller/ # RESTコントローラ ├── dto/ # Data Transfer Objects ├── entity/ # JPAエンティティ ├── exception/ # カスタム例外 ├── mapper/ # MapStructマッパー ├── repository/ # Spring Data JPA ├── security/ # 認証・認可 └── service/ # ビジネスロジック
## コーディング規約
### 命名規則
- クラス: PascalCase
- メソッド/変数: camelCase
- 定数: SCREAMING_SNAKE_CASE
- パッケージ: lowercase
### レイヤー責務
- Controller: リクエスト/レスポンス処理のみ
- Service: ビジネスロジック、トランザクション管理
- Repository: データアクセスのみ
### アノテーション配置順序
1. Lombokアノテーション
2. Spring/JPAアノテーション
3. バリデーションアノテーション
## 例外処理
\`\`\`java
// カスタム例外
public class ResourceNotFoundException extends RuntimeException {
public ResourceNotFoundException(String resource, Long id) {
super(resource + " not found with id: " + id);
}
}
// グローバルハンドラで処理
@RestControllerAdvice
public class GlobalExceptionHandler { ... }
\`\`\`
## 禁止パターン
- Controllerでのビジネスロジック
- `@Autowired`フィールドインジェクション（コンストラクタを使用）
- `Optional.get()`の直接呼び出し
- 生のSQLクエリ（JPQLまたはQuerydslを使用）
フルスタックプロジェクトのAGENTS.md
フロントエンドとバックエンドが統合されたプロジェクトでは、両方のコンテキストを含みつつ、境界を明確にします。
Next.js + tRPC フルスタック
|
|
├── app/ # Next.js App Router │ ├── (auth)/ # 認証ページ │ ├── (dashboard)/ # ダッシュボード │ ├── api/trpc/ # tRPCエンドポイント │ └── layout.tsx ├── components/ # Reactコンポーネント ├── lib/ │ ├── trpc/ # tRPCクライアント設定 │ └── db/ # Prismaクライアント ├── server/ │ ├── routers/ # tRPCルーター │ ├── procedures/ # 共通プロシージャ │ └── trpc.ts # tRPCコンテキスト └── prisma/ └── schema.prisma
## tRPC規約
### ルーター構成
\`\`\`typescript
// server/routers/user.ts
export const userRouter = router({
list: publicProcedure.query(...),
create: protectedProcedure.input(createUserSchema).mutation(...),
})
\`\`\`
### クライアント使用
\`\`\`typescript
// Server Component
const users = await api.user.list()
// Client Component
const { data } = api.user.list.useQuery()
\`\`\`
## フロントエンド規約
- Server Componentsをデフォルトとする
- tRPCクエリはServer Componentで直接実行
- ミューテーションはClient Componentで実行
## バックエンド規約
- ビジネスロジックはサービス層に分離
- 入力バリデーションはZodスキーマで定義
- エラーはTRPCErrorでラップ
## 禁止パターン
- tRPC外でのAPI Route作成（認証コールバック除く）
- Prismaクライアントのフロントエンドでのインポート
- tRPCコンテキスト外でのDB操作
モノレポ構成でのAGENTS.md管理
モノレポでは、ルートレベルの共通設定と各パッケージ固有の設定を階層化して管理します。
モノレポのディレクトリ構造例
my-monorepo/
├── AGENTS.md # 全体共通設定
├── packages/
│ ├── web/
│ │ ├── AGENTS.md # フロントエンド固有
│ │ └── ...
│ ├── api/
│ │ ├── AGENTS.md # バックエンド固有
│ │ └── ...
│ └── shared/
│ ├── AGENTS.md # 共有ライブラリ固有
│ └── ...
├── apps/
│ └── admin/
│ ├── AGENTS.override.md # 管理画面の一時的オーバーライド
│ └── ...
└── turbo.json
ルートレベルのAGENTS.md
|
|
変更時の確認事項
packages/sharedを変更した場合、依存する全パッケージのテストを実行- 新しい依存関係は必ずルートではなく各パッケージに追加
- パッケージ間のimportは
workspace:*プロトコルを使用
### パッケージ固有のAGENTS.md（Web）
~~~markdown
# AGENTS.md（packages/web）
## パッケージ概要
Next.js 15で構築されたメインWebアプリケーションです。
ルートのAGENTS.mdの規約を継承しつつ、フロントエンド固有のルールを定義します。
## 固有コマンド
\`\`\`bash
pnpm --filter @myapp/web dev
pnpm --filter @myapp/web build
pnpm --filter @myapp/web test
\`\`\`
## ディレクトリ構造
（前述のNext.js構造を参照）
## 追加規約
- 共有型は`@myapp/shared`からインポート
- APIクライアントは`@myapp/shared/api`を使用
- 環境変数は`.env.local`で管理
このパッケージでは、ルートの共通規約に加えて以下を遵守してください：
- コンポーネントテストはVitestで作成
- E2EテストはPlaywrightで作成
パッケージ固有のAGENTS.md（API）
|
|
src/ ├── plugins/ # Fastifyプラグイン ├── routes/ # ルートハンドラ ├── services/ # ビジネスロジック ├── schemas/ # JSONスキーマ（Zodからコンパイル） └── index.ts # エントリポイント
## 追加規約
- バリデーションは`@myapp/shared/schemas`のZodスキーマを使用
- エラーレスポンスは共通フォーマットに従う
- ログはPinoを使用（Fastify標準）
AGENTS.mdの継続的改善
AGENTS.mdは一度作成して終わりではなく、プロジェクトの成長に合わせて継続的に改善していくことが重要です。
改善サイクル
flowchart LR
A[Codexにタスク依頼] --> B[出力を確認]
B --> C{期待どおり？}
C -->|はい| D[次のタスクへ]
C -->|いいえ| E[問題を特定]
E --> F[AGENTS.mdを更新]
F --> A改善のトリガー
以下の状況が発生したら、AGENTS.mdの更新を検討してください。
| 状況 | 改善アクション |
|---|---|
| Codexが古いパターンを使う | 新しいパターンを明記 |
| テストが失敗する | テストコマンドを修正 |
| コードスタイルが合わない | 規約セクションを追加 |
| 禁止パターンを使う | 禁止パターンを明記 |
| ディレクトリを間違える | 構造説明を詳細化 |
| 依存関係の選択が違う | 技術スタックを明記 |
改善の記録
AGENTS.mdの変更履歴を追跡するため、以下の方法を推奨します。
|
|
チームでの運用
チーム開発では、AGENTS.mdの変更もコードレビューの対象とします。
- AGENTS.mdの変更は専用のPRで管理
- 変更理由を必ずPR説明に記載
- 大きな変更はチームで議論してから適用
- 定期的なレビュー会（月1回程度）で見直し
効果測定
AGENTS.mdの改善効果を測定するため、以下の指標を追跡します。
- PRの修正回数: Codexが作成したPRへの修正コメント数
- テスト成功率: Codexのタスク完了時のテスト成功率
- レビュー時間: PRレビューにかかる時間の推移
- 再依頼率: 同じタスクを再度依頼する割合
まとめ
本記事では、プロジェクト構成別のAGENTS.md設定例と、モノレポでの階層的な管理方法、継続的な改善プロセスを解説しました。
重要なポイント
- フロントエンド: コンポーネント設計、状態管理パターン、スタイリング規約を明記
- バックエンド: API設計規約、エラーハンドリング、セキュリティ要件を含める
- フルスタック: フロントエンドとバックエンドの境界と連携方法を明確化
- モノレポ: ルートレベルの共通設定と各パッケージ固有の設定を階層化
- 継続的改善: 出力を観察し、問題があれば随時AGENTS.mdを更新
次のステップ
AGENTS.mdのテンプレートをベースに、自分のプロジェクトに合わせてカスタマイズしてください。最初から完璧を目指す必要はありません。Codexの出力を観察しながら、徐々に改善していくことで、プロジェクトに最適化されたAGENTS.mdが完成します。