技術資料

Codexに「〇〇なアプリを作って」と指示を出すと、ある程度動くものを短時間で作ってくれます。

ただし、作りたいものの条件が整理されていないまま実装を始めると、後から仕様を変更したり、作り直したりする場面も増えます。なので、実装前に設計と作業分解を行っておく方が、手戻りが少なくなります。

今回は、ChatGPT、GitHub、Codexを使い分けて、設計から実装、レビューまで進める流れを整理します。

設計やIssueの作成は通常のChatGPT、コードの実装や検証はCodex、変更の保存とレビューはGitHubという分担です。GitHubへのpushやPull Requestの作成は、Codexアプリ、Visual Studio Codeの拡張機能、またはGitコマンドから行います。

設計やIssueの作成でCodexを使わないのは、Codexのトークン消費を少しでも抑えたいからという理由なので、がんがんクレジット課金できる富豪の皆様は全部Codexで完結しても良いと思います。

前提

今回の対象は、GitHub上で管理しているWebアプリケーションの開発です。

• GitHubのリポジトリがある
• Markdown形式の設計書をリポジトリで管理する
• GitHub Issueを実装単位の指示書として使う
• Codexアプリ、VS Code拡張、またはGitコマンドを利用できる
• 実装前後に人が設計、差分、テスト結果を確認する

Codexの利用方法や機能は変更される可能性があります。現在の機能や利用条件については、Codexの公式ドキュメントを確認してください。

ChatGPT、GitHub、Codexの役割を分ける

まず、各サービスに任せる作業を分けます。

OpenAIの公式サイトでも、Codexはコードベースの理解、機能の実装、テスト、変更のレビュー、出荷準備に利用するものとして案内されています。アイディアやIssueを実装へつなげる使い方とも相性がよいと思います。

ただし、すべての作業を機械的に分担する必要はありません。例えば、設計書の内容を確認するのは人が行い、設計書をもとにした文章の整理だけをChatGPTへ依頼する、といった使い方でも構いません。

先に設計してから実装を依頼する

単純に「タスク管理アプリを作って」と指示すると、Codexは不足している条件を推測しながら実装することになります。

この方法でも動くものは作れますが、次のような判断が後から発生しやすくなります。

• ユーザーが登録できる情報
• ログインが必要かどうか
• データを保存する場所
• 入力エラーをどのように表示するか
• 実装後に何を確認すれば完了とするか

このような条件が実装途中で追加されると、既に作った画面やデータ構造を変更する必要が出てきます。

そこで、まずChatGPTと設計の壁打ちを行います。ここで重要なのは、ChatGPTに最終的な設計を任せることではありません。自分の考えを文章にし、抜けている条件や矛盾している部分を見つけるために使います。

次のアプリの設計を整理してください。

目的:
個人で使うタスク管理アプリを作りたい。

現時点で決まっていること:
- タスク名と期限を登録する
- 完了したタスクを一覧から確認できる
- ログイン機能を追加する

次の観点で、不足している条件と確認が必要な点を整理してください。
- 画面
- データ
- 権限
- 入力チェック
- エラー表示
- 動作確認

この段階では、すぐにコードを書かせるのではなく、決まっていないことを洗い出します。設計について自分で判断した内容は、ChatGPTの回答をそのまま採用せず、設計書へ反映する前に確認します。

Markdownで設計書を作る

壁打ちで整理した内容は、Markdownの設計書として保存します。例えば、次のような構成です。

# タスク管理機能の設計

## 目的

ログインしたユーザーが、自分のタスクを登録・確認できるようにする。

## 対象範囲

- タスクの登録
- タスク一覧の表示
- タスクの完了状態の変更
- ログイン済みユーザー自身のタスクだけを表示

## 対象外

- メール通知
- 他のユーザーとの共有
- スマートフォン向けアプリ

## 画面

- タスク一覧画面
- タスク登録画面
- タスク編集画面

## データ

- タスク名
- 期限
- 完了状態
- 作成者

## 完了条件

- ログインユーザーがタスクを登録できる
- 自分のタスクだけが表示される
- 必須入力が空の場合にエラーになる
- 対象のテストが成功する

対象範囲と対象外を分けて書いておくと、Codexが実装範囲を広げすぎるのを防ぎやすくなります。

また、設計書にはAPIキー、パスワード、個人情報などを記載しません。実際のリポジトリをChatGPTやCodexから参照する場合も、連携先へ渡す情報と権限の範囲を確認します。

設計をGitHub Issueへ分割する

