Codexで開発を始める人向けの最初の環境構築ガイド

はじめに

Codexアプリを少し触ってみて、「これを本格的な開発や分析に使うには、最初に何を準備すればいいのか」と感じる人は多いと思います。

試しに小さな修正を頼むだけなら、思いついたまま依頼してもそれなりに動きます。しかし、実際の開発で使い始めると、要件の伝え忘れ、設計方針のずれ、テストや報告の抜けが少しずつ問題になります。

この問題は、毎回のプロンプトを工夫するだけでは安定しません。Codexが作業のたびに確認できる、プロジェクトのルール、要件、設計、前提知識を用意しておく方が効果的です。

とはいえ、最初から複雑な環境を作る必要はありません。まずは、初心者がそのまま真似できる最小構成から始めます。

最小構成

最初に作る構成はこれです。

project/
├─ AGENTS.md
├─ README.md
└─ docs/
   ├─ requirements.md
   ├─ design.md
   └─ domain.md

AGENTS.md は、Codex向けの作業ルールを書くファイルです。このプロジェクトではどう進めるか、どのコマンドを使うか、何を完了条件にするかを書きます。

README.md は、人間向けにプロジェクト概要を書くファイルです。何のプロジェクトか、どう使うか、どこを見ればよいかを説明します。

docs/ は、要件、設計、業務知識などの資料を置くフォルダです。Codexに読ませたい前提情報を、目的別に分けて置きます。

この記事の説明

この記事では、まず上の最小構成を実際に作れるように、各ファイルの役割と短いテンプレートを説明します。

その後で、日常の実装前に使う Plan、長時間作業で使う Goal、繰り返し作業をまとめる Skills を紹介します。これらは便利ですが、最初の環境構築で必須ではありません。

流れとしては、まずプロジェクト文書を作り、慣れてきたら補助機能を足していきます。

では、なぜ最初にプロジェクト文書を作るのでしょうか。

なぜプロジェクト文書が重要なのか

Codexの出力品質は、だいたい次の順で決まります。

要件の明確さ
↓
設計の明確さ
↓
作業ルールの明確さ

つまり、いきなり

課題作成機能を作って

と頼むよりも、

AGENTS.mdに従ってください。
docs/requirements.md と docs/design.md を確認してから、
課題作成機能を実装してください。

と頼む方が安定します。

Codexはコードを読むのが得意ですが、プロジェクトの目的や判断基準を勝手に正しく補完できるわけではありません。だから、最初に「何を作るのか」「どう作るのか」「このプロジェクトでは何を守るのか」を文書化しておきます。

AGENTS.mdはCodexへの常設指示

AGENTS.md は、Codexへの常設指示ファイルです。人間で言えば、プロジェクトの業務マニュアルに近いものです。

OpenAIのCodexドキュメントでも、Codexは作業前に AGENTS.md を読み、グローバル設定やプロジェクトごとの指示を組み合わせて扱うと説明されています。厳密には、グローバル、リポジトリ、下位ディレクトリの指示ファイルが階層的に組み合わされます。リポジトリルートに置く AGENTS.md は、プロジェクト固有のルールをCodexに伝えるための基本ファイルです。

参考: Custom instructions with AGENTS.md

読み込まれ方は、ざっくり次のように理解すれば十分です。

Codexでプロジェクトを開く
↓
Codexが対象ディレクトリのAGENTS.mdを確認する
↓
その内容を、このプロジェクトで守る常設ルールとして扱う
↓
ユーザーの依頼内容と組み合わせて作業する

つまり AGENTS.md は、毎回の依頼文に書かなくても効きやすい「プロジェクトの作業ルール」です。ただし、AGENTS.md に何でも詰め込むのではなく、Codexに常に守ってほしいルールだけを書きます。

たとえば、最初はこのくらいで十分です。

# Project Overview

このプロジェクトは、開発チーム向けの課題管理ツールである。

## Workflow

1. 要件確認
2. 設計確認
3. 影響範囲調査
4. 実装
5. テスト
6. 結果報告

## Commands

### Test

pytest

### Lint

ruff check .

## Definition of Done

- テストが通る
- 必要なドキュメントが更新されている
- 変更内容、テスト結果、リスク、残課題を報告する

