Webサービス開発時の
agent.md / AGENTS.md 作成手順 How to Create agent.md / AGENTS.md for Web Projects

AGENTS.md（または agent.md）は、Cursor・Codex などの AI がリポジトリを扱うときに読む「指示書」です。プロジェクトの前提を書いておくことで、AI が誤った技術選定（例: Express を使うプロジェクトで Fastify を提案する）を防ぎ、初回から規約に沿った提案をしやすくします。

AGENTS.md (or agent.md) is an instruction file that AI tools like Cursor and Codex read when working on your repo. By documenting your project’s context, you avoid wrong assumptions (e.g. suggesting Fastify in an Express project) and get convention-aware suggestions from the start.

手順では、なんのアプリケーションか・コンセプト・技術要件を冒頭に書くことを心がけ、そのうえでアーキテクチャ・コマンド・コード規約・レビュー指針をまとめます。

This guide emphasizes writing what the app is, its concept, and technical requirements first, then architecture, commands, code conventions, and review guidelines.

どこに置くか

Where to put it

リポジトリのルート（Git のルート）に AGENTS.md を1つ置きます。ファイル名は AGENTS.md が一般的です。agent.md は同じ役割の別名として使えます。

Place a single AGENTS.md at the repository root (Git root). agent.md is an alternative name for the same role.

何を書くか（心がけること）

What to write (guidelines)

• アプリの定義 — なんのアプリケーションか（例: 会員制SaaS、社内ツール、マーケ用LP、API サービス）を一言で書く。
• App definition — In one line, state what the application is (e.g. member-only SaaS, internal tool, marketing LP, API service).
• コンセプト — 誰向けか・何を解決するか・方針（シンプル優先 / 拡張性重視 など）を短く書く。
• Concept — Briefly describe target users, what problem it solves, and principles (e.g. simplicity first, scalability first).
• 技術要件 — 使用言語・フレームワーク・DB・認証・ホスティングなど。選定理由が分かると AI の提案がぶれにくい。
• Technical requirements — Languages, frameworks, DB, auth, hosting. Stating why they were chosen helps keep AI suggestions consistent.
• そのうえで: アーキテクチャ（ディレクトリ構成・役割）、コマンド（npm run dev など）、コード規約、レビュー指針（PR 時に AI が参照する想定）を書く。
• Then add: Architecture (directory layout, roles), Commands (e.g. npm run dev), Code conventions, and Review guidelines for AI when reviewing PRs.

AGENTS.md のサンプル（抜粋）

AGENTS.md sample (excerpt)

以下は Next.js の Web アプリを想定した例です。プロジェクト名・コンセプト・技術要件を冒頭に置いています。

Below is an example for a Next.js web app, with project name, concept, and technical requirements at the top.

# プロジェクト名: 会員制ダッシュボード

## アプリの定義
- 会員（ログイン済みユーザー）向けの管理ダッシュボード。登録・設定・分析画面を提供する。

## コンセプト
- 対象: 運用担当者。作業時間の削減とミス防止が目的。
- 方針: シンプルな UI 優先。将来の多言語対応を見据え i18n を最初から入れる。

## 技術要件
- Next.js 14 (App Router)。React Server Components を基本とし、"use client" は必要最小限。
- DB: PostgreSQL (Supabase)。認証は Supabase Auth。
- ホスティング: Vercel。pnpm 使用。

## アーキテクチャ
- ページは app/(routes)/ に配置。共通レイアウトは app/layout.tsx。
- API ルートは app/api/ に 1 リソース 1 ディレクトリで route.ts を置く。

## コマンド
- `pnpm dev` — 開発サーバー起動
- `pnpm build` / `pnpm start` — ビルド・本番起動
- `pnpm lint` — ESLint
- `pnpm test` — Vitest

## コード規約
- 新規ページには対応するテストを追加する。
- 環境変数は .env.local にのみ記載し、リポジトリにコミットしない。

## レビュー指針
- 認証なしでアクセスできる API がないか確認する。
- 未使用の依存関係を追加していないか確認する。

モノレポの場合

Monorepo

パッケージごとにルールを変えたい場合は、そのディレクトリに AGENTS.override.md を置くと、その配下ではそちらの内容が優先されます（ツールによっては「上書き」ではなく「追記」として結合される場合もあります）。

To override rules per package, add AGENTS.override.md in that directory; it takes precedence for that subtree (some tools merge it instead of full override).

自分が使う全リポジトリに共通で効かせたいルールは、ユーザーホームに置きます。例: ~/.codex/AGENTS.md（Codex の場合）。パッケージマネージャー（pnpm 優先など）・Git のコミット規約・コードスタイル（シングルクォート、async/await 優先など）を書いておくと便利です。

For rules that apply to all your repos, use a file in your home directory, e.g. ~/.codex/AGENTS.md (for Codex). Document package manager preference (e.g. pnpm), Git commit conventions, and code style (single quotes, prefer async/await) there.

Cursor では、次の2つも使えます。AGENTS.md はツール非依存なので、まずはリポジトリルートの AGENTS.md を用意することをおすすめします。

Cursor also supports the following. AGENTS.md is tool-agnostic, so start with one at the repo root.

• .cursor/rules/*.mdc — ファイルパターン（例: **/*.ts）で「いつでも適用」か「特定ファイルを開いているときだけ」を指定できるルール。YAML フロントマターで description・globs・alwaysApply を設定。
• .cursor/rules/*.mdc — Rules with file patterns (e.g. **/*.ts) to apply always or only when matching files are open. Use YAML frontmatter: description, globs, alwaysApply.
• .cursor/agents/*.md — サブエージェント用のプロンプト（コードレビュー専門など）。name と description を frontmatter で指定。
• .cursor/agents/*.md — Prompts for subagents (e.g. code reviewer). Set name and description in frontmatter.

AGENTS.md を作成・更新するときのチェックリストです。

Checklist when creating or updating AGENTS.md.

• アプリの定義・コンセプト・技術要件が冒頭に書かれているか
• App definition, concept, and technical requirements are at the top
• 主要なコマンド（dev / build / test / lint）が書かれているか
• Main commands (dev, build, test, lint) are documented
• ディレクトリ構成やアーキテクチャの方針が分かるか
• Directory structure and architecture are clear
• PR レビュー時に AI に確認してほしい点（レビュー指針）があるとよい
• Review guidelines for AI when reviewing PRs are helpful

参考: Cursor のルールは .cursor/rules/ のドキュメント、AGENTS.md の一般的な使い方は Codex / Cursor の「AGENTS.md」や「project instructions」の説明を参照してください。

Reference: See Cursor docs for .cursor/rules/, and your tool’s docs for “AGENTS.md” or “project instructions” for general usage.