← 기사 목록
日本語https://qiita.com/tags/ai/feed

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

원문 사이트로 이동 ↗

추출된 키워드

32개
GitHub Issue·5親Issue·5Codex·5PR·4critical path·4parallel lane·4Issue駆動開発·4release gate·3blocked·3deferred·3done·3human review·3CODEX_STATUS·3contract変更·3GitHub Copilot coding agent·3Claude Code·3stable node id contract·2webview protocol·2grammar / parser contract整理·2completion evidence matrix·2runbook整備·2map-aware diff·2export品質·2tester feedback·2i18n foundation·2host adapter設計·2parser contract·2Obsidian Plugin·2Desktop·2VS Code拡張·2GitHub sub-issues·1Projects·1

원문

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

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

この記事は、自分の個人開発で試している Codex + GitHub Issue 駆動開発の運用メモです。AIにIssueを渡すだけでは複数Issueの順序や依存関係が崩れやすくなったため、親Issueを制御面として使うようにした話を書きます。実体験と、まだ未検証の運用仮説を分けて残します。

前回の記事: AIに「いい感じに直して」と頼むのをやめて、GitHub Issueを作業の正本にした

Codexで小さなPRを複数作るようになると、最初に困ったのは「作業できるIssueが多いこと」ではなく、「どれを先に進めてよいか分からないこと」だった。

Issue単体にはGoalやScopeを書いている。それでも、複数Issueが絡むと、contract変更、docs整備、tester feedback、release gateが同じ一覧に並んで見える。

そこで最近は、親Issueをただのまとめではなく、AI作業の制御面として使っている。

この記事で扱うのは、親Issue、critical path、parallel laneの考え方です。CODEX_STATUSの詳しい表やCodexへの依頼文テンプレは続編で分けて書きます。

この記事で言いたいこと

A: IssueにGoalとScopeを書いていれば十分では？

B: 単発Issueならかなり効く。ただ、複数Issueが同時に動き始めると、それだけでは順序と依存が見えなくなった。

AIにIssueを渡すだけだと、単発作業は進む。

でも、開発が少し大きくなると、次の問題が出てきた。

  • どのIssueが先に終わらないといけないのか分からない
  • 並列に進めてよいIssueと、待つべきIssueが混ざる
  • Codexが別々のPRを作ると、親Issue側の進捗が追いにくい
  • contract変更やrelease gateのように、人間レビューが必要なものまで勢いで進みそうになる

そこで、今はGitHub Issueをただのタスクではなく、開発グラフとして扱っている。

自分の運用では、親Issueに次を置く。

  • critical path
  • parallel lane
  • blocked / deferred / done の状態
  • 担当agentやPR
  • merge前に必要なgate
  • 次の並列wave

Issue駆動開発というより、Issueを制御面にしたCodex並列開発に近い。

この記事の対象読者

  • Codex / Claude Code / GitHub Copilot coding agent などでPRを作っている人
  • GitHub Issueを使っているが、複数Issueが絡むと優先順位が崩れる人
  • 小さなPRを並列に進めたいが、どこで止めるべきか迷う人
  • 親Issueやlabelを、AI開発の判断材料として使いたい人

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

  • 親Issueを「作業一覧」ではなく「制御面」として使う考え方
  • critical path / parallel lane / blocked を分ける最小パターン
  • Codexに進めさせるIssueと、人間レビューに戻すIssueの分け方

この記事の前提

種類内容
実体験private repo で GitHub Issue を作業単位にし、Codexで複数PRを進めている
発展点Issue単体ではなく、親Issueにcritical pathと並列レーンを持たせている
実測ではないこと生産性が何倍になった、レビュー時間が何%減った、という定量効果はまだ測っていない
未検証他チーム・複数人開発・大規模OSSで同じ運用が効くか

なぜIssue単体では足りなかったか

A: Issueを細かくすれば、並列に進めやすくなるのでは？

B: 細かくするだけだと、全部が同じ重さに見える。問題は粒度だけでなく、どれが後続を止めているかだった。

前の段階では、AIに「いい感じに直して」と頼むのをやめて、GitHub Issueを作業の正本にすることを重視していた。

Issueには最低限これを書く。

Goal
Scope
Done
Out of scope

これは今でも有効です。

単発Issueなら、この形だけでもかなり進めやすいです。

ただ、VS Code拡張、Desktop、Obsidian Plugin、parser contract、release gateのように複数レーンが絡み始めると、Issue単体では足りなくなってきた。

複数Issueを並べると、全部が同じ重さに見えます。

でも実際には違います。

たとえば、次のようなIssueが同じ一覧に並ぶ。

  • stable node id contract
  • Obsidian Plugin PoC
  • host adapter設計
  • i18n foundation
  • tester feedback
  • release gate
  • export品質
  • map-aware diff

このとき、AIに「open issueを進めて」と渡すだけでは危ない。

先にcontractを決めないと進めてはいけないIssueもあれば、並列に進めてよいdocs/design issueもある。

小さな実例: 親Issueでphaseを制御する

