Codexを使い始めて半年、だんだん複雑なプロジェクトに触れることが増えてきました。
つい最近のトラブルなんですが、作業ルールや文書の間に矛盾が生じ、どの内容を基準にすればよいかAIが混乱して、開発をスムーズに進めなくなることが発生しました。
シンプルな構成でしたら、チャットだけすれば大体問題ないですが、複数のタスクを並行して進めるプロジェクトでは、ディレクトリ構成をいよいよしっかり整理することがかなり重要だと気づきました。
とはいえ、モデルもどんどん賢くなっていて、自動化が進むこの時代なので、「基盤は確かに大事だけど、基盤構成に時間を使いすぎないでまず開発を進めてみよう」という観点は変わりません。
なのでで今回は、まずディレクトリ構成はどういう感じか、シンプルで初心者が理解しやすい例を整理してみました。
架空のアプリを例としています。
例・図書管理アプリ
手元の本を登録し、分類ごとに探せるアプリです。保存するデータは「図書」と「分類」の2種類です。
| 画面 | 機能 |
|---|---|
| 図書登録 | 図書名を入力し、登録済みの分類を1つ選んで保存 |
| 図書一覧 | 選択した分類に属する図書を表示 |
1. ディレクトリ構成:文書の配置
Codexが必要な文書をすべて自動で作成・配置するとは限りません。プロジェクトの文書構成を把握し、不足を確認するための参考として、必要に応じて調整できます。
project/
├─ AGENTS.md # 作業ルールと参照先
├─ src/
├─ tests/
└─ docs/
├─ requirements.md # 現在の仕様
├─ decisions.md # 決めた理由
└─ progress.md # 検証結果と次の作業
| 対象 | 役割・読み込み方 |
|---|---|
AGENTS.md |
Codexの指示ファイル。一回の実行開始毎に、作業ディレクトリなどに応じて既存の AGENTS.md が探索され、指示として読み込まれる。 |
docs/ 内の文書 |
本稿で提案する仕様・判断理由・進捗の資料。Codexが、AGENTS.md や会話内の指示に応じて、必要な文書を参照する。 |
2. AGENTS.md:作業ルールと参照先
AGENTS.mdは、Codex向けの指示ファイルです。この例では、作業・報告のルールと、各文書を参照する条件をまとめています。
記載項目:開始時の確認、参照条件、変更時の対応、終了時の記録。
# Project workflow
## Start
- 現在のブランチと未コミット変更を確認する。
- 仕様確認: docs/requirements.md の関連箇所を読む。
- 作業再開: docs/progress.md の該当記録を読む。
- 判断理由の確認: docs/decisions.md の関連箇所を読む。
## Work
- 既存の変更を無断で戻さない。
- 仕様の不明点・矛盾を実装前に確認する。
- 仕様変更時は、関連文書とテストを更新する。
## Finish
- 変更内容、実行した検証、未確認事項を分けて報告する。
- docs/progress.md に次の作業を記録する。
3. requirements.md:現在の仕様と受け入れ条件
requirements.mdは、現在の仕様、実装範囲、動作の確認条件をまとめる文書です。
記載項目:目的、対象、対象外、現在の仕様、受け入れ条件。
# Requirements
更新日: YYYY-MM-DD
## 目的
- 分類別の図書検索。
## 対象
- 図書の登録と分類別一覧。
## 対象外
- 貸出管理。
## 現在の仕様
- 図書登録の入力項目は図書名と分類。
- 1冊につき1分類が必須。
- 選択可能な分類は登録済みのもの。
- 図書一覧には、選択した分類に属する図書を表示。
## 受け入れ条件
- [ ] 図書名が空の場合、登録が拒否される。
- [ ] 登録済みの分類を指定すると登録できる。
- [ ] 存在しない分類を指定した場合、登録が拒否される。
- [ ] 分類を選ぶと、その分類の図書だけが一覧に表示される。
4. decisions.md:判断理由と旧案
decisions.mdは、採用した設計の理由と旧案の扱いを残す文書です。
記載項目:日付、決定、理由、旧案、影響範囲。
# Decisions
## YYYY-MM-DD: 図書の分類:1冊につき1分類
- 決定: 1冊につき1分類が必須。
- 理由: 最初の版の対象は単純な分類検索。
- 旧案: 複数分類への所属は次版以降の検討事項。
- 影響範囲: 登録画面、入力検証、図書テーブル。
- 関連仕様: requirements.md / 現在の仕様
5. progress.md:作業状態と再開位置
progress.mdは、作業状態と再開位置の記録です。次の会話では、この記録と実ファイルの状態を照合できます。
記載項目:ブランチ、変更、検証と結果、未確認、次の作業。
# Progress
更新日: YYYY-MM-DD
## 作業対象
- ブランチ:
- コミット / 未コミット変更:
- 対象ファイル:
## 実装済み
-
## 検証済み
- 実行したコマンド・操作:
- 結果:
## 未確認・阻害要因
-
## 次の作業
-
Codexへの再開依頼例:
対象: このプロジェクト
目的: 前回の続きから再開
確認: 適用されるAGENTS.md、progress.mdの該当記録、
現在のブランチと変更内容
実行: 記録と実ファイルを照合し、次の作業へ進んでください。
出力: 不一致があれば、該当箇所と判断が必要な点を報告してください。
6. 更新フロー:開始・変更・終了・再開
文書の更新・照合タイミングは、次のとおりです。
開始 → ブランチ・変更内容を確認
↓
実装 ┬ 仕様変更 → requirements.md
├ 判断変更 → decisions.md
└ 動作変更 → 対応テスト
↓
検証 → 実行内容・結果・未確認をprogress.mdへ
↓
終了 → 次の作業を記録
↓
再開 → 関連文書と実ファイルを照合
Codexへの終了時の依頼例:
対象: 今回の変更
実行: progress.mdに変更、実行した検証、未確認事項、
次の作業を記録してください。
区分: 実装済み / 検証済み / 未着手
出力: 更新した文書と残っている確認事項を報告してください。
7. DB・API文書:データ構造と通信仕様
本稿の構成では、DBの設計をdatabase.mdに、APIを使う場合の通信仕様をapi.mdにまとめます。
docs/
├─ requirements.md
├─ decisions.md
├─ progress.md
├─ database.md # データ構造
└─ api.md # 通信仕様
database.md:関係図とフィールド
記載項目:使用DB、関係図、型・制約・意味、変更方法、検証方法。
categories(分類)1 ───── 0..N books(図書)
id [PK] id [PK]
name title
category_id [FK → categories.id]
| 記号 | 意味 |
|---|---|
1 → 0..N |
1つの分類に0冊以上が所属し、1冊は1分類に所属 |
| PK(主キー) | 各レコードを識別する値 |
| FK(外部キー) | 別のテーブルのレコードを参照する値 |
型・長さは架空の設計例です。利用時は採用するDBに合わせて調整してください。
| テーブル | フィールド | 型 | 必須 | 制約 | 意味 |
|---|---|---|---|---|---|
| categories | id | INTEGER | 必須 | 主キー(PK) | 分類ID |
| categories | name | VARCHAR(100) | 必須 | UNIQUE | 分類名 |
| books | id | INTEGER | 必須 | 主キー(PK) | 図書ID |
| books | title | VARCHAR(200) | 必須 | — | 図書名 |
| books | category_id | INTEGER | 必須 | 外部キー(FK)→ categories.id | 所属分類 |
api.md:入力と出力
記載項目:パス、メソッド、認証方式、入力、出力、エラー、確認方法。
# API
- エンドポイント / メソッド:
- 認証方式:
- 入力:
- 出力:
- エラー:
- 確認方法:
認証に関する記載項目は、方式と環境変数名です。パスワードやAPIキーの値は文書に含めないでください。
参考資料
- OpenAI公式:Custom instructions with AGENTS.md
- OpenAI Cookbook:Iterating development workflows with Codex
🔥 成長と挑戦を楽しむ仲間を募集中!
スピードリンクジャパンでは、一緒に技術を楽しめる仲間を探しています!
会社の雰囲気や働く環境などをまとめていますので、ご興味のある方はぜひサイトに遊びに来てください!

