• 要件をどう実現するかを理解するまで、AIに実装を許可しない。
• 実装後にどのような仕様になるのかを理解するまで、AIに実装を許可しない。
• 画面・API・DB・バッチ・テストなどの影響範囲を理解するまで、AIに実装を許可しない。
• 設計書・実装計画書を作っただけで着手しない。複数人確認までを着手条件にする。
• 決めたこと、採用した方針、採用しなかった理由は必ずドキュメント化する。
• Codex の調査結果や実装方針で分からない用語、処理、影響範囲があれば、実装前に質問する。
• 「AIがそう言ったから」で進めない。自分の言葉で、対象ファイル、変更理由、戻し方を説明できる状態にする。
• 理解できない場合は、Codex に「初心者にも分かるように実装方針を説明して。まだ実装しないで」と依頼する。

実装前に、AIへ整理項目を提案させ、人間が漏れを判断してから仕様・計画書へ落とす会話例です。

最終更新日: 2026-05-13

このマニュアルは、ChatGPT と Codex を併用する開発現場で、以下を実現するための運用指針である。

• Codex の無駄な token 消費を減らす
• 曖昧な依頼や試行錯誤によるコスト増を防ぐ
• 実装品質を上げる
• 手戻りを減らす
• 仕様・設計・判断をドキュメントとして残す
• ロールバック可能な安全な開発フローを徹底する

重要なのは、Codex を禁止・過度に制限することではない。

改修・保守・既存コード変更では、Codex はメインで使うべきである。

なぜなら、既存コードを読まないと正しい修正ができないからである。

ただし、Codex にいきなり曖昧な依頼を投げると、以下が発生する。

• 不要なファイル探索
• 大量の context 読み込み
• 誤った実装
• テスト失敗
• 再修正
• さらに追加調査
• ロールバック不能な差分拡大

そのため、Codex を使う前に ChatGPT で仕様・設計・作業範囲を整理し、Codex には実装に集中させる。

2.1 コストが高いのは「実装」ではなく「迷走」

AI開発で token を大量消費する主な原因は、実装そのものではない。

一番高いのは次のループである。

曖昧な依頼
↓
Codexが広範囲を探索
↓
誤った実装
↓
テスト失敗
↓
追加修正依頼
↓
さらに探索
↓
差分拡大
↓
ロールバック困難

このループを止めることが最重要である。

2.2 Codexの利用を減らすのではなく、Codexの失敗回数を減らす

Codexは改修・既存コード理解・複数ファイル修正に向いている。

したがって、改修案件ではCodexを主役にしてよい。

ただし、Codexに渡す前に以下を明確にする。

• 何を直すのか
• なぜ直すのか
• どのファイルを読むのか
• どのファイルは触らないのか
• 既存仕様との互換性
• テスト観点
• ロールバック方法
• 失敗時の対応方針

2.3 理解できない状態でAIに実装を許可しない

Codexに実装を任せる前に、担当者自身が以下を説明できる状態にする。

• 要件をどう実現するのか
• 実装後にどのような仕様になるのか
• 既存仕様から何が変わるのか
• どの画面・API・DB・バッチ・テストに影響するのか
• どのファイルを変更し、どのファイルは変更しないのか
• 失敗した場合にどう戻すのか
• 設計書を誰が確認し、複数人確認が完了しているか

特に、設計書を複数人で確認するまでは実装しない。

また、実装方針を理解できない状態でAIに作業させない。Codexの調査結果や提案内容が理解できない場合は、すぐ実装に進まず、以下のように確認する。

まだ実装しないでください。

この要件をどう実現するのか、初心者にも分かるように説明してください。

出力:
1. 実現方法
2. 修正後の仕様
3. 影響範囲
4. 変更するファイル
5. 変更しないファイル
6. テスト観点
7. ロールバック方法
8. 実装前に人が確認すべきこと

担当者が自分の言葉で説明できない場合、その作業はまだAIに実装させてはいけない。

凡例:

• ◎: 主担当
• ○: 補助的に利用
• △: 必要時のみ
• ×: 原則使わない

推奨フロー

ChatGPTで要件整理
↓
ChatGPTで仕様書作成
↓
ChatGPTで設計案比較
↓
ChatGPTで実装計画書作成
↓
Codexで実装
↓
Codexでテスト追加
↓
Git diff確認
↓
ChatGPTでPR説明文作成

ChatGPTにやらせること

• 機能仕様の整理
• API仕様案の作成
• DB設計案の比較
• エッジケース整理
• テスト観点整理
• 実装計画書作成

Codexにやらせること

• 既存構成に合わせた実装
• 型定義追加
• テスト追加
• Lint修正
• 差分作成

Codexへの指示例

docs/ai-work/2026-05-13-user-invite.md を読んで実装してください。

