CodexでPRを量産する前に、Issue・状態・判断ログをつなぐ「文脈ハブ」を作る

この記事は、自分の個人開発で試している Codex + GitHub Issue 駆動開発の全体像を、AIに整理してもらいながら下書きしています。この記事では、実体験、仮説、まだ未検証の運用案を分けて残します。

CodexやChatGPTを使うようになって、作業そのものはかなり速くなりました。

一方で、作業が速くなるほど「何を解くのか」「誰が決めるのか」「どこまで任せるのか」が曖昧なままだと、逆に迷いが増える場面もありました。

最近、自分の中では、AI時代に価値が上がるのは、何でも自分で処理する人ではなく、文脈を整理して、Issue、状態表、判断ログ、AIに渡せる形へ移していく人なのではないかと考えています。

この記事は、その考えをまとめる親記事です。

この記事の位置づけ

この記事では、個別のテクニックを深掘りするというより、Codexを使ったAI開発運用の全体地図を書きます。

個別の話は、子記事として分けています。

テーマ	子記事
作業単位	AIに「いい感じに直して」と頼むのをやめて、GitHub Issueを作業の正本にした
並列開発	CodexでPRを並列に作る前に、親Issueを制御面にしている話
状態管理	CodexにPRを並列で任せる前に見る、CODEX_STATUSという小さな表
見積もり	AIをプランニングポーカーの参加者にして、見積もりの論点をそろえる

自分の中では、この構造を「親Qiita / 子Qiita」のように捉えています。

親Qiita = 全体地図、思想、導線
子Qiita = 個別テーマの実践ログ、テンプレ、失敗談

GitHub Issueでいう親Issue / 子Issueに近いです。

親Issueが全体の目的、依存関係、進捗を持つように、親Qiitaではシリーズ全体の考え方と読む順番を置きます。

なぜ親Qiitaが必要だと思ったか

最初は、個別記事を書くだけで十分だと思っていました。

実際、最初に書いたのは「AIにいい感じに直してと頼むのをやめて、GitHub Issueを作業の正本にした」という記事です。

その後、Codexで複数PRを作るようになると、話題が少しずつ分かれていきました。

• Issueをどう書くか
• 親Issueでどう制御するか
• CODEX_STATUSでどう状態を見るか
• 見積もりの論点をAIとどうそろえるか
• どこで自分が判断するか
• どこから仕組みに移すか

個別記事としては書けます。

ただ、個別記事だけだと、あとから読んだ人には「これは何の一部なのか」が見えにくい。

そこで、シリーズ全体の入口として、親Qiitaを置いた方がよいと考えました。

Codexで作業は速くなる

Codexを使うと、実装、調査、修正、テスト追加、ドキュメント更新はかなり速くなります。

これは便利です。

ただ、自分が困ったのは「AIが遅いこと」ではありません。

むしろ、AIが速いことで、次のような問題が見えやすくなりました。

• どのIssueを先に進めるべきか分からない
• 並列にしてよいPRと、待つべきPRが混ざる
• 変更してよい範囲が曖昧なまま作業が進む
• contractや保存形式に関わる変更まで勢いで進みそうになる
• merge判断やrelease gateまでAIに流れそうになる
• あとから「なぜこの変更をしたのか」を追いにくい

つまり、作業速度が上がるほど、作業の前後にある文脈が重要になってきます。

自分が作りたいのは「文脈ハブ」

ここでいう文脈ハブは、人の役割名というより、Codexに渡す前提をまとめておく構造のことです。

自分の中では、次のように捉えています。

Issue、PR、判断、AI、ナレッジをつなぎ、次に進める状態を作る接続点

Codexに作業を渡す前に、次がそろっている状態です。

• 何を解くのか
• 何を解かないのか
• どこを変更してよいのか
• どこを変更してはいけないのか
• 何が通れば完了なのか
• どのIssueが先に必要なのか
• どのPRは並列にしてよいのか
• どこで自分の判断に戻すのか
• 判断ログはどこに残すのか

これを頭の中だけに置くと、AIに渡す前提も、あとから見返す自分の判断も揺れます。

だから、Issue、親Issue、CODEX_STATUS、PR本文、判断ログに少しずつ移していく。

これが、自分の中での「文脈ハブ」です。

頭の中の文脈を外に出す

個人開発では、自分の頭の中に文脈がたまりがちです。

たとえば、次のような判断です。

• このIssueは先にやる
• これはまだ実装しない
• これは調査だけで止める
• これはPRを作ってよいが、mergeは後で見る
• この変更は別Issueと衝突しそう
• この検証が通るまでは次へ進めない

自分だけで作業しているなら、頭の中で覚えていてもなんとかなることがあります。

ただ、Codexに作業を任せ始めると、それでは足りなくなりました。

AIに毎回長い説明を渡していると、会話ごとに前提が少しずつ揺れます。

そこで、頭の中にある判断を、できるだけIssueや状態表に移すようにしています。

