🦔

AGENTS.mdを試してみた

に公開
GitHub Copilot
Claude 4
tech

1.AGENTS.mdについて

AGENTS.mdとはプロンプトで何度も同じことをAIに伝えずに、いつも伝えておくことをまとめておくファイルです。
今までもAIコードエディタにバラバラにこのような設定ファイル(ex.copilot-instructions.md)はありましたが、AGENTS.mdは全てのコードエディタ共通でのファイルとなることを目指しています。
今回は、このAGETNS.mdを使うとエージェントの動きがどう変わるかか確かめて行こうと思います。

2.今回の題材

2.1.概要

調査に当たって、社内で学習用に使うリポジトリをベースとしました。
シンプルなRESTAPIで映画の管理を行うものです。途中でエージェントから求められた確認などは全て許可しました。

2.2.利用したモデルやエージェント

IDE:vscode
AIモデル:Claude Sonnet 4.5
エージェントツール:github copilot

2.3.AGENTS.md

# AGENTS.md - [Project Name] AI Instructions

このドキュメントは、GitHub Copilot、Claude、ChatGPT などの AI エージェントが本プロジェクトでコード生成や提案を行う際の「唯一の信頼できる情報源（Single Source of Truth）」です。
開発者と AI エージェントは、このガイドラインに従って開発を進めてください。

---

## 1. AI エージェントへの行動指針 (Meta-Instructions)

### 基本的な振る舞い

- **言語**: 思考プロセスや内部推論は**英語**で行い、ユーザーへの回答は**日本語**で行ってください。
- **トーン**: 簡潔、客観的、技術的。過度な丁寧語は不要です。
- **役割**: あなたは[Project Role, e.g. シニアフルスタックエンジニア]として振る舞ってください。

### コード生成の原則（最重要）

1.  **既存実装の調査 (Search First)**:
    - 新しいコードを書く前に、必ず `grep_search` や `file_search` を使用して類似の既存機能を検索・参照してください。
    - プロジェクト内の一貫性（命名規則、ディレクトリ構造、パターン）を最優先します。
    - **自己判断で新しいパターンを作らないでください。**
2.  **コンテキストの理解**:
    - ユーザーの要求だけでなく、周辺ファイル、関連する型定義、インポート元を読み込んでから実装してください。
3.  **安全性**:
    - 秘密情報（API キー、パスワード等）をコードに埋め込まないでください。
    - `any`型の使用は避け、型安全性を維持してください。
4.  **副作用の考慮**:
    - 変更が他の機能やテストに与える影響を常に考慮してください。

### 思考プロセス (Thinking Process)

提案を行う際は、以下のステップを踏んでください：

1.  **目的の理解**: ユーザーは何を達成したいのか？（不明点は質問する）
2.  **情報収集**: 関連するドキュメント、既存コード、型定義を読む。
3.  **設計**: どのファイルを作成・修正する必要があるか特定する。
4.  **実装**: コーディング規約に従ってコードを生成する。
5.  **検証**: テストコードの提案や、動作確認の方法を提示する。

### ツール利用ガイドライン

- **MCP ツール**: GitHub 操作、ファイル操作などは、提供されている MCP ツールを優先的に使用してください。
- **コマンド実行**: 破壊的なコマンド（削除など）を実行する際は、必ずユーザーに確認を取ってください。

---

## 2. プロジェクト概要 (Project Overview)

### 基本情報

- **プロジェクト名**: 映画管理
- **目的**: 映画に関するデータの保存と取得を行えるサービスを構築する。

### 技術スタック

- **Frontend**: TypeScript, nestjs
- **Backend**: TypeScript, express
- **Database**: mysql
- **Infrastructure**: Docker
- **Tools**: Docker, ESLint, Prettier

### アーキテクチャ

- **主要な設計思想**: ドメイン駆動設計(DDD)

---

## 3. ディレクトリ構造 (Directory Structure)

```
.
└── apps/                                # アプリケーションコード
    └── backend/movieAPI             # バックエンド
         └──app/                         # API実装
```

---

## 4. ドメイン知識 (Domain Knowledge)

### 主要なデータモデル

- **[Movie]**: 映画に関する情報を格納するエンティティです。

---

## 5. 開発ルール (Development Rules)

### コーディング規約

- **命名規則**:
  - 変数/関数: `camelCase`
  - クラス/コンポーネント: `PascalCase`
  - 定数: `UPPER_SNAKE_CASE`
  - ファイル名: [e.g., kebab-case]
- **型定義**:
  - 全てに型を定義する。推論可能な場合は省略可だが、`any`は禁止。
  - Zod などのバリデーションライブラリを活用する。
- **コメント**:
  - 複雑なロジックには「なぜそうしたか」の理由を日本語で記述。
  - JSDoc/TSDoc 形式を推奨。

### コミットメッセージ

- **形式**: `type(scope): subject`
- **Type**:
  - `feat`: 新機能
  - `fix`: バグ修正
  - `docs`: ドキュメントのみの変更
  - `style`: コードの意味に影響しない変更（空白、フォーマットなど）
  - `refactor`: バグ修正も機能追加も行わないコード変更
  - `test`: テストの追加・修正
  - `chore`: ビルドプロセスやツールの変更
- **例**: `feat(auth): ログイン機能の実装`

### テスト方針

