CodexにPRを並列で任せる前に見る、CODEX_STATUSという小さな表

この記事は、自分の個人開発で試している Codex + GitHub Issue 駆動開発の運用メモです。前回は、複数Issueを扱うために親Issueを制御面にした話を書きました。今回は、その親Issueに置いている CODEX_STATUS と、parallel-safe / blocked / needs-human-review の分け方を書きます。

前提記事:

• CodexでPRを並列に作る前に、親Issueを制御面にしている話

Codexに複数Issueを渡すと、PR作成までは速い。

ただ、速くPRが出るほど、「それ、今進めてよいIssueだったのか？」を先に見ないと危ない。

自分はその確認に、親Issueへ置く小さな状態表を使っています。

この記事で扱うのは、Codexに作業を渡す直前の判断材料です。計測方法は別記事で分けます。

この記事で言いたいこと

A: labelを付ければ、AIも判断できるのでは？

B: labelは入口にはなる。ただ、blocked by、blocks、PR、notesまで見ないと、今進めてよいかは分からなかった。

Codexに並列でPRを作らせると、速く進むことがある。

ただし、並列化してはいけないIssueまで同時に進めると、contractや保存形式が壊れやすい。

自分は最近、親Issueに CODEX_STATUS という状態表を置いて、次を分けるようにしている。

• 先に閉じるべきcritical path
• 並列に進めてよいparallel-safe
• 実装せず止めるblocked
• merge判断を人間に残すneeds-human-review

CODEX_STATUS はGitHubの正式機能ではありません。自分の運用名です。親Issueの本文またはコメントに置く、AI作業用の状態表として使っています。

この記事の対象読者

• Codexに複数Issueを渡している人
• parallel-safe や blocked をlabelだけで判断して不安がある人
• PRを小さくしたいが、同じcontractに触る並列PRを避けたい人
• merge判断やrelease gateは人間側に残したい人

この記事で持ち帰れるもの

• 親Issueに置く CODEX_STATUS tableの最小形
• critical-path / parallel-safe / blocked / needs-human-review の分け方
• Codexに作業前確認させる依頼文テンプレ

CODEX_STATUSを置く

A: GitHub Projectsやsub-issuesで管理すればよいのでは？

B: それも選択肢だと思う。ただ、Codexに短く読ませるには、親Issue上の1つの表が扱いやすかった。

たとえば、こういう表を置きます。

| ID | Issue | Lane | State | Blocked by | Blocks | Agent | PR | Notes |
|---|---|---|---|---|---|---|---|---|
| P7-01 | stable node id contract | Contract | blocked | human review | P7-03, P7-04 | - | - | 保存形式未確定 |
| P7-02 | tester feedback template | Docs | parallel-safe | - | - | Codex | #123 | docs-only |
| P7-03 | map-aware diff | Core | todo | P7-01 | release gate | - | - | contract確定後 |

これは人間向けの進捗表でもありますが、Codexにとっても重要なコンテキストになります。

特に効いているのは Blocked by と Blocks です。

Issue一覧だけを見ると「全部open」に見えますが、CODEX_STATUSを見ると、どこで止めるべきかが分かります。

critical path / parallel-safe / blocked を分ける

AI並列開発で一番危ないのは「並列化してはいけないものまで並列化すること」だった。

そこで、Issueに次の意味を持たせるようにした。

label	付ける条件	Codexに許可すること
critical-path	後続Issueやrelease gateを直接ブロックする	優先対応。ただしscope外変更は禁止
parallel-safe	他Issueと書き込み範囲・contractが分離されている	小PRで並列実行可
blocked	先行Issue・設計判断・人間レビュー待ち	実装せず、調査・設計メモまで
needs-human-review	contract / release / security / data formatに触れる	PR作成まで。merge判断は人間
codex-active	Codexに作業委譲中	他agentとの重複防止

たとえば、次のような作業はcritical pathになりやすい。

• data format contract
• parser / serializer / validation / patch にまたがる変更
• release gate
• parent issue coordination
• human reviewが必要な設計判断
• testerが次に触る導線、選択状態、保存・復元、release前の主要操作

逆に、次のような作業はparallel-safeになりやすい。

• docs-only design note
• 表示文言、空状態、docsに近い軽微なUI polish
• i18n foundationの棚卸し
• tester feedback template
• export形式の調査

もちろん、実際にはIssue本文を読む必要がある。

labelだけで完全判断はしない。

ただ、labelがあるだけでCodexに渡す初期判断がかなり安定する。

Codexに渡す依頼文