抽象論だけだと分かりにくいので、private repoで実際に使っているIssueを、公開できる粒度まで匿名化するとこうなります。

種類実例何をしたか扱い
critical pathtester feedback後のUI gatetoolbar表示、選択位置のreveal、zoom操作のような、次のtester確認を直接ブロックするUX不具合を直した後続確認の前に先に閉じた
parallel-saferelease evidence / runbook整備tester配布手順、human review用decision packet、completion evidence matrixをdocsとして整理したproduct code本流と衝突しにくいので並列に進めた
deep + reviewgrammar / parser contract整理parserとvalidationで使う分類を単一ソース化したparallel-safeに見えてもcontractに近いため、review境界を強く意識した
blocked / deferredstable node id contractMarkdown内にnode idをどう保存するかを検討したparser / serializer / patch / validationにまたがるため、実装前にhuman review待ちにした

この表で伝えたいのは、

critical-path
が付いたIssueだけが重要なわけではない、という点です。

release evidenceやrunbookのようなdocs/evidence系は、product codeを直接変えないので並列に進めやすい。Codexに任せるには相性が良い。

一方で、stable node id contract のような作業は、表面上は「ID保存形式を決めるだけ」に見えるが、実際には parser、serializer、validation、patch、webview protocol に影響する。こういうIssueは、勢いで実装に入るより、まずcontract boundaryを切り出してreview待ちにした方が安全だった。

また、tester feedback後のUX修正は、ユーザーが次に触る体験を直接ブロックするため、critical pathとして扱った。全部を並列にするのではなく、先に閉じるべきものを親Issue側で明示する。

自分の運用では、このようにIssueを次の3種類に分けている。

今すぐ閉じるべきcritical path
並列に進められるdocs / evidence / polish
reviewなしで進めすぎてはいけないcontract変更

親Issueを制御面にする

A: 親Issueは進捗メモとして使えばよいのでは？

B: 最初はそれで十分だった。ただ、Codexに作業を渡すなら「次に何をしてよいか」を読める形にした方が安定した。

自分のprivate repoでは、親Issueに phase 全体の状態を書いています。

たとえば、親Issueにはこういう情報を置きます。

P7-01 -> P7-06

これは「P7-01からP7-06へ進める」というcritical pathを表しています。

さらに、並列レーンも持たせます。

Import/Export: P7-01, P7-03
Integrations: P7-02
Map Semantics: P7-04
Templates: P7-05
Gate: P7-06

この形にすると、Codexに渡すときも「どのIssueをやるか」だけでなく、「どのIssueは並列でよいか」「どれはgateか」を判断しやすくなる。

図にすると、流れはだいたいこうなります。

重要なのは、子Issueを全部同じ扱いにしない点です。

親Issueは「作業一覧」ではなく、どの子Issueを先に進めるか、どれを並列にしてよいか、どこで人間判断に戻すかを示す制御面として使います。

この分け方で良くなったこと

1. AIに渡す文脈が短くなる

親Issueに状態がまとまっているので、毎回長い説明をしなくてよい。

2. 並列化してよいものが見える

docs、evidence、軽微なpolishのように本流のcontractに触らないものを見つけやすい。

3. 止めるべき場所が見える

blockedやneeds-human-reviewがあると、AIが進めすぎるのを防ぎやすい。

4. PRが小さくなりやすい

Issue単位でScopeが決まるので、PRの範囲も小さくしやすい。

失敗しやすいところ

critical pathを増やしすぎる

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

critical pathは「重要なIssue」ではなく、「滑ると後続Issueやrelease gateが止まるIssue」として扱う。

親Issueが古くなる

親Issueは便利ですが、更新されなければ逆に危険になります。

PR本文に「親Issueの更新案」を書かせるようにしておくと、review時に反映漏れを見つけやすい。

labelだけで判断する

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

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

まとめ

AI開発でIssueを使うだけなら、単発作業は進めやすくなる。

でも、複数Issueが絡む開発では、Issueを作業単位としてだけでなく、依存関係と並列化の制御面として扱う必要が出てきた。

今の自分の運用では、親Issueにcritical pathとparallel laneを置き、Codexにはその状態を読ませてから作業させている。

これはまだ完成された方法論ではない。

ただ、AIに「Issueを渡す」段階から、「Issue graphを読ませて並列開発する」段階へ進んできた感覚がある。

まず小さく試すなら、親Issueに次の3行だけ置くところからでよいと思う。

critical path: 先に閉じないと後続が止まるIssue
parallel lane: docs/evidenceなど、並列に進めやすいIssue
blocked: contractや保存形式が未確定で止めるIssue

続編

この記事では、親Issueを制御面にする考え方を書きました。

続編では、親Issueに置く状態表 

CODEX_STATUS
と、Codexに渡す依頼文テンプレを書きます。

未検証

  • この運用でPR lead timeがどれだけ短くなるか
  • review負荷が下がるか
  • 複数人チームでも成立するか
  • GitHub sub-issuesやProjectsとの使い分け