頭の中にありがちな文脈	外に出す場所
何を解くか	GitHub Issue
何をやらないか	Out of scope
どれを先にやるか	親Issue
今進めてよいか	CODEX_STATUS
どこで止めるか	blocked / needs-human-review
何を検証したか	PR本文
なぜそう判断したか	判断ログ

これは、きれいな管理表を作りたいという話ではありません。

Codexに渡す前提を、毎回のチャットではなく、あとから見返せる場所に置くための工夫です。

抱える文脈と、渡せる文脈

自分の中では、文脈には2種類あります。

種類	例	扱い
抱える文脈	違和感、優先度の感覚、まだ言葉になっていない不安	まず自分で拾う
渡せる文脈	Goal、Scope、Done、Out of scope、blocked by、検証結果	Issueや表に移す

最初から全部を言語化するのは難しいです。

でも、Codexに任せる作業については、少なくとも「渡せる文脈」まで落としてから依頼した方が安定しました。

特に効いたのは、次の3つです。

• 変更してよい範囲を書く
• 今回やらないことを書く
• 進めてよい状態かを親IssueやCODEX_STATUSで確認する

このあたりが曖昧なままだと、Codexの出すPRは速くても、あとから見る自分の負荷が上がります。

文脈ハブを構成するもの

自分の個人開発では、文脈ハブを次のような要素で作っています。

要素	役割
GitHub Issue	何を解くかを固定する
Scope / Out of scope	変更してよい範囲、しない範囲を決める
親Issue	複数Issueの順序、依存、gateを見る
CODEX_STATUS	issue、state、blocked by、PR、notesを一覧化する
PR本文	何を変えたか、何を検証したか、親Issue更新案を残す
判断ログ	なぜそう決めたかをあとから追えるようにする
AIへの依頼文	作業前に状態判定させる

全部を最初から整える必要はありません。

自分も最初からこの形だったわけではありません。

最初は、Issueに Goal / Scope / Done / Out of scope を書くところから始めました。

そこから、親Issue、CODEX_STATUS、見積もり、判断ログへ少しずつ広げています。

読む順番

今から読むなら、次の順番が分かりやすいと思います。

順番	まず読むもの	何が分かるか
1	AIに「いい感じに直して」と頼むのをやめて、GitHub Issueを作業の正本にした	AIに渡す作業単位をチャットではなくIssueにする。Goal / Scope / Done / Out of scope でPRの境界を作る
2	CodexでPRを並列に作る前に、親Issueを制御面にしている話	複数Issueが同じ重さに見えないように、親Issueで critical path、parallel lane、blocked、human review を見る
3	CodexにPRを並列で任せる前に見る、CODEX_STATUSという小さな表	Codexに渡す前に、そのIssueが今進めてよい状態かを確認する。Blocked by、Blocks、Agent、PR、Notes を見る
4	AIをプランニングポーカーの参加者にして、見積もりの論点をそろえる	AIを意思決定者ではなく、見積もりの論点をそろえる参加者として使う

まだ書きたい子Qiita

今後は、次のような子記事を分けて書きたいです。

テーマ	書きたいこと
Out of scope	Codexに任せるIssueには、Doneより先にOut of scopeを書いた方がよかった
判断ログ	AIの提案を採用しなかった理由を、どこに残すか
merge gate	CodexがPRを作っても、merge判断はどこまで人間に残すか
文脈ハブ	AI時代に必要なのは「全部できる人」より、文脈を仕組みに移せる人だと思った
医療DXとの接続	できる人を増やすより、迷う人を減らす仕組みにする

親記事は更新していく

この親記事は、一度書いて終わりではなく、子記事が増えたら更新していくつもりです。

最初から全体像をきれいに作るというより、実際にCodexを使って困ったこと、試したこと、失敗したことを子記事に分けて書き、あとから親記事に戻していく形です。

そうすると、個別記事だけでは流れてしまう学びを、シリーズ全体の地図として残しやすくなります。

自分の中では、これはGitHub Issue運用にも近いです。

子Issueが増えたら親Issueに戻す。

子Qiitaが増えたら親Qiitaに戻す。

この形にしておくと、読者にも自分にも「今どこを読めばよいか」が見えやすくなると考えています。

注意点

この運用は、まだ自分の個人開発で試している段階です。

次のことは、まだ断定できません。

• どのチームでも同じように効くか
• 複数人開発でも同じように運用できるか
• GitHub Projectsやsub-issuesより優れているか
• 実際にレビュー時間が何%減ったか
• PRの手戻りがどれだけ減ったか

なので、この記事では「これが正解」とは書きません。

今のところ、自分の環境では、Codexに作業を任せる前に、Issue、状態、判断ログをつなぐ文脈ハブを作ると扱いやすいと感じています。

まとめ

Codexを使うと、作業そのものは速くなります。

ただ、作業が速くなるほど、何を解くのか、どこまで任せるのか、どこで止めるのかが重要になります。

そのために、自分は GitHub Issue、親Issue、CODEX_STATUS、PR本文、判断ログをつなぐ文脈ハブを作ろうとしています。

自分が頭の中で見ている文脈を、少しずつIssueや状態表に移す。

それが、Codexを使ったAI開発を安定させるうえで大事なのではないかと考えています。