設計書全体を一つのファイルとして渡して、「この機能を全部実装してください」と依頼する方法もあります。しかし、設計書の範囲が大きすぎると、変更内容の確認や問題の切り分けが難しくなります。

そこで、設計書を実装単位へ分割します。GitHub公式のIssueを使った作業の計画と追跡でも、Issueを作業の分解や進捗管理に使う方法が説明されています。例えば、次のようなIssueに分けます。

1. タスクテーブルとモデルを作成する
2. タスク登録画面と登録処理を作成する
3. タスク一覧画面を作成する
4. ログインユーザー自身のタスクだけを表示する
5. 入力チェックとテストを追加する

通常のChatGPTからGitHubへ接続できる環境では、設計書をもとにIssueを作成したり、既存Issueへコメントを追加したりできます。私の環境では、設計の整理からIssueの作成、実装後の修正依頼までを通常のChatGPTから行っています。

利用できるアプリや操作は、ChatGPTのプラン、ワークスペース設定、GitHub側の権限などによって変わる可能性があります。Issueを作成できない場合は、GitHubの画面やGitHub CLIから登録します。

Issueには、少なくとも次の項目を記載します。

## 目的

タスクをデータベースへ保存できるようにする。

## 実装内容

- tasksテーブルを追加する
- Taskモデルを追加する
- ログインユーザーを作成者として保存する

## 対象ファイル

- database/migrations/
- app/Models/Task.php
- app/Http/Controllers/TaskController.php

## 完了条件

- ログインユーザーがタスクを登録できる
- 作成者のIDが保存される
- 未入力の場合はバリデーションエラーになる
- 対象テストが成功する

## 注意点

- 他のユーザーのタスクを登録・参照できないこと
- 既存の認証処理を変更しないこと

Issueを小さく分けると、Codexへ渡す指示も小さくできます。設計書が全体像、Issueが一回の実装内容、という関係にしておくと、作業の範囲を確認しやすくなります。

CodexへIssue単位で実装を依頼する

Issueを作成したら、Codexへ対象のIssueを伝えて実装を依頼します。

GitHub Issue #123の内容を実装してください。

実装前に、次の順番で進めてください。
1. リポジトリの構成と関連ファイルを確認する
2. 変更予定のファイルと実装方針を説明する
3. 不明点や設計書との矛盾があれば質問する
4. 問題がなければ実装する
5. 対象のテストまたは動作確認を実行する
6. 変更したファイル、実行したコマンド、結果を説明する

私が確認するまで、commitとpushは実行しないでください。

最初に変更予定のファイルを確認するよう依頼すると、いきなり複数のファイルを変更されることを避けやすくなります。

また、Issueに書かれていない機能まで実装しないよう、対象外の内容を明示します。Codexに推測で仕様を補ってほしくない場合は、「不明点は実装前に質問してください」と書いておくとよいかと思います。

実装後は、変更内容とテスト結果を確認します。OpenAIの公式サイトでも、Codexの利用方法として、変更を作成した後にチェックを実行し、差分を確認して出荷準備を行う流れが案内されています。詳しくはCodexの公式ドキュメントを参照してください。

commit、push、Pull Requestを行う

実装が完了したら、いきなりpushするのではなく、まずローカルの変更を確認します。

git status
git diff
git diff --check

git statusでは、変更されたファイルと未追跡ファイルを確認します。git diffでは、実際の変更内容を確認します。MarkdownやHTMLなどの日本語を含むファイルを変更した場合は、文字化けや表示崩れがないことも確認します。

git diff --checkでは、行末の余分な空白など、差分上の問題を確認できます。プロジェクトで決めているテスト、構文チェック、ビルドもこの段階で実行します。

確認が終わったら、次のいずれかの方法でcommitやpush、Pull Requestの作成を行います。

• CodexアプリのGit操作
• Visual Studio CodeのCodex拡張やGit機能
• Gitコマンド

git add path/to/changed-file
git commit -m "タスク登録機能を追加"
git push origin feature/task-create

git add .を使うと、意図していないファイルまでcommit対象になる可能性があります。実行前にgit statusで対象ファイルを確認します。

Pull Requestでは、Issueへのリンク、変更内容、確認したコマンド、既知の制約を記載します。GitHub公式のPull Requestクイックスタートでも、ブランチで変更を行い、commitとpushを行った後にPull Requestを作成し、レビューする流れが説明されています。

ChatGPTでコミットやPull Requestをレビューする

