Codexに既存プロジェクトの情報を渡す前に整理すること
既存プロジェクトへの実装を依頼するときは、いきなり「この機能を追加して」と伝えるのではなく、まずプロジェクトの前提を整理します。目的、主な利用者、主要機能、現在の課題を短く言語化しましょう。あわせて、使用言語やフレームワーク、起動方法、テスト方法、外部サービス、変更してはいけない領域も確認します。特に、コードだけでは判断しにくい設計上の制約は明示することが重要です。
- プロジェクトの目的と主要機能
- ディレクトリごとの責務
- 開発・テスト・ビルドの手順
- 認証やデータ連携などの外部依存
- 変更禁止領域や既存仕様
最後に、説明文と実際のファイル構成・設定が一致しているかを確認します。資料とリポジトリに矛盾があると、AIがどちらを基準にすべきか判断しにくくなります。
READMEでプロジェクト全体像と作業手順を伝える
READMEは、プロジェクトを初めて見る人が全体像と基本的な作業手順を把握するための資料です。概要、セットアップ、実行、テスト、主要なディレクトリ構成を最初に確認できるようにします。
# Sample API
## 概要
ユーザー情報を管理するAPIです。
## 起動
npm install
npm run dev
# 開発用サーバーを起動する
## テスト
npm test
# テストを実行する
## 主な構成
- src/routes: APIのルート定義
- src/services: 業務ロジック
- src/repositories: DBアクセスREADMEを長大な仕様書にする必要はありません。詳細な背景や設計判断は設計書に分け、READMEから参照できる形にすると、必要な情報を探しやすくなります。
設計書とディレクトリ構成でコードの責務を示す
ディレクトリ名だけでは、なぜその場所にコードを置くのかまでは伝わりません。設計書では各層の責務と依存方向を説明し、変更時に守る制約も記載します。例えば、ルート層では入力を受け付け、サービス層で業務ロジックを処理し、リポジトリ層でデータベースへアクセスする、といった関係です。
- routes：リクエストの受付とレスポンスの組み立て
- services：業務ルールや処理の組み立て
- repositories：データベースへのアクセス
- 設計書：依存方向、例外処理、変更時の制約
認証、バリデーション、エラーハンドリングなど複数のファイルにまたがる処理は、文章だけでなく簡単な処理順も示すと理解しやすくなります。例えば「リクエスト→ルート→サービス→リポジトリ→データベース」のように、担当範囲を明確にします。
AGENTS.mdでAI向けの開発ルールを短く定義する
AGENTS.mdには、AIが作業するときに毎回確認すべきルールを短く記載します。READMEがプロジェクト全体の説明、設計書が設計意図、AGENTS.mdが作業時のルールという役割分担です。OpenAIの公開情報でも、AGENTS.mdにはコード構成、規約、ビルドやテスト方法など、コードだけでは推測しにくいプロジェクト固有の指示を記載する例が示されています。
# Development rules
- 変更前にREADME.mdとdocs/architecture.mdを確認する。
- 業務ロジックはsrc/servicesに置く。
- APIを変更したら関連するテストを追加または更新する。
- 秘密情報や.envの内容をコミットしない。
# ルールは実際のリポジトリと一致させるAGENTS.mdは百科事典のように長くするより、作業上の重要事項への案内として保つ方が管理しやすくなります。なお、配置場所、適用範囲、複数ファイルの優先順位は、利用するCodexの製品や実行環境の公式仕様を確認してください。公開されているCodexの説明では、AGENTS.mdの適用範囲や、より深いディレクトリにある指示が優先される仕組みが説明されていますが、対象環境に応じた確認は必要です。
小さな依頼で理解度を確認してから実装を進める
資料を整えた後も、最初から大規模な変更を依頼するのは避けます。まずは、プロジェクトの構成説明や変更対象ファイルの候補、実装方針の提案を依頼し、認識が合っているか確認します。
- 現在の構成と各ディレクトリの責務を説明してもらう。
- 変更対象のファイル、利用する既存処理、追加するテストを挙げてもらう。
- 設計書やREADMEと回答が一致しているか確認する。
- 小さな変更を実装し、テストと差分を人間が確認する。
回答が資料と異なる場合は、すぐにAIへ合わせるのではなく、まずリポジトリの実装と正しいルールを確認します。運用を重ねながら、資料の不足や矛盾を修正していくことが、誤実装や手戻りを減らす基本的な進め方です。
開発