📝

AGENTS.mdはAIに書いてもらおう！

に公開
AI
Copilot
Cursor
agents
Codex
tech

AGENTS.mdって？

AGENTS.md活用してますか？　開発でAIを使うのはだんだん浸透してきましたが、CodexやClaude Code、GitHub Copilotなど、使われるエージェントはさまざまです。それぞれのエージェントに統一したルールを与えたいときに便利なのがAGENTS.mdで、プロジェクトがどういうものか、どういうルールがあるかをAIに伝えるためのドキュメントです。

「このプロジェクトは何をするのか」「どんなコマンドがあるのか」「どんな構造になっているのか」などを整理しておくと、AIとスムーズに連携できるようになります。

正直めんどくさい！

便利ではあるものの、プロジェクトの情報を書くのは正直めんどくさいですよね。

  • npm script
  • コードの規約
  • テストの手順
  • ディレクトリ構成

などなど、いちいち調べて、それを書いて…となるとなかなか時間がかかります。が、このAGENTS.mdもAIに任せるといい感じに書いてもらえます！

AIに書いてもらうメリット

1. プロジェクト全体を見て構成してくれる

自分で1から考えるとどうしても抜け漏れが出たりします。
でもAIは、プロジェクトを読み取って「このリポジトリはこういう構成だな」と自動で整理してくれます。

コードだけでなくpackage.jsonや設定ファイルも参照して「使用しているAPI」「関係するnpm script」など、自分が忘れていた要素まで含めてくれます。

2. AIが知りたいことはAIが一番知っている

AGENTS.mdはAIのための文章です。AIが理解できるよう書く必要があります。
だったら、AIが読みやすいようにAI自身が書くのが一番効率的です。

実際に作ってもらうとこんな感じ

AGENTS.mdはリポジトリごとに作ります。作りたいリポジトリに入って、お好みのエージェントに依頼します。

試しに、複数のThree.jsプロジェクトをまとめたリポジトリのAGENTS.mdを書いてもらいました。

このリポジトリのAGENTS.mdを作成して
- 「回答は必ず日本語で」の指示は必須
- そのほかはリポジトリ全体を見てあなたが必要と判断したものを追加

すると、こんな感じで書いてくれます。独立したプロジェクトであることも読み取ってくれます。

AGENTS.md
# AGENTS
## 必須指示
- 回答は必ず日本語で。
## リポジトリ概要
- `01_`〜`15_`の各ディレクトリは独立した Three.js × Vite の実験プロジェクト。作業や依存追加は対象ディレクトリ内に限定する。
- ルートディレクトリには共通のビルド設定や依存関係がないため、コマンド実行時は必ず該当プロジェクトへ移動してから実行する。
## 環境・ツール
- 各プロジェクトは Vite を利用する前提。セットアップは `npm install`、開発は `npm run dev`、ビルドは `npm run build` を想定。
- `package-lock.json` がコミットされているディレクトリでは npm を利用し、同ファイルのみを更新する。`pnpm-lock.yaml` が併存する場合も基本的に触れない。
- Vite 6 系を利用しているため Node.js 18 以上（推奨は 20 系）を想定。バージョン不足によるエラーが出たら Node.js を更新する。
## 実装上の注意
- 複数プロジェクトで `vite-plugin-glsl` により `src/shaders/**.glsl` を直接インポートしている。拡張子や配置を変える場合はプラグイン設定を確認し、ビルドが壊れないようにする。
- `vite.config.js` で `root: "src/"` と `base: "./"` を設定しているケースはビルド後の相対パス維持が目的。理由がない限り変更しない。
- README や `docs/` 配下の画像はポートフォリオ用途。不要な差し替えや削除は避け、更新時は利用箇所を確認する。

Tips

個人プロジェクトや実務で書いてもらった時のTipsです。

1. 「回答は日本語で」は必須

エージェントは隙あらば英語で回答してくるので、日本語で回答する指示は必須です。

2. 複数のエージェント向けのルールが混在している時

プロジェクトでGitHub CopilotやCursor、Claude Codeなど複数のAIを使っている場合は

  • .github/copilot-instructions.md
  • .cursor/rules/....md
  • CLAUDE.md

等の複数のルールが混在していることがあります。

その場合は、AGENTS.mdに各ルールの意図と要約を書くのがおすすめです。

AGENTS.mdには以下のように記載します。

AGENTS.md
# 前提

- すべてのAIエージェントは本ファイルと`.cursor/rules/`配下のルールを必ず参照してください。
  - `.cursor/rules/project-rules.mdc`（アーキテクチャ・設計方針）
  - `.cursor/rules/coding-rules.mdc`（コーディング規則）
- `.github/copilot-instructions.md`：テストのノウハウをまとめています。詳細な判断が必要な場合に参照してください。

3. 必要になったルールはAIに都度追加してもらう

AIエージェントと協働していると、毎回同じ指示をしているな、と思うことがあります。

その場合はAIに「AGENTS.mdに追加して」と指示すれば追加してくれます。

▼AIにこんな感じで依頼

- タスクが終わったらformatとlintを実施してください
- エラーが出たら修正してください
- 修正が3回以上うまくいかない場合はフィードバックして私に意見を求めてください
- 以上の3つはAGENTS.mdにも追加してください

▼追加してくれる

AGENTS.md
## 必須指示
- 回答は必ず日本語で。
- タスク完了時は対象プロジェクトで `npm run format` と `npm run lint` を実行し、エラーが出た場合は修正してから再度コマンドを実行する。
- エラー修正が 3 回以上うまくいかない場合は速やかにユーザーへ状況を報告して指示を仰ぐ。
- 上記の手順は常に遵守する。

4. AGENTS.mdが肥大してきたら分割

都度ルールを追加していくと、AGENTS.mdが大きくなってきます。その場合はルールを分割しましょう。

細かなコーディングルールなどは.cursor/rules/coding-rules.mdcなどに分けた方が良いかもしれません。

この辺りの判断もAIに相談するとうまく分割案を考えてくれます。

AIに丸投げしてとりあえず作ってみよう！

最初から完璧なAGENTS.mdを作れることはありません。プロジェクトを進めている上で追加/修正も必要です。

だからこそ、AIに丸投げしてとりあえず作ってみるとどんどんプロジェクトが楽になっていきます。

ぜひぜひ活用してください！

Discussion