制約:
- 仕様書に書かれた対象ファイルを中心に確認すること
- 仕様書にないDB変更は行わないこと
- 既存APIレスポンス形式を壊さないこと
- 実装後は指定されたテストのみ実行すること
- テスト失敗時は、すぐ修正せず原因と修正案を報告すること

改修はCodexメインでよい。

理由は、既存コードの構造・命名・依存関係・テストを読む必要があるため。

ただし、Codexにいきなり「この機能を直して」と投げない。

推奨フロー

ChatGPTで改修目的を整理
↓
ChatGPTで仕様差分を整理
↓
Codexで対象コード調査
↓
Codexに調査結果を要約させる
↓
ChatGPTで実装計画をレビュー
↓
Codexで実装
↓
Git diff確認
↓
Codexでテスト
↓
失敗時は分析のみ

ポイント

改修では、ChatGPTにコード全体を無理に貼り付ける必要はない。

代わりに、Codexに以下をやらせる。

まず実装せず、以下を調査してください。

1. 関係するファイル
2. 現在の処理フロー
3. 変更が必要な箇所
4. 変更すると影響を受ける箇所
5. テストすべき観点

まだコードは変更しないでください。

この調査結果を元に、ChatGPTで実装計画をレビューする。

その後、Codexに実装させる。

なぜこの方法が良いか

Codexにコードを読ませる必要はある。

しかし、いきなり実装させる必要はない。

まず「調査だけ」をさせることで、無駄な実装失敗を防げる。

悪い例

エラーが出るので直して

これは高コストになりやすい。

良い例

まず修正せず、原因分析だけしてください。

入力:
- エラーログ
- 再現手順
- 期待する動作
- 実際の動作

出力:
1. 原因候補
2. 関係ファイル
3. 確認すべきコード
4. 修正方針
5. テスト観点

まだ実装しないでください。

推奨フロー

ChatGPTでエラーログ整理
↓
Codexで関係コード調査
↓
ChatGPTで原因仮説を整理
↓
Codexで最小修正
↓
テスト
↓
失敗したら分析のみ

PDFや長文ドキュメントはChatGPTで整理する。

CodexにPDF読解や議事録整理をやらせると、実装以外でtokenを消費しやすい。

推奨フロー

ChatGPTでPDF仕様書を解析
↓
ChatGPTで実装仕様に変換
↓
ChatGPTで実装計画書を作成
↓
Codexに実装計画書だけ渡す
↓
Codexで実装

ChatGPTで作る成果物

docs/specs/
docs/ai-work/
docs/decisions/

例:

docs/ai-work/2026-05-13-payment-timeout-fix.md
docs/specs/payment-timeout-spec.md
docs/decisions/adr-2026-05-13-payment-timeout.md

リファクタリングはCodex向きだが、最もtokenを使いやすい作業でもある。

範囲を必ず限定する。

悪い例

全体をきれいにリファクタして

良い例

UserService の責務分離のみ行ってください。

対象:
- src/users/user.service.ts
- src/users/user.repository.ts
- src/users/user.service.spec.ts

禁止:
- APIレスポンス形式の変更
- DB schema変更
- 認証処理の変更
- unrelated file の修正

完了条件:
- 既存テストが通る
- public method のシグネチャを維持
- diffが300行以内

リファクタリング時のルール

• 1回の作業は300行diff以内を目安にする
• public APIを変える場合は別タスクにする
• renameだけ、責務分離だけ、型改善だけ、のように分ける
• テスト追加とリファクタを同時に巨大化させない

テスト追加はCodex向き。

ただし、先にテスト観点をChatGPTで整理すると失敗が減る。

ChatGPTに依頼

以下の仕様からテスト観点を作ってください。

出力:
- 正常系
- 異常系
- 境界値
- 回帰テスト
- mockが必要な箇所
- 既存テストへの追加方針

Codexに依頼

docs/ai-work/... のテスト計画に従ってテストを追加してください。

制約:
- 実装コードは変更しない
- テストファイルのみ変更
- 既存のテストスタイルに合わせる

差分レビューはChatGPTでもCodexでも可能。

ただし、Git差分を元にする。

推奨

git diff --stat
git diff

ChatGPT向け依頼

以下のgit diffをレビューしてください。

観点:
1. 仕様との一致
2. 影響範囲
3. 破壊的変更の有無
4. テスト不足
5. 命名・責務
6. セキュリティリスク

Codex向け依頼

現在の差分をレビューしてください。
まだ修正しないでください。

出力:
- 問題点
- 修正すべき箇所
- 修正不要だが注意すべき点
- 追加テスト案

必ず以下を作る。

docs/ai-work/YYYY-MM-DD-task-name.md

内容:

# AI実装計画書

## 目的

## 背景

## 現状の問題

## 期待する動作

## 仕様詳細

## 対象ファイル

## 変更禁止ファイル

## 実装方針