Pull Requestやコミットを作成したら、ChatGPTで変更内容をレビューします。レビューを依頼するときは、「問題がないか確認してください」だけではなく、確認してほしい観点を具体的に書きます。

GitHubのPull Request #456をレビューしてください。

次の観点を確認してください。
- Issueの完了条件を満たしているか
- 既存機能を壊していないか
- 認証ユーザー以外のデータへアクセスできないか
- 入力値の検証が不足していないか
- テストで確認できていないケースがないか
- 不要なファイル変更や秘密情報が含まれていないか

問題がある場合は、重要度、対象ファイル、理由、修正案を示してください。
問題がなければ、確認した範囲と残っている懸念を説明してください。

レビューで問題が見つかった場合は、その場で長い指示を追加するのではなく、Issueへのコメントや新しいIssueとして記録します。修正内容を小さく保ち、再度CodexへIssue単位で依頼できるようにするためです。

OpenAIの公式ユースケースにも、GitHubのPull Requestをレビューして、人によるレビューの前に問題を見つける使い方が掲載されています。ただし、AIによるレビューで問題がないと判断されても、人による確認を省略してよいという意味ではありません。

設計・実装・レビューのループを回す

実際の作業は、次のようなループになります。

1. ChatGPTで要件と設計を整理する
2. Markdownの設計書としてGitHubへ保存する
3. 設計を実装単位のIssueへ分割する
4. 通常のChatGPTからIssueを作成・補足する
5. CodexへIssue単位で実装を依頼する
6. テスト、構文チェック、ビルド、差分を確認する
7. Codexアプリ、VS Code拡張、またはGitコマンドでcommit・pushする
8. Pull Requestを作成し、ChatGPTや人がレビューする
9. 問題があればIssueへ戻して修正する

設計書と実装内容に差が出た場合は、実装だけを修正するのではなく、設計書も更新します。設計書が古いままだと、次のIssueやCodexへの指示が現在の実装と合わなくなるためです。

手戻りとトークン消費について

この分担を始めた理由の一つは、Codexのトークン消費を抑えたかったからです。

設計の壁打ち、要件の整理、実装単位への分解までCodexで行うと、その会話の分だけCodexのトークンを消費します。設計を通常のChatGPTで行い、Codexには決まったIssueを渡すようにすれば、少なくとも設計段階のチャットをCodex側へ持ち込まずに済みます。

ただし、トークン消費を抑えることだけを目的にすると、Issueや設計書の作成に時間がかかりすぎる可能性もあります。私の場合は、トークンの削減量を正確に計測しているわけではありません。先に設計することで、実装後に大きく作り直す手戻りが減ることの方が、実感しやすい効果だと感じています。

運用時の注意点

Issueを細かく分けすぎない

Issueを小さく分けると確認しやすくなりますが、細かくしすぎるとIssueの管理だけで時間がかかります。画面、データ、権限などが一つの目的にまとまっている場合は、無理に分割しない方がよい場合もあります。

設計書とIssueで同じ内容を重複させすぎない

設計書に全体の方針、Issueに今回の実装範囲と完了条件を書くように分けます。同じ内容を両方へ大量に書くと、後から片方だけ更新して情報がずれる原因になります。

秘密情報を連携先へ渡さない

GitHubのリポジトリやIssueをChatGPT、Codexから参照する場合は、APIキー、パスワード、秘密鍵、個人情報が含まれていないか確認します。公開用の設計書やIssueには、実在する認証情報を記載しません。

最終的な確認は人が行う

ChatGPTやCodexが設計、実装、レビューを支援しても、要件の判断や公開前の最終確認まで自動化できるとは限りません。変更されたファイル、テスト結果、Pull Requestの差分を確認してから、mergeや公開へ進みます。

まとめ

今回は、ChatGPT、GitHub、Codexを分担して、設計から実装、レビューまで進める流れを整理しました。

Codexへいきなりアプリの作成を依頼するのではなく、先にChatGPTで設計を壁打ちし、Markdownの設計書を作成します。その設計をGitHub Issueへ分割し、CodexへIssue単位で実装を依頼します。

実装後は、テストと差分を確認してから、Codexアプリ、VS Code拡張、またはGitコマンドでcommit、push、Pull Request作成を行います。問題が見つかった場合は、Issueへ戻して修正します。

この方法でトークン消費を抑えられる可能性はありますが、私が実際に効果を感じているのは、設計を先に行うことで手戻りが減る点です。最初から完璧な設計を作るのではなく、設計書とIssueを更新しながら、実装とレビューのループを回していくのがよいかと思います。