AI maintainer 用 WorkItem / Thread 抽象メモ

位置づけ

AI maintainer が単なる coding agent ではなく、作業の発見・分解・実装委譲・review・完了判断まで扱うには、現在の TODO.md / tickets/*.md だけでは足りない。必要なのは、個々の file path ではなく「作業単位」と「その会話・判断・成果物」を扱う抽象である。

このメモは実装 ticket ではなく、将来こういうものが必要になるという設計メモとして置く。具体的な最初の実装は tickets.sh / work-items/ の MVP で試す。

必要になりそうな概念

WorkItem
- 作業単位。title / status / kind / priority / labels / acceptance criteria / links を持つ。
Thread
- WorkItem に紐づく append-only な会話・判断・review・実装報告の流れ。
Event
- comment / plan / decision / implementation_report / review / status_change など。
Artifact
- review log、test log、設計メモ、branch / commit / worktree への link など。
Lease / Run
- どの Pod / agent がどの worktree / scope で作業中かを表す runtime coordination 情報。

配置の分担

repo-managed な project-visible 領域には、作業の正本として人間が読める coordination data を置く。

repo/
  work-items/   # WorkItem / Thread / Artifact
  tickets/      # 当面の既存 ticket。将来 WorkItem view に寄せる候補
  docs/         # plan / report

.insomnia は local runtime state として扱い、project coordination の正本にはしない。

.insomnia/
  memory/
  workflow/
  maintainer/
    leases/
    runs/
    inbox/

ID と backend の考え方

WorkItem ID は中央 SEQUENCE にしない。複数 branch / worktree / Pod が同時に作業を作ると conflict しやすいため、timestamp + slug などの衝突しにくい ID にする。

YYYYMMDD-HHMMSS-<slug>
YYYYMMDD-HHMMSS-<short-rand>-<slug>

backend は最初は repo 内 file backend でよいが、抽象としては Git directory 固定にしない。将来、remote maintainer hub や GitHub Issues などへ移る可能性を潰さない。

移行イメージ

既存の TODO.md / tickets/ 運用は維持する。
tickets.sh MVP で work-items/ の file backend と thread 操作を試す。
既存 TODO.md / tickets/ を手動で work-items/ に寄せ、doctor が通る状態にする。
その運用が安定したら、TODO.md を generated view にするか、廃止するかを判断する。
必要になった段階で Rust crate / Store interface / LeaseStore / remote backend を検討する。

当面やらないこと

remote maintainer hub の実装。
SQLite / index / search daemon の導入。
Pod lifecycle / completion tracking の完全実装。
LeaseStore の本格実装。
TUI 統合。

参照

tickets/tickets-sh-workitem-thread-mvp.md
docs/plan/ai-maintainer.md
tickets/auto-maintain-workflow.md

3.0 KiB Raw Blame History