## Constraints

- 本番DBを直接変更しない
- 勝手に本番依存パッケージを追加しない

AGENTS.md に書くべき内容は、主に次の5つです。

内容	例
プロジェクト概要	何を作るシステムか
作業手順	要件確認、設計確認、実装、テスト、報告
コマンド	test、lint、build
完了条件	何ができたら完了か
禁止事項	本番DB変更禁止、勝手な依存追加禁止

最初から細かく書きすぎる必要はありません。Codexに毎回守ってほしいことだけを書きます。

docsはプロジェクト資料

docs/requirements.md、docs/design.md、docs/domain.md は、プロジェクトの資料です。

ここで重要なのは、これらのファイルは置いただけで常に自動で読まれるとは限らない、という点です。自動で読み込まれやすい標準の指示ファイルは主に AGENTS.md です。

そのため、AGENTS.md に次のようなルールを書いておくと安定します。

## Required Context

実装、設計、調査の前に、必要に応じて以下を確認する。

- docs/requirements.md: 要件
- docs/design.md: 設計
- docs/domain.md: 業務知識
- README.md: プロジェクト概要

また、Codexに依頼するときも、必要な資料を明示します。

AGENTS.mdに従ってください。
docs/requirements.md、docs/design.md、docs/domain.mdを確認してから作業してください。

このひと手間で、Codexが前提を取り違える確率をかなり下げられます。

docs/requirements.mdには「何を作るか」を書く

docs/requirements.md は要件定義です。

たとえば課題作成機能なら、次のように書きます。

# Issue Creation

## Purpose

開発メンバーがバグや改善要望を課題として登録できる。

## Functional Requirements

- タイトルと本文を入力して課題を作成できる
- 優先度を設定できる
- 担当者を設定できる

## Non Functional Requirements

- 通常時は2秒以内に応答する
- 入力内容を検証し、不正な値を保存しない

## Acceptance Criteria

- 必須項目を入力すると課題を作成できる
- 必須項目が不足している場合はエラーを表示する
- 正常系と異常系のテストがある

Codexは要件があると強くなります。逆に、要件が曖昧なまま実装だけ頼むと、見た目は動いていても期待と違うものになりがちです。

docs/design.mdには「どう作るか」を書く

docs/design.md は設計資料です。

たとえば課題作成機能なら、API、DB、処理フローを書きます。

# Issue Creation Design

## API

POST /issues

Request:
- title
- body
- priority
- assignee_id

Response:
- issue_id
- status

## DB

issues
- id
- title
- body
- priority
- assignee_id
- status
- created_at

## Flow

Client
↓
API
↓
DB
↓
Issue List

設計があると、Codexは既存の方針に合わせて実装しやすくなります。特に複数人で開発している場合や、同じプロジェクトを何度もCodexに触らせる場合は、設計資料の有無が効いてきます。

docs/domain.mdには「業務知識」を書く

docs/domain.md は業務知識の置き場です。

プロジェクトに固有の言葉、前提、運用ルールを書きます。

# Domain

## Users

- 開発者
- テックリード
- QA担当者

## Terms

- Issue: バグ、改善要望、作業項目をまとめた課題
- Priority: 対応優先度
- Assignee: 課題の担当者
- Status: 課題の進捗状態

## Business Rules

- 新規課題の初期ステータスはopenにする
- 優先度はlow、medium、highの3種類にする
- 完了した課題はclosedにする

一般的なWebアプリなら最初は薄くても構いません。しかし、開発チームの運用ルール、リリース判断、レビュー基準のようにプロジェクト固有の前提がある場合は、domain.md がかなり効きます。

Codexは一般知識を持っていますが、あなたの会社やプロジェクト固有の判断基準は知りません。そこを domain.md で補います。

実際に最小構成を作る

ここからは、実際に最小構成を作ります。コマンドを覚える必要はありません。プロジェクトのルートに次のファイルとフォルダを作ってください。

project/
├─ AGENTS.md
├─ README.md
└─ docs/
   ├─ requirements.md
   ├─ design.md
   └─ domain.md

1. フォルダ構成を作る

まず、プロジェクト直下に docs フォルダを作ります。その中に、requirements.md、design.md、domain.md を作ります。