## 影響範囲

## テスト計画

## ロールバック方法

## Codexへの指示

Codexには以下の順で作業させる。

1. 調査
2. 実装計画確認
3. 実装
4. テスト
5. 差分要約

重要:

調査と実装を同時にさせない。

調査だけの指示

まだ実装しないでください。
まず関係ファイルと現在の処理フローを調査し、実装方針を報告してください。

実装の指示

上記の実装方針で進めてください。
対象外ファイルは変更しないでください。

必ずGitで確認する。

git status
git diff --stat
git diff

必要に応じてテスト。

pnpm test
pnpm lint
pnpm typecheck

失敗したら、すぐに「直して」と依頼しない。

NG

テスト落ちた。直して。

OK

テストが失敗しました。
まだ修正しないでください。

出力:
1. 失敗原因
2. 関係ファイル
3. 修正が必要な箇所
4. 修正案
5. 追加で読む必要があるファイル

git checkout -b fix/task-name

または

git switch -c fix/task-name

git status

未コミット変更がある場合、AI作業を開始しない。

git diff --stat
git diff

Codexに「元に戻して」と頼らない。

ロールバックはGitで行う。

全変更を戻す

git restore .

特定ファイルだけ戻す

git restore path/to/file

stagedを戻す

git restore --staged .

直前のコミットを取り消す

git revert <commit-hash>

Codexに「元に戻して」と依頼すると、以下が起きやすい。

• どこまで戻すべきか曖昧
• 追加の探索が発生
• 別の差分を作る
• さらにtokenを使う
• 完全に元に戻らない可能性がある

ロールバックはGitの責務である。

ドキュメントは単なる記録ではない。

AIのtoken削減装置である。

毎回チャットで説明するとtokenを消費する。

設計資料として残せば、次回はそれを読むだけで済む。

会議、設計相談、AIとの調査、レビュー、実装前確認で決めたことは必ずドキュメント化する。

特に以下は、チャットだけで終わらせない。

• 要件をどう実現するか
• 実装後にどのような仕様になるか
• 採用した実装方針
• 採用しなかった案と理由
• 影響範囲
• 変更禁止事項
• テスト観点
• ロールバック方法
• 複数人で確認した設計書・計画書の確認結果

保存先は内容に合わせて分ける。

• 実装前の作業範囲と方針は docs/ai-work/
• 確定した仕様は docs/specs/
• 設計判断や方針比較は docs/decisions/
• 障害原因や失敗分析は docs/troubleshooting/

このルールの目的は、記録を増やすことではない。

次回以降に同じ説明や判断を繰り返さず、AIにも人にも同じ前提を渡せるようにすることである。

推奨:

docs/
  ai-work/
  specs/
  decisions/
  troubleshooting/

用途

# AI実装計画書

## 1. 目的
この作業で実現することを書く。

## 2. 背景
なぜこの作業が必要かを書く。

## 3. 現状の問題
現在発生している問題、制約、既存仕様を書く。

## 4. 期待する動作
修正後にどう動くべきかを書く。

## 5. 仕様詳細

### 正常系

### 異常系

### 境界値

### 互換性

## 6. 対象ファイル
- `src/...`
- `tests/...`

## 7. 変更禁止ファイル
- `generated/`
- `schema.prisma`
- `package-lock.json`

## 8. 実装方針
1. 
2. 
3. 

## 9. 影響範囲
- API:
- DB:
- UI:
- Batch:
- Test:

## 10. テスト計画

### 実行コマンド

pnpm test

pnpm lint

pnpm typecheck

### 確認項目

- 
- 
- 

## 11. ロールバック方法

git restore .

または

git revert <commit-hash>

## 12. Codexへの指示

この計画書に従って実装すること。
計画にないファイル変更は事前に理由を説明すること。
テスト失敗時は、すぐ修正せず原因と修正案を報告すること。

まだ実装しないでください。

以下を調査してください。

1. 関係するファイル
2. 現在の処理フロー
3. 変更が必要そうな箇所
4. 影響範囲
5. 追加で確認すべきファイル
6. 実装方針案

出力後、実装は止めてください。

docs/ai-work/YYYY-MM-DD-task-name.md を読んで、実装方針に従って修正してください。

制約:
- 対象ファイルを中心に作業する
- 対象外ファイルを変更する場合は理由を説明する
- 既存API仕様を壊さない
- DB変更は指示がある場合のみ
- 生成ファイルは変更しない
- テスト失敗時は、すぐ修正せず原因を報告する

実装コードは変更せず、テストのみ追加してください。

対象:
- 正常系
- 異常系
- 境界値
- 回帰テスト

既存のテストスタイルに合わせてください。

テストが失敗しました。
まだ修正しないでください。

出力:
1. 失敗したテスト
2. 原因候補
3. 関係ファイル
4. 修正案
5. 追加調査が必要な箇所

