関連 issue: #81
作成日: 2026-07-09
ステータス: 設計検討用メモ
この文書は、track capability の実装案ではなく、実現したあとに Issue 全体をどう運用するかを想像しやすくするための CODEX 版の運用案である。
track capability は、作業の正解だけを残すための仕組みではなく、正解に至るまでの探索、試作、方針転換、やり直しを散らかさずに扱うための仕組みとする。
CODEX 版の運用では、親 Issue を「作業全体の台帳」、子 Issue を「探索や判断の単位」として扱う。
親 Issue には、現在の本線、全体の目的、採用済みの判断、次に見るべき track の一覧を集約する。子 Issue には、個別の試作、調査、仮説、やり直し、捨てた案、保留案を残す。
重要なのは、親 Issue を読めば現在地が分かり、子 Issue を読めば判断の理由が分かる状態にすることである。
親 Issue は、その作業全体の現在地を表す。
親 Issue に置くもの:
親 Issue には、細かい試行錯誤を全部書かない。親 Issue は読み返すための目次であり、現在地を短時間で復元するための場所とする。
子 Issue は、ひとつの探索単位を表す。
子 Issue に置くもの:
子 Issue は、最終的に採用されなくても価値がある。却下した理由、やり直した理由、途中成果物の退避先が残ることで、後続の Brain が同じ道をもう一度たどらずに済む。
track は、おおむね次の状態で運用する。
| 状態 | 意味 |
|---|---|
open |
まだ調査、試作、検討中 |
adopted |
親 Issue の本線に採用した |
discarded |
明示的に捨てた |
superseded |
後続 track に置き換えられた |
inconclusive |
判断に足る材料が出なかった |
paused |
今は触らないが、後で戻る可能性がある |
Gitea の Issue state は open / closed しかないため、track の状態はコメント、本文の決定欄、または label で表現する。運用上は、Butler が summary できるように、状態名を揺らさないことを優先する。
親 Issue は、作業のたびに大きく書き換える場所ではない。重要な節目で、現在地が分かる程度に更新する。
親 Issue の本文には、次のような固定セクションがあるとよい。
## 目的
## 現在の本線
## 採用済み track
## 却下 / 破棄した track
## 保留中の track
## 未検証の論点
## 次にすること
## 後続セッションへの引き継ぎ
親 Issue のコメントには、日々の細かい作業記録ではなく、判断が変わったタイミング、track が増えたタイミング、track が完了したタイミングを残す。
子 Issue は、track を開始した時点で作る。
開始時に最低限書くもの:
## track の目的
## 背景
## 仮説 / 確認したいこと
## 判断条件
## 想定成果物
作業中は、細かいコマンドログではなく、判断に影響する事実をコメントする。
完了時には、次を必ず残す。
## 結果
## 判断
## 判断理由
## 成果物
## 親 Issue へ反映する内容
## 次の出発点
ここで大事なのは、「何をしたか」よりも「何が分かったので、どう判断したか」である。
作業開始時は、まず親 Issue を読む。
親 Issue から次を確認する。
次に、着手対象の子 Issue を読む。子 Issue がまだ存在しない場合は、新しい track として子 Issue を作る。
作業中の細かい変更や実行結果は work_record に寄せる。
Issue コメントには、次のような判断材料だけを残す。
Issue コメントは日報ではなく、後続の判断者への道しるべとして使う。
作業終了時は、子 Issue に現在の判断を残す。
まだ結論が出ていない場合でも、次を残す。
track が完了した場合は、親 Issue に要約を反映する。
方針転換は、失敗扱いにしない。方針転換 track として明示的に残す。
方針転換時に残すもの:
親 Issue では、現在の本線を新方針へ更新する。旧方針は削除せず、却下または superseded な track として参照できるようにする。
やり直しは、特に明示的に扱う。
単に「前の作業をなかったことにする」のではなく、restart track として次を記録する。
やり直し時の親 Issue には、次のような短い宣言があるとよい。
現在の本線を track #X から track #Y に切り替える。
track #X の成果物のうち A と B は残し、C は破棄する。
切り替え理由は、D の制約により旧方針では完了条件を満たせないため。
これにより、後続セッションで「なぜここから再出発しているのか」が分かる。
work_record は、実際に作業した事実を保存する場所である。
Issue は、作業の意味と判断を保存する場所である。
CODEX 版では、次のように分担する。
| 保存先 | 主に残すもの |
|---|---|
work_record |
変更ファイル、実行した検証、作業単位の記録 |
| 子 Issue | track の目的、結果、判断理由 |
| 親 Issue | 全体の現在地、本線、track 一覧 |
| docs | 長い設計案、比較表、運用案、仕様メモ |
| handover | 次の Brain が再開するための短い引き継ぎ |
Issue コメントにすべてを書き込むと、親 Issue が読みにくくなる。長い検討は docs に置き、Issue からリンクする。
docs は、長い文章や比較検討を置く場所とする。
たとえば次のものは docs 向きである。
子 Issue には docs へのリンクと、そこから得た判断だけを書く。
Issue は索引、docs は本文、という分担にする。
handover は、次の Brain がすぐ再開するための短い圧縮情報とする。
handover に入れるもの:
handover に長い設計議論を入れない。長い内容は親 Issue、子 Issue、docs に残し、handover はそこへの導線にする。
コメントは、後から読んだときに判断が復元できる粒度にする。
残すべきコメント:
残さなくてよいコメント:
ただし、途中経過でも方針に影響するならコメントする。
track_summarize(parent_issue_id) のような capability がある場合、最終的に次のような一覧が見えると運用しやすい。
親 Issue #81: track capability の設計
現在の本線:
- Issue を主台帳、子 Issue を track 単位として扱う
採用:
- #82 運用モデル案: 親 Issue + 子 Issue 方式を採用
却下:
- #83 Gitea Project ボード方式: Gitea 1.25.5 に API がないため却下
置き換え:
- #84 実験専用 model 案 -> #85 汎用 track model 案に置き換え
保留:
- #86 label 設計: 実装時に再検討
次:
- #87 track_restart の運用詳細を詰める
この summary は、親 Issue を読む前の入口にも、handover の補助にも使える。
CODEX としては、track capability の初期運用は「親 Issue + 子 Issue + docs リンク」を基本形にするのがよいと考える。
理由は次の通り。
最初から複雑な内部台帳を作るより、Issue に見える形で運用を固める方がよい。track が人間にも見えることで、Butler がいない場面でも作業の意味が失われにくい。
track を増やしすぎると、親 Issue が目次として機能しなくなる。小さすぎる試行は work_record に任せ、判断単位になったものだけを track にする。
子 Issue は、作業ブランチのように乱立させるのではなく、「後から独立して読める判断単位」になったときに作る。
親 Issue は、常に最新の本線を指す。古い判断は消さず、採用、却下、置き換えとして位置づける。
この運用で目指すのは、後続の Brain や人間が次の問いにすぐ答えられる状態である。
track capability は、作業を増やすための管理機能ではなく、迷子にならないための地図として運用する。