2. AGENTS.mdを作る

実践用の最小版はこのくらいで十分です。詳細なルールは、運用しながら足していきます。

# Project Overview

このプロジェクトは、開発チーム向けの課題管理ツールです。

## Required Context

実装、設計、調査の前に、必要に応じて以下を確認する。

- README.md: プロジェクト概要
- docs/requirements.md: 要件
- docs/design.md: 設計
- docs/domain.md: 業務知識

## Workflow

1. 要件を確認する
2. 設計を確認する
3. 影響範囲を調べる
4. 実装または分析を行う
5. 必要な確認を行う
6. 変更内容、確認結果、リスク、残課題を報告する

## Definition of Done

- 要件と設計に合っている
- 必要な確認が終わっている
- 変更内容、確認結果、リスク、残課題を報告している

3. README.mdを作る

README.md は人間向けの入口です。Codexだけでなく、自分やチームメンバーが最初に読むファイルとして使います。

# 開発チーム向け課題管理ツール

## 概要

このプロジェクトは、開発チームがバグ、改善要望、作業項目を課題として管理するためのツールです。

## 主要ドキュメント

- AGENTS.md: Codex向けの作業ルール
- docs/requirements.md: 何を作るか
- docs/design.md: どう作るか
- docs/domain.md: 業務知識、用語、前提

## Codexに作業を頼む時の注意

作業を頼む時は、AGENTS.mdに従い、必要に応じてdocs配下の資料を確認するように伝える。

4. docs/requirements.mdを作る

最初は、目的、要件、完了条件だけで構いません。

# Requirements

## Purpose

開発メンバーが課題を作成し、担当者と優先度を設定できるようにする。

## Functional Requirements

- タイトルと本文を入力して課題を作成できる
- 優先度を設定できる
- 担当者を設定できる

## Non Functional Requirements

- 通常時は2秒以内に応答する
- 不正な入力値を保存しない

## Acceptance Criteria

- 必須項目を入力すると課題を作成できる
- 必須項目が不足している場合はエラーを表示する
- 正常系と異常系のテストがある

5. docs/design.mdを作る

設計は、実装方法の判断材料です。最初から完璧でなくて構いません。

# Design

## Architecture

フロントエンド、API、DBで構成する。

## Main Flow

課題作成画面からAPIに送信し、DBに保存して課題一覧に反映する。

## Data

- issuesテーブル
- POST /issues
- title、body、priority、assignee_id、status

## Decisions

- 新規課題の初期ステータスはopenにする
- 優先度はlow、medium、highに限定する

6. docs/domain.mdを作る

業務知識が少ないプロジェクトでも、用語と前提を書いておくと後で効きます。

# Domain

## Terms

- Issue: バグ、改善要望、作業項目をまとめた課題
- Priority: 対応優先度
- Assignee: 課題の担当者

## Assumptions

- ユーザー管理機能は既に存在する
- 担当者には既存ユーザーを指定する

## Business Rules

- 新規課題の初期ステータスはopenにする
- 完了した課題はclosedにする

7. Codexに依頼する文面を使う

ファイルを作ったら、Codexには次のように依頼します。

AGENTS.mdに従ってください。
docs/requirements.md、docs/design.md、docs/domain.mdを確認してから作業してください。

課題作成機能を実装してください。

完了後に、変更内容、確認結果、リスク、残課題を報告してください。

README.md は人間向けの入口なので、通常の実装依頼では必ず読ませる必要はありません。重要なのは、資料を置くだけでなく、作業に必要な docs を確認するように明示することです。

この構成だけで、Codexの作業はかなり安定します。

成長ステップ

最小構成を作ったら、次は次の順で育てます。最初から完成形を目指す必要はありません。

Phase 1: AGENTS.md、README.md、docsを作る

まずは最低限の環境を作ります。

project/
├─ AGENTS.md
├─ README.md
└─ docs/
   ├─ requirements.md
   ├─ design.md
   └─ domain.md

この段階ではGoalもSkillsも不要です。

Phase 2: Planを使う

日常の開発では、実装前にPlanを使います。

/plan
docs/requirements.md と docs/design.md を確認して、
実装方針、影響範囲、必要なテストを整理してください。

