はじめに
とっても今更ですが、、、最近、Codexを使ってDjango製のWebアプリケーションを開発しています！
Codexを単なるコード生成AIとしてではなく、
- 既存コードを確認してもらう
- HTML / SCSSを修正してもらう
- Djangoの機能を追加してもらう
- ファイルを横断して実装してもらう
といった、エージェント的な使い方をしています。
Codexがプロジェクトの情報を理解しやすいように、AGENTS.md や docs/、Skillsの構成を整理してみました。
- このプロジェクトは何を作っているのか
- どんな技術を使っているのか
- コードを変更するときのルール
- デザインで使用するカラー
- コンテンツの最大幅
- レスポンシブのルール
- Codexからの回答は簡潔にしてほしい
といった内容です。
今回は、実際に開発しているDjangoプロジェクトを例に紹介します。
1. 今回のファイル構成
現在は、以下のような構成にしています。
yakugaku-quiz/
├── AGENTS.md
│
├── docs/
│ ├── project-spec.md
│ │
│ └── agent/
│ ├── development.md
│ ├── design.md
│ └── chat-output.md
│
├── .agents/
│ └── skills/
│
├── accounts/
├── quiz/
├── templates/
├── static/
├── manage.py
└── README.md
それぞれの役割は以下です。
| ファイル / ディレクトリ | 役割 |
|---|---|
AGENTS.md |
Codexが最初に確認するプロジェクトの案内 |
docs/project-spec.md |
プロジェクト・機能の仕様書 |
docs/agent/development.md |
開発時の基本ルール |
docs/agent/design.md |
HTML / SCSS・UIのデザインルール |
docs/agent/chat-output.md |
Codexのチャット出力ルール |
.agents/skills/ |
特定の作業で使用するSkill |
ポイントは、すべての情報を AGENTS.md に書かないことです。
2. AGENTS.mdとは？
Codexでは、リポジトリ内に AGENTS.md を置くことで、プロジェクト固有の指示を与えることができます。
例えば、
- プロジェクト構成
- コーディングルール
- 使用するコマンド
- 開発上の注意事項
- 参照してほしいドキュメント
などを伝えることができます。
最初は、
プロジェクトに関する情報は全部AGENTS.mdに書けばいいのでは？
と思っていました。
実際、以前の AGENTS.md には、
- プロジェクト概要
- Djangoの構成
- PostgreSQLのモデル
- AWS構成
- URL一覧
- 機能仕様
- 開発ルール
などをすべて記載していました。
ただ、これを続けていくと AGENTS.md がどんどん巨大になります。
そこで現在は、AGENTS.md を詳細な仕様書としてではなく、Codexが必要な情報へアクセスするための案内板として使用しています。
3. AGENTS.mdは「目次」として使う
現在の AGENTS.md は、以下のようなイメージです。
# yakugaku-quiz
薬剤師国家試験対策向けのDjango製クイズWebアプリケーションです。
## Project Documentation
プロジェクト仕様については以下を参照してください。
- `docs/project-spec.md`
## Development Rules
コードの新規作成・修正時は以下を参照してください。
- `docs/agent/development.md`
## Design Rules
HTML / SCSS / UIを変更する場合は以下を参照してください。
- `docs/agent/design.md`
## Chat Output
ユーザーへの作業報告は以下に従ってください。
- `docs/agent/chat-output.md`
## Tech Stack
- Python
- Django
- PostgreSQL
- Docker / Docker Compose
- HTML
- JavaScript
- SCSS
## Important
- 既存コード・既存設計を確認してから変更する。
- 大規模な仕様変更やDB設計変更は独断で行わない。
- 機能仕様を変更する場合は `docs/project-spec.md` との整合性を確認する。
AGENTS.md 自体には最低限の情報だけを書き、詳細については別ファイルを参照する形です。
イメージとしては、
AGENTS.md
↓
必要なドキュメントを案内
↓
docs/
という構成です。
OpenAIでも、巨大な AGENTS.md にすべてを書き込むのではなく、短い AGENTS.md をマップとして利用し、詳しい情報を構造化されたドキュメントへ分離する考え方が紹介されています。
4. プロジェクト仕様は project-spec.md に分離する
アプリケーションそのものの仕様は、
docs/project-spec.md
にまとめています。
例えば、このプロジェクトでは以下のような内容を記載しています。
プロジェクト概要
技術スタック
AWS構成
ディレクトリ構成
データモデル
機能一覧
画面仕様
URLルーティング
今後の機能追加予定
ここで意識しているのが、
「アプリの仕様」と「AIへの指示」を分けること
です。
例えば、
Questionモデルにはcategoryが存在する
というのはプロジェクト仕様です。
一方、
DBスキーマを独断で変更しない
というのはCodexへの開発ルールです。
この2つを別ファイルにすることで、それぞれの役割がかなり分かりやすくなりました。
5. 開発ルールは development.md
Codexにコードを書いてもらう際の基本ルールは、
docs/agent/development.md
に記載しています。
例えば以下のような内容です。
# Development Rules
- 既存のコード・設計・ディレクトリ構成を尊重する。
- 必要以上に大きな変更を行わない。
- 依頼と関係のないリファクタリングを行わない。
- Djangoの標準機能・一般的なベストプラクティスを優先する。
- DBスキーマやアーキテクチャの大きな変更は事前に提案する。
- パスワードやAPIキーなどの機密情報をコードへ直接記載しない。
ここには、
「このプロジェクトで、どう開発してほしいか」
を記載します。
プロジェクト仕様とは切り離しておくことで、ルールだけを確認したい場合にも分かりやすくなります。
6. デザインルールは design.md
今回、特に細かく設定しているのがデザインルールです。
docs/agent/design.md
に、Figmaで作成したデザインをもとに、
- カラー
- フォント
- フォントサイズ
- 行間
- セクション余白
- コンテンツ最大幅
- ブレークポイント
- スマホ時のレイアウト
などを定義しています。
例えばカラーはSCSS変数として定義しています。
// Colors
$color-main: #39A378;
$color-bg: #F1F3F9;
$color-text: #19273B;
$color-red: #DC716C;
$color-yellow: #F4AA6D;
$color-line: #CDD9EA;
$color-bg-sub: #E7F4F0;
レイアウトについても、
$container-width: 1200px;
$container-width-narrow: 1000px;
$side-padding: 24px;
$side-padding-mobile: 16px;
のように具体的な値を決めています。
レスポンシブについても、
$breakpoint-tablet: 1023px;
$breakpoint-mobile: 767px;
としています。
単に、
いい感じにレスポンシブ対応してください
と依頼するのではなく、Codexが判断するための基準をあらかじめ用意しておくイメージです。
7. チャットの出力ルールも分離する
もう一つ作っているのが、
docs/agent/chat-output.md
です。
Codexをエージェントとして使っていると、チャット上で長い説明をしてもらうより、実際にファイルを確認・編集してもらうことの方が重要になります。
そのため、例えば以下のようなルールを設定しています。
# Chat Output Rules
- チャット上でのアウトプットは必要最低限にする。
- 説明よりも実際のファイル編集・実装を優先する。
- 作業前の長い説明は不要。
- 作業完了後は変更内容を簡潔に報告する。
- 詳細な説明はユーザーから求められた場合に行う。
これも development.md にまとめることはできます。
ただ、
development.md
→ コードをどう変更するか
chat-output.md
→ Codexがどう報告するか
と役割が異なるため、現在は分離しています。
8. Skillsは特定の作業用に使う
さらに、必要になった場合はSkillsを利用できます。
例えば、
.agents/
└── skills/
└── create-django-feature/
└── SKILL.md
のような構成です。
Skillには、
Djangoで新しい機能を追加するときは、どのような手順で進めるか
といった、特定タスクの手順を記載できます。
例えば、
---
name: create-django-feature
description: Djangoで新しい画面や機能を追加するときに使用する。
---
# Django Feature Creation
1. 既存のアプリ構成を確認する
2. 関連するModelを確認する
3. URLを確認・追加する
4. Viewを実装する
5. Templateを実装する
6. 既存デザインとの整合性を確認する
といった形です。
自分の中では、
AGENTS.md / docs
→ プロジェクトで継続的に守ってほしいこと
Skills
→ 特定の作業をするときの手順
という使い分けをしています。
最初から大量のSkillを作る必要はなく、
この作業、毎回同じ指示をしているな
と思ったタイミングでSkill化していくくらいで良いと考えています。
9. なぜファイルを分割するのか
最終的に、現在は以下のように役割を分けています。
AGENTS.md
↓
どの情報を見るべきか
project-spec.md
↓
何を作っているか
development.md
↓
どう開発するか
design.md
↓
どう見せるか
chat-output.md
↓
どう報告するか
skills/
↓
特定の作業をどう進めるか
ファイルを分ける一番大きな理由は、単純に管理しやすくなることです。
また、プロジェクトが大きくなった場合でも、
docs/
├── project/
│ ├── overview.md
│ ├── architecture.md
│ ├── database.md
│ └── features.md
│
└── agent/
├── development.md
├── design.md
└── chat-output.md
と段階的に分割できます。
最初から複雑にするのではなく、情報量が増えたタイミングで分けていく方が管理しやすそうです。
10. Codexへの依頼がかなりシンプルになる
この構成にしておくと、実際のCodexへの依頼はかなり短くできます。
例えば、
マイページの学習進捗セクションをFigmaに合わせて実装してください。
と依頼した場合でも、Codexがプロジェクト内のルールやドキュメントを参照できる状態にしておけば、
AGENTS.md
↓
project-spec.md
↓
development.md
↓
design.md
↓
既存コード
という形で必要な情報を確認しながら作業できます。
こちらから毎回、
Djangoで作っています。
SCSSを使っています。
メインカラーは#39A378です。
コンテンツ幅は1200pxです。
スマホでは左右16pxです。
既存コードを勝手に大きく変更しないでください。
と説明する必要がなくなります。
エージェントを使った開発では、この「毎回説明しなくていい状態」を作ることがかなり重要だと感じています。
11. AntigravityからCodexへ移行して変えたところ
もともとはGoogle Antigravityを使っていたため、以下のような構成にしていました。
.agents/
├── rules/
│ ├── development.md
│ ├── design.md
│ └── chat-output.md
│
└── skills/
Codexへ移行するタイミングで、現在は以下のように整理しています。
AGENTS.md
docs/
├── project-spec.md
└── agent/
├── development.md
├── design.md
└── chat-output.md
.agents/
└── skills/
既存のMarkdownファイルの内容を大きく変更する必要はなく、
.agents/rules/
に置いていたルールを、
docs/agent/
へ移動し、ルートの AGENTS.md から参照する形に変更しました。
ツールを変更したからといって、これまで作ったルールをすべて作り直す必要はありませんでした。
12. まとめ
現在は、Codex向けのファイルを以下のように整理しています。
yakugaku-quiz/
├── AGENTS.md
│
├── docs/
│ ├── project-spec.md
│ └── agent/
│ ├── development.md
│ ├── design.md
│ └── chat-output.md
│
└── .agents/
└── skills/
Codexを使い始める段階から複雑なエージェント構成を作る必要はないと思います。
まずは、
AGENTS.md
docs/project-spec.md
docs/agent/
くらいから始めて、何度も繰り返す作業が出てきたらSkillsを追加する。
今のところ、このくらいの構成がシンプルで管理もしやすく、Codexにもプロジェクトの意図を伝えやすいと感じてます！