この文書は、実験を繰り返しながら P1、P2、P3 を順に進めるための日常運用を定義します。
各段階の目標と完了条件は project-plan.md、全体の目的と着手順は Home.md を正本とします。
進捗と判断経路の管理には Butler の Track Ledger を使います。採用した結論だけでなく、試した案、結果、却下理由、未検証事項、次の出発点を Gitea Issue 上に残します。
work_record、判断の文脈は track_record、長い安定情報は docs/ に分けるneeds-review とする| 段階 | 親 Issue | 着手条件 |
|---|---|---|
| P1: PCでのデータ読み取りと位置確認 | Gitea Issue #1 | 最初に着手する |
| P2: 地図表示プロトタイプ | Gitea Issue #2 | P1の出力形式と誤差傾向を説明できる |
| P3: Androidタブレット対応 | Gitea Issue #3 | P2の主要構成と地図表示方式を評価できる |
原則として前段の完了条件を確認してから次段へ進みます。ただし、後段の判断に必要な前提調査だけを先に行う場合は、その理由と依存関係を track に明記します。
親 Issue を初めて使うときは、次の順で Track Ledger 化します。
work_start(issue_id=...) で作業中の親 Issue を default issue にするtrack_update_parent(parent_issue_id=..., mode="preview") で本文案を確認するtrack_update_parent(parent_issue_id=..., mode="sync") で反映するtrack_summarize() と track_check() で初期状態を確認するparent_issue_id は default issue 設定後も明記し、別の親 Issue を誤更新しないようにします。
Track Ledger 初期化前からある Issue 本文の「状態: 予定／調査中／試作中／確認済み／改善中」は移行用の旧表示として扱い、初期化後は Track Ledger の「現在の本線」と track の状態を進捗の正本にします。旧表示を並行更新して二重管理せず、既存本文を整理する機会に削除します。CLAUDE.md と記述が競合する場合は、Track Ledger を使う P1、P2、P3 Issue についてはこの文書の運用を優先します。
Track Ledger 用ラベルは track_ensure_labels() で管理し、独自の kind:experiment ラベルなどで同じ意味を重複管理しません。既存の project:P1、project:P2、project:P3 ラベルは、親 Issue がどの段階に属するかを検索するため維持します。子 track の分類と状態には track/* ラベルを使います。ラベルは補助であり、Issue 本文内の Track Ledger metadata を正本とします。
次のように、複数の判断経路や再検証の価値がある作業は track にします。
一方、判断を伴わない小さな修正、単なるコマンド実行、通常のテスト結果は track を増やさず work_record に残します。
track の kind は目的に応じて使い分けます。
| kind | 用途 |
|---|---|
exploration |
仕様、制約、接続方法、選択肢の探索 |
experiment |
仮説や測定条件の検証 |
prototype |
確認ツールやアプリの試作 |
comparison |
保存形式、技術、地図ソースなどの比較 |
baseline-check |
後続判断の前提となる事実の確定 |
pivot |
方針転換 |
restart |
一部を残して作り直す作業 |
作り直しには通常の track_start(kind="restart") ではなく track_restart() を使い、残す成果物、捨てる成果物、理由、次の出発点を明記します。
実験 track を開始するときは、少なくとも次を定めます。
作業中の判断材料は track_record() に残します。record_type は内容に応じて progress、review、decision、risk、artifact、question を使い分けます。
実験を終えるときは track_finish() で結論と理由を記録します。
| outcome | このプロジェクトでの扱い |
|---|---|
adopted |
親 Issue の現在の本線に採用する |
discarded |
理由を明記して採用しない |
superseded |
後続 track に置き換える。relation も明記する |
inconclusive |
結論に必要な結果が得られなかった |
baseline |
後続作業の前提となる事実を確定した |
needs-review |
ユーザーや実機担当者の判断・確認を待つ |
adopted にした場合は、track_update_parent(mode="preview") で親 Issue の「現在の本線」の更新案を確認してから sync します。
| 記録先 | 残す内容 |
|---|---|
| 親 Issue | 目的、現在の本線、track一覧、relation、未検証事項、次の行動 |
子 Issue / track_record |
仮説、実験条件、判断材料、レビュー、リスク、結論と理由 |
docs/ |
長い設計、比較表、再利用する手順、確定した安定情報 |
work_record |
変更ファイル、実際に行った変更、テスト・検証結果 |
| handover | 次の AI セッションが再開するための短い引き継ぎ |
同じ内容を track と work_record に重複させません。保存先に迷う場合は、書き込む前に track_capture() で候補を確認します。
| 置き場所 | 何を置くか | Git管理 |
|---|---|---|
docs/ |
確定した方針、計画、比較資料、手順、運用ルール | する |
apps/ |
PC、Web、Androidなど利用者向けのアプリ本体 | する |
tools/ |
受信確認、解析、変換などの補助ツール | する |
samples/ |
再現用の小さなサンプルログ、匿名化済みデータ | する |
artifacts/ |
生データ、長時間ログ、ビルド成果物、検証中の出力 | しない |
tmp/ |
一時作業用ファイル | しない |
apps/ と tools/ は必要になった段階で作るartifacts/ に保存し、再配布できる最小サンプルだけを samples/ に移すdocs/decisions/ には確定した技術選定、docs/procedures/ には再利用する接続・計測・復旧手順を置く配置先の基準名は次のとおりです。実装方式が決まって別の構成が適切になった場合は、該当 track に理由を記録して変更します。
docs/
decisions/
procedures/
apps/
pc-viewer/
map-prototype/
android-tablet/
tools/
capture/
parse/
convert/
samples/
artifacts/
raw-logs/
test-runs/
builds/
まだ使わないディレクトリは作らず、track の成果物として必要になった時点で追加します。
work_session_start(project_root) を呼ぶwork_observe() で変更、active issue、required_action を確認するwork_start() で選び、track_summarize() で現在地を確認するtrack_start()、通常作業なら既存 track または親 Issue の文脈で開始するtrack_record()、作業事実は work_record()、安定情報は docs/ に残すtrack_finish() で outcome、decision、reason を記録するtrack_summarize() と track_check() で整合性を確認するwork_publish() で公開するButler の各返値にある warnings、required_action、next_actions は必ず確認し、必要な後続操作を行います。
Gitea Project ボードは Track Ledger の正本ではありません。現在の Gitea では Butler から Project を操作する REST API が利用できないため、自動運用の必須要件から外します。
project_capability_check() を実行する各 P の完了判定は project-plan.md の完了条件で行います。
track_check() の warning を解消または明示的に引き継ぐP1 から P2、P2 から P3 への依存関係は、必要に応じて derives_from や references の relation で明示します。
最初に進めるのは P1（Issue #1）です。P1 を Track Ledger の親 Issue として初期化した後、次の作業を個別の track として順に進めます。