Planをレビューしてから実装に進むと、手戻りが減ります。

Phase 3: 長時間作業でGoalを使う

数時間以上かかる作業や、複数回の検証が必要な作業ではGoalを使います。

Goal:
課題管理機能を刷新する。

成功条件:
- 課題作成、更新、一覧表示の仕様が整理されている
- 既存の課題管理コードが新しい設計に沿って整理されている
- 全テストが通る
- ドキュメントが更新されている

Phase 4: 繰り返し作業をSkillsにする

同じ専門作業を何度も依頼するようになったら、Skillsを作ります。

Phase 4まで進んだときの構成は、たとえば次のようになります。

project/
├─ AGENTS.md
├─ README.md
├─ docs/
│  ├─ requirements.md
│  ├─ design.md
│  ├─ domain.md
│  ├─ architecture.md
│  └─ decisions.md
└─ .codex/
   └─ skills/
      ├─ code_review/
      │  └─ SKILL.md
      ├─ architecture_review/
      │  └─ SKILL.md
      ├─ test_design/
      │  └─ SKILL.md
      └─ release_check/
         └─ SKILL.md

docs/architecture.md や docs/decisions.md は、最初から作る必要はありません。設計判断やアーキテクチャの説明が増えてきたら追加します。

Skillsは、環境構築の最初に作るものではなく、運用が成熟してから効いてくるものです。

Planは日常的に使う

Planは「どう進めるか」を整理するためのものです。実装前に、触るファイル、影響範囲、必要なテスト、リスクを確認したいときに使います。

たとえば、いきなり実装させる前にこう依頼します。CLIやコマンド入力中心の環境では、/plan を使います。Codexアプリでは、/(スラッシュ)を入力すると、「プランモード」を選択できます。

/plan
課題作成機能を追加したい。
既存コードを調査して、
実装方針、影響範囲、必要なテストを整理してください。

おすすめの流れはこうです。

要件を書く
↓
設計を書く
↓
Planで進め方を確認する
↓
実装する
↓
テストする
↓
結果を確認する

初心者ほど、Goalより先にPlanを使う方が実務上の価値は大きいです。

Goalは最初は不要

Goalは「何を達成するか」をCodexに持たせるためのものです。Planが「どう進めるか」なら、Goalは「どの状態になれば成功か」です。

Goal = 何を達成するか
Plan = どう達成するか

たとえば、課題管理機能の刷新、大規模リファクタ、ライブラリ移行、大量のテスト修正のような作業ではGoalが役に立ちます。

OpenAIのCodex use casesでも、Goalは長時間の作業に対して持続的な目的を与えるものとして紹介されています。また、Codexアプリのドキュメントでは、GoalはCodexが作業を続けるための永続的な目的として説明されています。

参考: Codex Use Cases、Codex app commands

使い方はシンプルです。CLIやコマンド入力中心の環境では、/goal <目的> を使います。Codexアプリでは、/(スラッシュ)を入力して /goal (目標)を選択します。利用できるコマンドは環境や設定によって変わるため、/goal が表示されない場合は機能設定を確認してください。

Goalに入れる内容は、たとえば次のようにします。CLIで設定する場合は、まず /goal 課題作成機能を完成させる。 のように目的を設定し、詳しい成功条件は続く依頼文や参照ファイルで補足します。

Goal:
課題作成機能を完成させる。

参照資料:
- AGENTS.md
- README.md
- docs/requirements.md
- docs/design.md
- docs/domain.md

成功条件:
- タイトル、本文、優先度、担当者を入力して課題を作成できる
- 必須項目が不足している場合はエラーを表示できる
- 必要なテストが追加されている
- テストが通っている
- 変更内容、確認結果、リスク、残課題が報告されている

制約:
- 要件にない外部サービスを勝手に追加しない
- 既存の課題ステータス仕様を変える場合は先に理由を説明する

Goalは、細かい作業手順ではありません。「何を達成したいか」と「何ができたら完了か」です。

一方で、次のような小さな作業ならGoalは不要です。

このバグを直して
APIを1つ追加して
テストを追加して

小さな作業は普通に依頼すれば十分です。

Skillsは「知識」ではなく「手順」

