Codex CLI の作業開始を整えるために
AGENTS-base.md を作った

by

Codex CLI でプロジェクト作業を始めるとき、毎回まず決めることがあります1。
プロジェクトの目標、作業の進め方、使うフレームワーク、テスト方法、ドキュメントの置き場所などです。
これらを最初に確認しないまま作業を始めると、あとから「この前提を決めていなかった」「実行環境が違った」「ログの共有方法がなかった」と気づいて手戻りが起きます。

そこで、普段の AGENTS.md とは別に、プロジェクト開始時だけ読み込ませるベース指示書として AGENTS-base.md を作ることにしました2。

AGENTS-base.md（12KB）ダウンロード

関連記事

1. AGENTS.md に全部詰め込まない

AGENTS.md は、そのプロジェクトで毎回守ってほしいルールを書く場所です。
プロジェクト開始時に確認したいことをすべてここに入れると、文書が大きくなりすぎます。
AI エージェントに渡すコンテキストが増えるうえ、プロジェクト固有ではない「開始時だけ必要な確認手順」まで残り続けます3。

そこで役割を分けました。

  • AGENTS-base.md: プロジェクト開始時に読むベース指示書
  • AGENTS.md: そのプロジェクトで継続して守る固有ルール

最初に AGENTS-base.md を読ませて必要な確認をしたうえで、そのプロジェクト用の AGENTS.md を作ります。
こうすると、AGENTS.md には必要なものだけを残せます。

2. いきなり作業しない

今回いちばん大事にしたのは、いきなり実装に入らないことです。

AI エージェントは指示を出すとすぐ作業を始めてくれます。
便利ですが、前提があいまいなまま進むと後から修正が増えます。
特に新しいプロジェクトでは、何を作るのか、どこまでを今回の対象にするのか、どこで動かすのか、どの技術スタックを使うのか、どうテストするのか、ログやドキュメントをどこに残すのかを最初に確認しておく必要があります。
これらを毎回思い出して確認するのは面倒なので、開始手順をテンプレート化しました。

3. スタートアップ一問一答

AGENTS-base.md では、プロジェクト開始時に 7 問以内で確認する方針にしました。
最初の質問だけは自由記述です。

このプロジェクトの目的と、完成とみなす状態は何ですか。

まずユーザーが目的を自分の言葉で説明します。
2 問目以降は、AI エージェントが選択肢やおすすめ案を出してユーザーが選べるようにしています。

技術スタックはユーザーに最初から決めてもらうのではなく、目的、対象環境、配布方法、運用制約から候補を出します。
Web アプリなのか、CLI なのか、macOS アプリなのか、WordPress プラグインなのかによって向いている技術は変わります。
初心者にとっては「何を選べばよいか」自体が難しいので、AI エージェント側が候補を整理して提示する流れにしました。

4. AGENTS-base.md に入れた内容

今回入れた主な項目です4。

  • KISS / YAGNI / DRY を守り、シンプルに作る
  • 原因未特定のままフォールバックや互換分岐を増やさない
  • インストールや OS 設定などのシステム変更はユーザーが実行する
  • 技術スタックは目的と環境から候補を提案する
  • 開発環境と実行環境が同じか確認する
  • AGENTS.md、README.md、docs/dev-log.md を初期作成の候補にする
  • 配布物やエクスポート成果物は dist/ に整理する
  • デバッグログはコピー、クリア、保存できるようにする
  • UI は必要に応じて ASCII アートで簡易確認する5

なかでも、開発環境と実行環境の確認は外せません。
自分の PC で開発していても、実際に動かす場所はブラウザ、スマートフォン、WordPress、サーバー、別 OS かもしれません。
最初に確認しておくと、「ローカルでは動くけれど本番では違う」という手戻りを減らせます6。

5. 共通ディレクトリ構成

作業フォルダの構成も、最低限の候補を決めました。

project-root/
├── AGENTS.md
├── README.md
├── docs/
│   ├── dev-log.md
│   └── spec.md
├── dist/
├── src/
├── tests/
└── scripts/

最初から全部作るわけではありません。
プロジェクト開始時に作るのは AGENTS.md、README.md、docs/dev-log.md の3つが候補です。
docs/spec.md、src/、tests/、scripts/、dist/ は必要になってから作ります。ここでも YAGNI を守ります7。

6. 使い方

使うときは次のように依頼します。

AGENTS-base.md を読んでプロジェクトを開始しようCode language: CSS (css)

すると AI エージェントは AGENTS-base.md を土台にして最初の一問一答を始めます。
目標を確認し、技術スタック候補を整理し、必要な初期ファイルを作り、その後に計画、テスト方針、実装へ進みます。
この流れにすることで、毎回だいたい同じワークスタイルで作業を始められます。

  1. Codex CLI は OpenAI が開発したターミナル上で動作するオープンソースのコーディングエージェント。Mac・Linux・Windows（PowerShell / WSL2）に対応し、ローカルリポジトリを読み込んでコードの変更やコマンド実行を行う。ChatGPT アカウントか API キーで認証して使い、ChatGPT の全プランに含まれる。 – GitHub – openai/codex: Lightweight coding agent that runs in your terminal
  2. Codex は ~/.codex/AGENTS.md（グローバル）とプロジェクトルートから現在ディレクトリまでの各 AGENTS.md を作業前にすべて読み込む。ルートから順に結合され、より深いディレクトリの指示が後から追記される形で優先される。合計サイズはデフォルトで 32 KiB が上限。 – Custom instructions with AGENTS.md – Codex | OpenAI Developers
  3. コンテキストウィンドウとは、LLM が一度のリクエストで処理できるトークン数の上限のこと。プロンプト・会話履歴・指示ファイルなどすべてが含まれる。入力が長いほど推論コストが増え、長いコンテキストでは中間部分への注意精度が下がることも指摘されている。 – LLM Context Windows Explained: 4K to 1M Tokens (2026) – DevTk.AI
  4. KISS（Keep It Simple, Stupid）は「不要な複雑さを避ける」、YAGNI（You Ain’t Gonna Need It）は「今必要でない機能を実装しない」、DRY（Don’t Repeat Yourself）は「知識の重複を排除する」という設計原則。YAGNI は Extreme Programming（XP）に由来し、DRY は Andy Hunt と Dave Thomas の著書『The Pragmatic Programmer』（1999）で提唱された。 – DRY, KISS & YAGNI Principles: Guide & Benefits | Boldare
  5. ASCII アートによる UI 確認は、テキストのみで画面レイアウトを表現する手法。デザインツールを開かずに構造を整理でき、AI コーディングエージェントへのコンテキスト提供にも向いている。テキストなので Pull Request の説明や Slack にそのまま貼れる利点もある。 – ASCII-Driven Development
  6. 「ローカルでは動くが本番では動かない」は dev/prod parity（開発・本番環境の一致）の欠如として知られる典型的な問題。Twelve-Factor App メソドロジーの第10原則では、開発・ステージング・本番の各環境をできるだけ同一に保つことを推奨している。 – How to Build Production Parity
  7. YAGNI（You Ain’t Gonna Need It）をディレクトリ構成に適用すると、「将来使うかもしれない」だけを理由にフォルダを作らないことになる。Git は空のディレクトリを追跡しないため、実際に使い始めたタイミングで作れば問題ない。 – DRY, KISS & YAGNI Principles: Guide & Benefits | Boldare