A: 毎回こんな依頼を書くのは面倒では？

B: 面倒ではある。ただ、contractやrelease gateに触るIssueで進みすぎるよりは安いと感じている。

IssueをAIに渡すとき、最近は単に「このIssueを実装して」ではなく、こういう依頼にしている。

Parent issueを確認してください。

1. CODEX_STATUSを読んで、今回のIssueが critical-path / parallel-safe / blocked / needs-human-review のどれか判定してください。
2. downstream contract、保存形式、API、schema、release gateに触れる場合は、実装前に停止条件を明示してください。
3. 変更してよい範囲 / 変更してはいけない範囲をIssue本文から抽出してください。
4. PRは小さく作り、Doneに検証コマンドと影響範囲を残してください。
5. 親IssueのCODEX_STATUS更新案をPR本文に書いてください。

この依頼文を入れておくと、少なくともIssue単体だけを見て進みすぎるリスクを下げやすい。

ポイントは「作業を始める前に、作業してよい状態かを判定させる」ことです。

並列化してよいIssue、してはいけないIssue

Codexに並列で進めさせるときは、書き込み範囲を分ける。

悪い例。

Issue A: parserを変える
Issue B: serializerを変える
Issue C: validationを変える

この3つは同じcontractに触っている可能性が高いので、並列にすると危ない。

よい例。

Issue A: i18n dictionaryとpackage.nlsを追加する
Issue B: tester feedback templateをdocsに追加する
Issue C: export形式の調査表をdocsに追加する

書き込み範囲と契約面が分かれていれば、並列にしやすい。

merge判断は人間側に残す

CodexがPRを作れるようになると、mergeまで自動化したくなる。

でも、今の運用では次のものは人間判断を残す。

• needs-human-review が付いているcontract変更
• stable IDのような保存形式変更
• release tag / public release
• billing/spending limitなど環境由来failureを含むCI判断
• parent issueのcritical path更新

AIに任せるのは、作業と検証の高速化。

どのcontractを採用するか、どのrelease gateを通すかは、まだ人間が見る。

小さく始めるテンプレート

いきなり大きな運用にしなくてもよい。

最初は親Issueにこの表だけ置けば十分だと思う。

| ID | Issue | Lane | State | Blocked by | Blocks | Agent | PR | Notes |
|---|---|---|---|---|---|---|---|---|
| issue-a | Contract | blocked | human review | issue-c issue-d | - | - | human review待ち |
| issue-b | Docs | parallel-safe | - | - | Codex | pr-b | docs-only |
| issue-c | UI | todo | issue-a | release gate | - | - | issue-a後 |

そして、Issueには最低限このlabelを付ける。

critical-path
parallel-safe
blocked
needs-human-review
codex-active

これだけでも、AIに渡すときの判断材料が増える。

失敗しやすいところ

labelだけを信じる

labelは入口であって、判断そのものではない。

Issue本文、親Issue、関連PR、CODEX_STATUSを読む必要がある。

CODEX_STATUSが古くなる

親Issueの状態が古いと、Codexが古い前提で動く。

そのため、PR本文に「親IssueのCODEX_STATUS更新案」を書かせるようにしている。親Issueを直接編集させるより、review時に反映漏れを見つけやすい。

critical pathを増やしすぎる

全部をcritical pathにすると、何も並列化できなくなる。

本当に downstream を止めるものだけに絞る。

並列PRが同じcontractに触る

parser / serializer / validation / patch のような横断契約は、並列化しにくい。

ここはdeep + review扱いにする。

まとめ

Codexに並列で作業させる前に、Issueを critical-path / parallel-safe / blocked / needs-human-review に分けておくと、進めてよい作業と止めるべき作業を分離しやすい。

大事なのは、labelを付けること自体ではありません。

親IssueのCODEX_STATUS、Issue本文、関連PRを読ませたうえで、Codexに「この作業は今進めてよいのか」を先に判定させることです。

最初から完璧な運用にしなくてもよい。

まずは、CodexにIssueを渡す前に次の3つだけ確認させるだけでも、かなり事故を減らしやすくなる。

このIssueは何にblockedされているか
このIssueは何をblocksしているか
このPR後に親Issueへ何を戻すべきか

続編

この記事では、Codexに渡す前の状態表と依頼文を書きました。

続編では、この運用が効いているかを「何倍速くなった」ではなく、制御品質としてどう測るかを書きます。

未検証

• CODEX_STATUS更新をどこまで自動化できるか
• GitHub Projectsやsub-issuesとの使い分け
• 複数人チームで同じ表を保守できるか