実装は止めてください。

現在のgit diffをレビューしてください。
まだ修正しないでください。

観点:
1. 仕様との一致
2. 影響範囲
3. 破壊的変更
4. テスト不足
5. セキュリティ
6. 不要な差分

最後に、修正すべき点を優先度順に出してください。

このPDF仕様書を読み、実装に必要な情報だけを整理してください。

出力:
1. 機能概要
2. 実装要件
3. 非機能要件
4. 既存システムへの影響
5. API仕様
6. DB影響
7. エッジケース
8. テスト観点
9. Codexに渡す実装指示

以下の要件から、Codexに実装させるためのAI実装計画書を作ってください。

重視すること:
- 作業範囲を明確にする
- 変更禁止事項を書く
- テスト観点を書く
- 失敗時の対応を書く
- Gitロールバック手順を書く

以下はCodexが調査した内容です。
実装前にレビューしてください。

観点:
1. 調査範囲は十分か
2. 実装方針に抜けがないか
3. 影響範囲に漏れがないか
4. 先に確認すべきことはないか
5. Codexに渡すべき最終指示

以下の実装計画書とgit diff要約からPR説明文を作ってください。

出力:
- 概要
- 変更内容
- テスト
- 影響範囲
- レビューしてほしい点
- ロールバック方法

以下は禁止。

全部見て直して

なんか動かないから直して

いい感じにリファクタして

エラー出た。直して。

このリポジトリ全体を理解して

• 作業前にGit状態を確認しない
• ブランチを切らずにCodex作業を始める
• 実装計画書なしで大きな修正を依頼する
• テスト失敗時に即「直して」と依頼する
• Codexにロールバックを任せる
• PDF仕様書をCodexに読ませてから実装させる
• 長い会話で何度も修正を続ける
• unrelated file の変更を放置する
• diffを見ずにPRを出す

• [ ] 作業ブランチを切った
• [ ] git status が clean である
• [ ] 仕様・目的を説明できる
• [ ] 実装計画書を作った
• [ ] 対象ファイルを明記した
• [ ] 変更禁止ファイルを明記した
• [ ] テスト計画を書いた
• [ ] ロールバック方法を書いた

• [ ] まず調査だけさせた
• [ ] 実装前に調査結果を確認した
• [ ] 対象外ファイル変更の理由を確認した
• [ ] 失敗時に即修正させていない

• [ ] git diff --stat を確認した
• [ ] git diff を確認した
• [ ] 不要な差分を戻した
• [ ] テストを実行した
• [ ] 実装計画書を更新した
• [ ] PR説明文を作成した

新人

• ChatGPTで仕様整理を必ず行う
• Codex実行前にAI実装計画書を作成する
• Codexにはまず調査だけ依頼する
• 実装後は必ず先輩レビュー
• ロールバックはGitのみ

中堅

• 改修はCodexメインで可
• ただし大規模変更は実装計画書必須
• PR前にdiffレビューを行う
• テスト失敗時は分析フェーズを挟む

リード

• 社内スキル・MCP・テンプレート運用を整備
• 仕様書テンプレートを管理
• AI利用コストを定期確認
• 失敗事例をdocs/troubleshootingに蓄積

1. 実装前にAI実装計画書を作る
2. Codexにまず調査だけさせる
3. テスト失敗時に即修正させない
4. Gitでロールバックする
5. PDF・仕様書・議事録はChatGPTで整理する
6. docsに判断を残す
7. 大規模改修を小さく分割する
8. 長いセッションを避ける
9. diffを必ず確認する

実装させる
↓
うまくいかない
↓
また修正させる
↓
また失敗する
↓
また修正させる

このループを避けるために、失敗時は必ず分析フェーズに戻る。

• 作業タスク確認
• ChatGPTで仕様整理
• AI実装計画書作成
• ブランチ作成

• Codexに調査のみ依頼
• 調査結果を確認
• 必要ならChatGPTで実装計画を修正

• Codexで実装
• テスト実行
• 失敗時は原因分析のみ

• git diff確認
• 不要差分削除
• docs更新
• PR説明文作成

この運用の要点は以下である。

• 改修ではCodexをメインに使ってよい
• ただし、いきなり実装させない
• ChatGPTで仕様・設計・PDF・議事録を整理する
• Codexにはコード調査・実装・テストを担当させる
• 実装前にAI実装計画書を作る
• 失敗時は即修正禁止、まず分析
• ロールバックは必ずGitで行う
• 判断と仕様はdocsに残す
• token削減の本質はCodex制限ではなく、失敗回数の削減である

最終ルール:

ChatGPTで考える
Codexで作る
Gitで戻す
docsに残す

• OpenAI Help Center: Using Codex with your ChatGPT plan
• OpenAI Developers: Codex
• OpenAI Help Center: Codex collection