Skillsは再利用可能な専門作業のパッケージです。OpenAIのCodex use casesでも、繰り返すワークフローをSkillとして保存する使い方が紹介されています。

参考: Codex Use Cases

OpenAIのSkillsリポジトリでは、Skillは特定タスクのための指示、スクリプト、リソースをまとめたフォルダとして説明されています。また、SKILL.md の name と description は、CodexがそのSkillをいつ使うか判断するための重要な情報です。

参考: OpenAI Skills

ここで大事なのは、Skillsは単なる知識ファイルではないということです。

AGENTS.mdとの違いは、読み込まれ方です。

AGENTS.md
= プロジェクトを開いたときに効く常設ルール

Skills
= 必要な作業に合いそうなときだけ使われる専門手順

Skillは、通常この形で置きます。

.codex/
└─ skills/
   └─ code_review/
      └─ SKILL.md

Codexは、まずSkillの名前や説明を見て「今回の作業に関係がありそうか」を判断します。関係があると判断されたときに、そのSkillの本文を読んで作業に使います。確実に使わせたい場合は、依頼文でSkill名を指定するか、Codexアプリでは $、CLIでは /skills から明示的に選択します。

そのため、SKILL.md の description には、単なる説明ではなく「どんな作業のときに使うのか」を書きます。

---
name: code_review
description: Use when reviewing code changes for bugs, regressions, security risks, and missing tests.
---

良くない例はこれです。

Reactとは何か
Pythonとは何か
SQLとは何か

Codexはこのような一般知識をすでに持っています。わざわざSkillにしても、あまり効果はありません。

良い例は、専門家の作業手順です。

コードレビューの進め方

1. 変更目的の確認
2. 差分の確認
3. バグや回帰リスクの確認
4. テスト不足の確認
5. セキュリティリスクの確認
6. 修正提案の整理

または、

設計レビューの進め方

1. 責務分離
2. 拡張性
3. テスト容易性
4. セキュリティ
5. 運用リスク

のようなものです。

つまりSkillsに向いているのは、知識そのものではなく、何度も使う専門家の思考プロセスです。

Skillsを作るタイミング

最初からSkillsを作る必要はありません。目安は簡単です。同じ指示を3〜5回以上繰り返したら、Skill化を考えます。

たとえば毎回こう言っているとします。

リリース前確認をしてください。

確認事項:
- 未解決の重大バグ
- マイグレーションの有無
- テスト結果
- リリース手順
- ロールバック手順

この指示を何度も使うなら、Skillにする価値があります。

プロジェクト専用Skillを置くなら、構造は次のようにします。

.codex/
└─ skills/
   └─ release_check/
      └─ SKILL.md

SKILL.md には、少なくとも名前、説明、作業手順、出力形式を書きます。

---
name: release_check
description: Use before releasing software changes to verify blockers, tests, migration steps, and rollback plan.
---

# Release Check Workflow

1. Review release scope
2. Check unresolved critical bugs
3. Confirm test results
4. Review migration steps
5. Review deployment steps
6. Confirm rollback plan

## Output

- Release blockers
- Required actions
- Deployment risks
- Rollback notes

ただし、これは最初の一歩ではありません。まずは要件と設計です。

迷ったときの置き場所

迷ったら、この表で判断します。

内容	置き場所
プロジェクトルール	AGENTS.md
プロジェクト概要	README.md
要件	docs/requirements.md
設計	docs/design.md
業務知識	docs/domain.md
繰り返す専門手順	.codex/skills/{name}/SKILL.md

この分類を守るだけで、Codex環境はかなり扱いやすくなります。

まとめ

Codexで開発を始めるとき、最初にやるべきことは多くありません。

まず作るのはこれです。

AGENTS.md
README.md
docs/requirements.md
docs/design.md
docs/domain.md

最初からGoalやSkillsに手を出す必要はありません。

Goalは長時間作業のためのミッション管理です。Planは日常的な実装前整理です。Skillsは繰り返し使う専門手順です。

最初の品質を決めるのは、要件、設計、作業ルール、そしてプロジェクト概要です。

Codexをうまく使う第一歩は、すごいプロンプトを探すことではありません。Codexが迷わず読めるプロジェクト文書を用意することです。