- **単体テスト**: 新機能追加時、複雑なロジックには必ず作成。
- **結合テスト**: API エンドポイントなどは結合テストでカバー。
- **カバレッジ**: 80%以上を目指す

---

## 6. ワークフローとコマンド (Workflow & Commands)

### セットアップ

```
bash
npm install
# 環境変数の設定など
cp .env.example .env
```

### 開発

```bash
npm run dev      # 開発サーバー起動
npm run build    # ビルド
npm run lint     # リント実行
npm run format   # フォーマッター実行
```

### テスト

```bash
npm run test     # テスト実行
npm run test:cov # カバレッジ計測
```

---

## 7. インフラ・データベース (Infrastructure & DB)

- **環境変数**: `.env.example` を参照。`.env` はコミットしない。
- **マイグレーション**:
  - 作成: `npm run migrate:create`
  - 実行: `npm run migrate:run`

---

## 8. トラブルシューティング (Troubleshooting)

2.4.プロンプト

##実行してもらうタスク
このプロジェクトのbackend/API-Tutorial/appにバックエンドAPIサーバーを作成してください。
APIサーバーはCRUD操作が可能な映画の管理APIとしてください。

##制約条件
- 使用言語はTypescriptとします。
- 作成にあたってはbackend/API-Tutorial/app/package.jsonに記載されたパッケージを利用してください。
- データベースはMySQLを使用してください。
- infraとしてはbackend/API-Tutorial/app/docker-compose.ymlに記載された設定を利用してください。

##API仕様
下記の要件を満たすAPIを作成してください。
- 登録されている映画の一覧を取得できる				
- idを指定して登録されている映画の情報を取得できる				
- 映画を登録できる				
- 映画の情報を更新できる				
- 登録されている映画を削除できる
- 映画は以下の情報を登録できる				
	- タイトル：文字列			
	- 映画の要約：文字列			
				
- タイトル、要約は更新可能

3.結果比較

3.1.出力ファイルの差分

共通で更新されたファイル

app/README.md
app/data-source.ts
app/nodemon.json
app/package.json
app/src/entities/Movie.ts
app/src/index.ts
app/tsconfig.json
app/yarn.lock

AGENTS.mdがない場合のみ作成されたファイル

app/src/routes/movies.ts
app/test-api.sh

AGENTS.mdがある場合のみ作成されたファイル

app/.env.example
app/src/controllers/MovieController.ts
app/src/migrations/1702468800000-CreateMoviesTable.ts
app/src/repositories/MovieRepository.ts
app/src/routes/movieRoutes.ts
app/src/services/MovieService.ts

3.2.主要な差分

出力された中で違いが気になったものは下記のファイルでした。

package.json
AGENTS.mdなしの場合はmysqllからmysql2パッケージに変更していましたが、AGENTS.mdありの場合はmysqlパッケージのままでした。

app/src/index.ts
AGENTS.mdありの場合はシグナルによるサーバー停止処理が記載されていました。

app/src/migrations/1702468800000-CreateMoviesTable.ts
AGENTS.mdありの場合のみマイグレーションファイルが作成されていました。

app/src/repositories/MovieRepository.ts
app/src/services/MovieService.ts
AGENTS.mdありの場合のみサービス層やリポジトリ層が実装されていました。

3.3.出力内容の考察

package.jsonの差分についてはAGETNS.md側では実装時にエラーが発生した結果ライブラリを変更していました。
一方でAGENTS.mdありの場合は実装の違いのためか特にエラーが発生しなかったため、元のライブラリをそのまま利用していました。
AGENTS.md内にマイグレーションコマンドを記載しておいたためか、migrationの実装も併せて行われたようです。
AGENTS.md内に記載にDDDで実装するよう指示を書いておいたためか、サービス層とリポジトリ層への分割が行われたようです。

ただ、上記のようにAGENTS.mdの記載内容が反映される一方でテストの実行方法やカバレッジ目標についての記載はAGETNS.md込みでもテストコードの出力はされませんでした。
また、シグナルによるサーバー停止処理については特に今回AGENTS.mdでも記載していませんでした。これについてはAGENTS.mdの記載内容から単純な勉強用のサーバーよりも実践的な実装を参考にして出力が行われたのではないかと考えられます。

また、テストについてAgent.mdでは記載していますが、実装には出力されていません。明示的にテストコードを作成するように指示していないからかもしれませんが、できれば作って欲しかったとです。
もしかするとAGENTS.mdの記載を調整すれば生成される可能性もありますが、現状では記載したこと全てについて全てにコード生成が行われるとは言い難い状況と言えそうです。

4.AGENTS.md利用上の注意

今回の利用では問題なかったのですが実務上ではAIエージェントの呼び出し方によってAGENTS.mdの内容が正しく読み込まれないことがありました。
例.日本語で回答するよう指示しているにも関わらず英語による回答が返ってくる。
github copilotはAgents.md対応していますが、copilot-instructions.mdも扱っています。
詳しいことはわからないのですが、エージェントのquick fixなどを利用するとこちらだけが読み込まれAGETNS.mdの内容が無視されることがありました。
そのため、現状は各AIエージェントの設定に合わせて適宜AGENTS.mdの内容を記載するファイルを変えたり、それらのファイルからAGENTS.mdを読み込むよう指示をする必要がありそうです。AGENTS.mdの目標を考えると本末転倒な気がしますが、コーディングエージェント周りは変化が激しいので暫くは場当たり的な対応が必要なようです。

Discussion