CODEX開発環境の自動化と権限設計の実践
AGENTS.mdによるコンテキスト注入
リポジトリの憲法
AIコーディングエージェントをプロジェクトに導入する際、最初の課題は「コンテキストの欠如」です。AIはリポジトリの目的、独自のコーディング規約、あるいはチームの暗黙のルールを理解していません。その結果、的外れなコードを生成したり、プロジェクトのスタイルに合わない提案をしたりすることがあります。
そこで登場するのが AGENTS.md です。これは、AIエージェントに対してプロジェクト固有の指示や文脈を与えるために設計された、Markdownベースのファイルです。リポジトリのルートに配置することで、AIエージェントはこのファイルを「憲法」または「取扱説明書」として参照し、より的確なサポートを提供できるようになります。
AGENTS.mdは、人間とAIが共通の理解を持つための「契約書」と考えることができます。
このファイルは、AIエージェントがコードを生成・修正する際のの一部として機能します。適切に記述されたAGENTS.mdは、AIの出力を劇的に改善し、開発ワークフローをスムーズにします。
AGENTS.mdの基本構造
AGENTS.mdには決まった形式はありませんが、効果的な構成要素は存在します。重要なのは、AIが解析しやすいように、明確なセクションに分けて記述することです。以下は、多くのプロジェクトで役立つ基本的なテンプレートです。
# AGENTS.md: AI Agent Instructions for [Project Name]
## 1. Project Overview & Goal
- **Objective**: このプロジェクトの主な目的は何か。
- **Key Features**: 主要な機能やコンポーネントは何か。
## 2. Tech Stack & Dependencies
- **Languages**: TypeScript, Python
- **Frameworks**: Next.js, FastAPI
- **Database**: PostgreSQL
- **Key Libraries**: Prisma, Zod, React Query
## 3. Coding Conventions & Style Guide
- **Naming Convention**: `camelCase` for variables, `PascalCase` for components.
- **Formatting**: Prettierに準拠。`npm run format`で整形可能。
- **Comments**: 複雑なロジックにはJSDoc形式でコメントを追加する。
## 4. Development Workflow
- **Branching Model**: Git Flowに近い。featureブランチは`develop`から作成する。
- **Testing**: `*.test.ts`という命名規則でテストファイルを作成。Jestを使用。
- **Commit Messages**: Conventional Commitsの規約に従うこと。
## 5. Prohibitions (禁止事項)
- **DO NOT**: `any`型を絶対に使用しないこと。
- **DO NOT**: 外部APIのAPIキーをコードにハードコーディングしないこと。環境変数を使用する。
この構造はあくまで一例です。プロジェクトの特性に合わせて、「ディレクトリ構造のルール」や「エラーハンドリングの方針」といったセクションを追加すると、さらにAIの精度が向上します。
指示を最適化する
AIへの指示は、具体的かつ明確でなければなりません。曖昧な表現は誤解を招き、期待しない結果につながります。特に「禁止事項」セクションは重要です。AIが絶対にやってはいけないことをリストアップすることで、セキュリティリスクや品質低下を防ぎます。
例えば、「外部ライブラリを自由に追加しないこと」と書く代わりに、「新しい外部ライブラリを追加する場合は、必ずpackage.jsonを更新し、npm installを実行した上で、その理由をプルリクエストに明記すること」と具体的に指示します。
良い指示は「何をすべきか」だけでなく、「なぜそうすべきか」の文脈も提供します。
また、プロジェクト固有の用語やドメイン知識を説明することも有効です。例えば、社内でのみ使われる略語や、特定のビジネスロジックに関する背景知識などを記載します。これにより、AIは単なるコード生成マシンではなく、プロジェクトの文脈を理解した「アシスタント」として機能するようになります。
例えば、コミットメッセージの規約を定めるセクションは非常に効果的です。多くのプロジェクトで採用されているのような規約を明記することで、AIが生成するコミットメッセージの質を人間が書くレベルに近づけることができます。
既存のGitワークフローにAGENTS.mdを組み込むことは、AIとの協業を成功させるための重要な第一歩です。この「憲法」を整備し、継続的に更新していくことで、AIエージェントはプロジェクトにとって強力な味方となるでしょう。
内容を理解できたか、クイズで確認してみましょう。
「AGENTS.md」ファイルの主な目的は何ですか？
「AGENTS.md」ファイルは、プロジェクトのどこに配置するのが最も効果的とされていますか？
これで、AIエージェントにプロジェクトの文脈を正しく伝える準備ができました。