Hare/yoi
1
1
Fork 0
Code Actions Packages Releases Activity

docs: split maintainer workflows by role

Browse Source
This commit is contained in:
Keisuke Hirata 2026-05-24 07:34:30 +09:00
parent 3ae145269c
commit a9a2b1e034
5 changed files with 324 additions and 162 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

233
.insomnia/workflow/auto-maintain.md
View File

@ -1,148 +1,143 @@
--- ---
description: TODO.md と tickets/ から半自動で実装候補を選び、worktree・実装 Pod・reviewer・人間確認を使い分けて完了候補まで進める description: TODO / tickets / docs / git history から次の作業候補を見繕い、課題発見や方針決定を半自動でイテレーションする WIP maintainer workflow
model_invokation: false model_invokation: false
user_invocable: true user_invocable: true
requires: [] requires: []
--- ---
# Auto Maintain Workflow # Auto Maintain Workflow (WIP)
半自動 maintainer として、`TODO.md` と `tickets/` を俯瞰し、実装できる作業を選び、必要に応じて worktree / 実装 Pod / reviewer Pod を orchestration する。最終判断、git commit / merge / push、ticket 完了削除は人間に戻す。 insomnia を AI maintainer として運用するための半自動 loop。TODO / tickets から「今進められそうな作業」を選ぶだけでなく、課題の発見、設計判断の切り分け、次に人間へ戻すべき問いの整理までを扱う。
この Workflow は常駐 scheduler ではない。ユーザーが `/auto-maintain` を明示的に呼んだ時だけ動く。 これは unattended 自動開発ではない。実装の並列委譲は `multi-agent-workflow`、worktree の機械的作成は `worktree-workflow` に任せる。本 Workflow はその前段として、何を進めるべきか、何をまだ決めるべきかを整理する。
この Workflow は親 Pod / orchestrator 専用である。実装 Pod に `/auto-maintain` を渡してはならない。実装 Pod には、親 Pod が選んだ ticket、既に用意した child worktree、許可された write scope、禁止事項を具体的に渡す。 参照:
## 基本方針 - `docs/plan/ai-maintainer.md`
- `tickets/auto-maintain-workflow.md`
- main workspace は制御面として扱う。 ## 位置づけ
- `.insomnia/`
- maintainer inbox / trial log
- 実装差分は原則 child git worktree に隔離する。
- child worktree には `.insomnia` を置かない。必要なら `/worktree-workflow` の手順に従い sparse checkout で `.insomnia` を除外する。
- 実装 Pod と reviewer Pod は原則分ける。ただし scope 衝突や作業粒度により、親 Pod が review してよい。
- review artifact や完了候補の記録は main workspace 側に置き、実装 Pod には書かせない。
- git commit / merge / push / ticket 完了削除は行わず、人間へ完了候補として報告する。
## 事前調査 AI maintainer の目的は、コードを書くこと自体ではなく、プロジェクト状態を前に進めることである。
最初に以下を読む。 この Workflow は WIP として、以下を行う。
- TODO / tickets / docs / git history を読んで現在地を把握する。
- 実装可能な ticket と、方針決定が必要な ticket を分ける。
- 小さく実装できる候補を提案する。
- 設計相談が必要な論点を人間に戻す。
- 運用上の問題や繰り返し発生する詰まりを report / ticket / workflow 改訂候補として整理する。
## 非目標
現時点では以下をしない。
- 常駐 scheduler として自動実行する。
- 人間の合意なしに新規 ticket を作る。
- 人間の合意なしに既存 ticket を大幅変更する。
- 人間の合意なしに ticket 完了削除を行う。
- push する。
- Workflow を自律生成・自律改訂する。
- scope / permission / history persistence / prompt context 加工原則に関わる判断を勝手に決める。
## 入力として読むもの
必要に応じて以下を読む。
1. `TODO.md` 1. `TODO.md`
2. 対象候補の `tickets/*.md` 2. `tickets/*.md`
3. 関連 docs / report 3. `docs/plan/`
4. 既存 review file があれば `tickets/*.review.md` 4. `docs/report/`
5. `git log --oneline` / ticket file の git history
6. 既存 worktree / branch 状態
7. 最近の失敗や通知、ユーザーからの観測
TODO と tickets の不整合を見つけた場合は、勝手に ticket を作成・削除せず、人間へ報告する。 TODO と ticket の不整合を見つけたら、勝手に修正せず、まず報告する。ただしユーザーが明示的に「直して」と言った場合は Mode 1 として整理してよい。
## 着手候補の選び方 ## 分類
優先する作業: 候補を以下に分ける。
- ticket の要件と完了条件が具体的 ### A. 実装委譲可能
- 影響範囲が限定的
- build / test で確認しやすい
- scope / permission / history 永続化 / prompt context 加工原則に触れない
- narrow write scope を切りやすい
初回試走や小さな運用確認では、TUI 表示改善など局所的な ticket を優先する。 - 要件と完了条件が具体的。
- 影響範囲が限定的。
- test / build で確認できる。
- 大きな設計判断が不要。
- scope を狭く切れる。
避ける、または人間確認してから進める作業: この場合は、人間に候補として提示する。人間が実行を許可したら `$user/multi-agent-workflow` に進む。
- 複数の設計方針が自然に導け、将来構造に影響する ### B. 方針決定が必要
- permission / scope / Pod lifecycle / history persistence / prompt context 加工原則に触れる
- manifest cascade や protocol wire を広く変える - 複数の設計方針が自然に導ける。
- test 不能または再現不能 - protocol / permission / scope / persistence / prompt context に触れる。
- ticket 自体の大幅な要件変更が必要 - UX の仕様が未確定。
- 既存 ticket の要件が古い。
この場合は、実装せず、決めるべき問いを短く提示する。
### C. ticket 整理が必要
- TODO にあるが ticket がない。
- ticket があるが TODO にない。
- 完了済みに見えるが残っている。
- ticket の前提が変わっている。
この場合は、不整合と修正案を提示する。修正は人間の許可後に行う。
### D. report / workflow 改善候補
- 同じ tool 問題が繰り返し出る。
- Workflow の指示が曖昧で実装 Pod が迷った。
- AI が過剰に Task tool を使うなど、運用上の癖が出た。
- 通知や Pod completion tracking など、開発基盤の不足が観測された。
この場合は、すぐ ticket 化するか、`docs/report/` に観測として残すか、人間に確認する。
## 半自動 iteration
1. 状態把握
- TODO / tickets / git status を読む。
- 最近完了した流れや未完了 branch を確認する。
2. 候補抽出
- 実装可能そうな ticket を 2〜5 件挙げる。
- correctness / developer experience / user-visible UX / cleanup で分類する。
3. 推奨順位
- blocking correctness を最優先。
- 実害が出ている運用問題を次点。
- 小さく完了できる UX / cleanup を次点。
- 大きな設計変更は方針相談に回す。
4. 人間への提示
- 「次に進めるなら X」を1つ推奨する。
- 理由を短く述べる。
- 実装委譲する場合の scope / test 方針を添える。
5. 実行への接続
- 人間が「進めて」と言ったら `$user/multi-agent-workflow` に接続する。
- worktree 作成は `$user/worktree-workflow` に従う。
## エスカレーション基準 ## エスカレーション基準
以下では作業を止めて人間へ確認する。 以下では実装に進まず、人間へ戻す。
- ticket の要件から複数の設計方針が自然に導ける - ticket の要件から複数の設計方針が自然に導ける。
- scope / permission / history 永続化 / prompt context 加工原則など安全モデルに触れる - 長期構造、crate boundary、protocol、permission、scope、history persistence に触れる。
- 新 ticket 追加、既存 ticket の大幅変更、ticket 完了削除が必要 - prompt context 加工原則に関わる。
- git commit / merge / push / branch cleanup などの git 書き込み操作が必要 - 新 ticket の作成、既存 ticket の大幅変更、ticket 完了削除について合意がない。
- `git worktree add` など、作業ツリー作成の許可が明示されていない - test 不能、再現不能、または作業範囲外の不具合に遭遇した。
- テスト不能、再現不能、作業範囲外の不具合に遭遇した - WorkItem / Thread / Lease / maintainer state など、まだ設計中の概念が必要になる。
- child worktree に `.insomnia` が出てしまった
## Worktree 作成
実装差分を隔離する必要がある場合、親 Pod が `/worktree-workflow` の手順を使う。実装 Pod に worktree 作成を任せてはならない。要点は以下。 ## まだ固定しないもの
```bash 以下は `docs/plan/ai-maintainer.md` の上位設計に残し、本 Workflow では詳細を固定しない。
git worktree add .worktree/<task-name> -b <task-name>
git -C .worktree/<task-name> sparse-checkout init --no-cone - WorkItemStore / LeaseStore。
git -C .worktree/<task-name> sparse-checkout set --no-cone \ - operation inbox / trial log。
'/*' \ - QA feedback を ticket / review / report のどれに落とすか。
'!/.insomnia/' \ - AI 自身の feedback を Knowledge / report / ticket / workflow 改訂のどれにするか。
'!/.insomnia/**' - maintainer doctor。
``` - reviewer Pod の評価基準の機械化。
`git worktree add` は git 書き込み操作なので、ユーザーが明示的に許可していない場合は実行前に確認する。
## 実装 Pod の spawn
実装 Pod を使う場合は、対象 ticket、既に作成済みの child worktree path、write scope、禁止事項を明示する。実装 Pod は `/auto-maintain` や `/worktree-workflow` を実行せず、与えられた worktree 内で実装・確認・報告だけを行う。
推奨 scope:
- read: main workspace 全体
- write: child worktree 内の必要最小ディレクトリ
実装 Pod への依頼には以下を含める。
- 対象 ticket と完了条件
- 作業対象は child worktree であり、Bash は `cd <child-worktree> && ...` で実行すること
- `.insomnia` / `TODO.md` / `tickets/` / review artifact / inbox は書かないこと
- git commit / merge / push はしないこと
- build / test / format の結果を報告すること
- 未解決事項と人間確認が必要な点を報告すること
子 Pod の出力は `ReadPodOutput` で確認し、追加依頼が必要なら `SendToPod` を使う。不要になった Pod は `StopPod` する。
## Review
実装 Pod 完了後、原則として実装 Pod を停止して scope を回収してから review する。
reviewer Pod を使う場合は read-only を基本にする。reviewer には以下を依頼する。
- ticket の背景・要件・完了条件を読む
- diff が要件を満たすか確認する
- 既存設計を歪めていないか確認する
- 不必要な実装や過剰な抽象がないか確認する
- build / test 結果が妥当か確認する
review artifact を書く場合は、親 Pod が main workspace 側に書く。child worktree 内の `tickets/` に書く運用は scope 衝突を起こしやすいため避ける。
## 修正依頼
review 指摘があれば、指摘内容をまとめて実装 Pod に再依頼する。既存 Pod を止めている場合は、同じ child worktree と narrow write scope で再 spawn する。
修正後は build / test を再確認し、必要なら再 review する。
## 完了候補報告
最後は作業を完了削除せず、次の形式で人間へ報告する。
```text
完了候補:
- ticket: <path>
- worktree: <path>
- branch: <name>
- 実装概要: ...
- 変更ファイル: ...
- build/test: ...
- review: approve / changes requested / skipped
- 未解決事項: ...
- 人間に戻す判断:
- commit するか
- merge するか
- ticket / review file を更新または削除するか
- TODO.md から削除するか
```
## 試走記録
この Workflow 自体の試走では、対象 ticket、scope 方針、実装 Pod / reviewer の使い分け、停止した理由、不足点を記録する。不足が見つかっても、この Workflow 内で永続ジョブキュー、scope handoff、Pod sleep、ticket lifecycle 再設計を実装しない。必要なら別 ticket として人間に提案する。

150
.insomnia/workflow/multi-agent-workflow.md Normal file
View File

@ -0,0 +1,150 @@
---
description: worktree と子 Pod を使って複数 ticket の実装・レビュー・修正・完了処理を並列に進める orchestration フロー
model_invokation: true
user_invocable: true
requires: []
---
# Multi-agent Worktree Workflow
insomnia を insomnia で開発する際の、worktree + 実装 Pod + 親 Pod review の標準フロー。これは **実装を並列に進めるためのフロー** であり、worktree の機械的作成手順は `$user/worktree-workflow`、ticket 候補選定や方針探索の半自動 loop は `$user/auto-maintain` に分ける。
## 目的
- 実装差分を ticket ごとの child worktree に隔離する。
- 実装 Pod に narrow write scope を渡して並列実装させる。
- 親 Pod が diff / test / ticket 要件を review し、必要なら修正依頼する。
- approve 後に merge / ticket 完了処理 / main workspace での再検証を行う。
## 開始条件
以下が揃っている時に使う。
- 対象 ticket が決まっている。
- ticket の背景・要件・完了条件から実装方針が概ね導ける。
- worktree 作成と git 書き込み操作について、人間の許可がある。
- main workspace の unrelated dirty changes を把握している。
設計方針が複数自然に導ける場合、protocol / scope / permission / history persistence に触れる場合、ticket 自体の再定義が必要な場合は、実装委譲前に人間へ戻す。
## 親 Pod / orchestrator の責務
1. 状態確認
- `git status --short --branch`
- 対象 ticket
- 関連 TODO / docs / 既存 worktree
2. worktree 作成
- `$user/worktree-workflow` に従い `./.worktree/<task-name>` を作る。
- `.insomnia` を sparse checkout で除外する。
3. 実装 Pod spawn
- read scope: main workspace 全体。
- write scope: child worktree、または必要最小 directory。
- task には以下を明示する。
- child worktree path / branch
- 対象 ticket path
- Bash は必ず child worktree に `cd` すること
- main workspace の `TODO.md` / `tickets/` / `docs/report/` / `.insomnia` は編集しないこと
- 範囲外事項
- 実行すべき build / test / format
- 完了報告項目
4. 監督
- `ReadPodOutput` で報告を読む。
- 通知が来ない場合でも、worktree の `git status` / `git diff` / test で完了状態を確認する。
- 必要なら `SendToPod` で修正依頼する。
5. review
- ticket の背景・要件・完了条件・範囲外に照らして diff を確認する。
- build / test / `git diff --check` を確認する。
- 必要なら reviewer Pod を read-only で立てる。
6. merge / lifecycle
- approve 後に main workspace へ merge する。
- `TODO.md` から該当行を削除し、`tickets/foo.md` を削除して完了 commit を作る。
- main workspace で必要な test / `cargo check --workspace` / `cargo fmt --check` を再実行する。
## 実装 Pod の責務
- child worktree 内でのみ実装する。
- main workspace の管理ファイルを書かない。
- 指定された build / test / format を実行する。
- ticket 要件外の設計変更、依存関係追加、scope / permission / history persistence / prompt context 加工原則に触れる変更が必要なら止めて報告する。
- 完了時に以下を報告する。
- worktree path / branch
- commit hash（commit した場合）
- 変更ファイル
- 実装概要
- 実行した build / test / format
- 未解決事項
- review に回せるか
## 実装 Pod の commit 方針
実装 Pod には child worktree 内での commit を許可してよい。
- commit は ticket 内で意味のある粒度にする。
- 例: `feat: ...`、`fix: ...`、`test: ...`、`docs: ...`
- 実装 Pod は merge / push / branch deletion / worktree remove をしない。
- 実装 Pod は `TODO.md` / `tickets/` の完了処理 commit をしない。
- 親 Pod は review 時に commit 粒度も確認する。
- 必要な修正は、原則追加 commit として積む。履歴改変や squash は人間の明示指示がある時だけ行う。
## Review → 修正 → 完了の標準形
### Approve
1. 実装 Pod を停止し、scope を回収する。
2. 親 Pod が main workspace で `git merge --no-ff <branch>` する。
3. 親 Pod が `TODO.md` と `tickets/foo.md` を完了処理して commit する。
4. main workspace で検証コマンドを再実行する。
5. 変更内容・commit・検証結果・残 dirty changes を報告する。
### Request changes
1. blocking finding をファイル / 行 / 理由 / 修正方針つきで整理する。
2. 実装 Pod が生きていれば `SendToPod` で修正依頼する。
3. 停止済みなら、同じ worktree / branch / scope で再 spawn するか、親 Pod が最小修正する。
4. 修正後に focused test と必要な broader test を再実行する。
5. 再 review する。
### Non-blocking comments
- ticket 要件外の改善はその場で混ぜない。
- 必要なら後続 ticket / docs/report にする。
- non-blocking を理由に completion を遅らせない。
## 並列実装時の注意
- 1 ticket = 1 worktree = 1 branch を基本にする。
- 複数 Pod に同じ write scope を渡さない。
- parent は child の write scope 配下を直接編集しない。
- 依存関係がある ticket は、土台 branch を merge してから次 worktree を切る。
- parallel に走らせた Pod の完了通知は取りこぼしうるため、`ReadPodOutput` と worktree 状態で確認する。
## 完了報告の標準形
```text
完了:
- ticket: <path>
- branch: <name>
- commits:
- <hash> <subject>
- 変更概要: ...
- 検証:
- cargo fmt --check
- cargo check --workspace
- cargo test ...
- review: approve / approve with comments / request changes
- 未解決事項: ...
- 残 dirty changes: ...
```
## この Workflow で扱わないもの
以下は `$user/auto-maintain` または別の設計相談で扱う。
- ticket 候補を見繕うこと。
- 新規 ticket 作成判断。
- QA feedback / AI feedback を ticket / report / workflow に落とす判断。
- 長期 maintainer loop / WorkItemStore / LeaseStore の設計。

83
.insomnia/workflow/worktree-workflow.md
View File

@ -1,40 +1,47 @@
--- ---
description: Git worktree を使って実装用作業ツリーを作り、main workspace の管理ファイルと子 worktree のコード差分を分離して開発を進める description: insomnia プロジェクトで child git worktree を作成・管理するための機械的手順。実装 Pod に作らせず、親 Pod が main workspace で実行する。
model_invokation: false model_invokation: false
user_invocable: true user_invocable: true
requires: [] requires: []
--- ---
# Worktree Workflow # Worktree Workflow
Git worktree を使って、実装差分を main workspace から分離して進める。子 worktree はコード変更専用の作業面として扱う。 insomnia プロジェクトで実装差分を main workspace から分離するため、`./.worktree/<task-name>` に child git worktree を作る。これは **worktree の扱い方だけ** を定める Workflow であり、ticket 選定、実装委譲、review、merge の運用は `$user/multi-agent-workflow` 側で扱う。
insomnia では Pod の write scope が排他的に委譲されるため、子 worktree に `.insomnia` を置かず、親 Pod が main workspace 側の管理ファイルを書ける状態を保つ。 insomnia では Pod の write scope が排他的に委譲されるため、child worktree に `.insomnia` を置かない。main workspace は orchestration / ticket / docs / memory / workflow 管理の場所として残し、child worktree はコード差分専用の作業面として扱う。
この Workflow は親 Pod / orchestrator が worktree を用意するための手順である。実装 Pod にこの Workflow を渡して worktree を作らせてはならない。実装 Pod は親 Pod から既存 child worktree を受け取り、その中で実装・build・test・報告だけを行う。 ## 適用範囲
この Workflow は親 Pod / orchestrator が main workspace で実行する。
- 実装 Pod にこの Workflow を渡して worktree を作らせない。
- 実装 Pod は、親 Pod が作成済みの child worktree を受け取り、その中で実装・build・test・報告を行う。
- ticket 作成、TODO 更新、review artifact、docs/report は main workspace 側で扱う。
## 原則 ## 原則
- 1 セッション / 1 ticket / 1 task につき 1 worktree を作る。 - 1 ticket / 1 実装 task につき 1 worktree を作る。
- worktree は `./.worktree/<task-name>` に作る。 - worktree path は `./.worktree/<task-name>`。
- branch 名は原則 `<task-name>` と同じにする。 - branch 名は原則 `<task-name>` と同じ kebab-case。
- 子 worktree はコード差分専用にし、`TODO.md` / `tickets/` / `docs/report/` / inbox などの管理ファイルは main workspace 側で扱う。 - child worktree には `.insomnia` を出さない。
- 子 worktree には `.insomnia` を出さない。worktree 作成後に sparse checkout で `.insomnia` を除外する。 - child worktree は実装差分用。`TODO.md` / `tickets/` / `docs/report/` / workflow / memory は原則 main workspace 側で扱う。
- git commit / merge / push / branch deletion / worktree remove は、人間が明示した場合以外は行わない。 - push はしない。
## 事前確認 ## 事前確認
作業前に以下を確認する。 作成前に以下を確認する。
1. 対象 ticket / task 名が決まっているか。 1. 対象 ticket / task が決まっているか。
2. branch / worktree 名に使える kebab-case の `<task-name>` があるか。 2. `<task-name>` が branch / path 名に使える kebab-case か。
3. git 書き込み操作を行ってよい明示許可があるか。 3. `git worktree add` を実行してよい許可があるか。
4. main workspace の未保存差分や既存 worktree と衝突しないか。 4. main workspace に混ぜてはいけない未保存差分がないか。
5. 同名 branch / worktree が既に存在しないか。
許可が曖昧な場合、`git worktree add` の前に人間へ確認する。 同名 branch がある場合は、既存 branch を使うか、人間に確認する。`git worktree add -b` で上書きしない。
## 作成手順 ## 作成手順
`<task-name>` を確定したら、main workspace で以下を実行する。 main workspace で実行する。
```bash ```bash
git worktree add .worktree/<task-name> -b <task-name> git worktree add .worktree/<task-name> -b <task-name>
@ -46,44 +53,46 @@ git -C .worktree/<task-name> sparse-checkout set --no-cone \
'!/.insomnia/**' '!/.insomnia/**'
``` ```
既に branch がある場合は `-b` で新規作成せず、既存 branch を使うか人間へ確認する。`git worktree add` が失敗した場合は、worktree / branch / lock の状態を確認してから人間へ報告する。 確認する。
```bash
git -C .worktree/<task-name> status --short --branch
test ! -e .worktree/<task-name>/.insomnia
```
失敗した場合は、worktree / branch / lock の状態を確認し、勝手に cleanup せず人間へ報告する。
## 子 Pod へ渡す scope ## 子 Pod へ渡す scope
子 Pod を使う場合、子 Pod の cwd は現状 main workspace のままになる。子 Pod には作業対象が child worktree であることを明示し、Bash 実行時は必ず `cd .worktree/<task-name> && ...` させる。 子 Pod を使う場合、子 Pod の cwd は main workspace のままになる。必ず作業対象が child worktree であることを明示し、Bash 実行時は毎回 `cd <repo>/.worktree/<task-name> && ...` させる。
推奨 scope: 推奨 scope:
- read: main workspace 全体
- write: child worktree の必要最小ディレクトリだけ
例:
```text ```text
read: <repo> read: <repo>
write: <repo>/.worktree/<task-name>/crates/tui write: <repo>/.worktree/<task-name>
``` ```
子 Pod には `tickets/` や inbox を書かせない。review artifact や完了候補の記録は親 Pod が main workspace 側に書く。 より狭く切れる場合は、write scope を変更対象 crate / directory まで狭めてよい。ただし build / test に必要な生成物を書けることを確認する。
## 実装中のルール ## child worktree 内の禁止事項
- child worktree 内で build / test / format を実行する。 - `.insomnia` を作らない / コピーしない。
- main workspace の `.insomnia` や memory は child worktree にコピーしない。 - main workspace の `TODO.md` / `tickets/` / `docs/report/` を編集しない。
- `.insomnia` が child worktree に現れた場合は作業を止め、sparse checkout 設定を確認する。 - merge / push / branch deletion / worktree remove をしない。
- ticket 要件外の設計変更、scope / permission / history 永続化 / prompt context 加工原則に触れる変更は実装前に人間へ確認する。 - scope / permission / history persistence / prompt context 加工原則に関わる設計変更を無断で行わない。
- 依存関係追加や大きな設計変更が必要になった場合も人間へ確認する。
## 完了時 ## 完了時の扱い
実装が終わったら、merge は行わず、以下を報告する。 worktree 作成 Workflow としては、完了時に merge しない。merge、ticket 完了、TODO 削除は `$user/multi-agent-workflow` または人間の明示指示で行う。
実装 Pod へ渡す完了報告項目の標準形:
- worktree path - worktree path
- branch 名 - branch 名
- commit hash（実装 Pod に commit を許可した場合）
- 変更ファイル - 変更ファイル
- 実装概要 - 実装概要
- 実行した build / test / format - 実行した build / test / format
- 未解決事項 - 未解決事項
- review に回せるかどうか - review に回せるか
マージウィンドウとして人間が明示的にこの Workflow を呼んだ場合だけ、merge / worktree remove / branch cleanup の候補手順を提示する。実行は人間の明示許可を待つ。

10
AGENTS.md
View File

@ -10,8 +10,10 @@
LLM に投げる context への割り込みは、大きく2種類に分かれる。**前者は許されるが、後者は禁止**。 LLM に投げる context への割り込みは、大きく2種類に分かれる。**前者は許されるが、後者は禁止**。
- **許される**: 既存 history から純粋に再現可能な変換器（pruning、tool result の content 切り詰め、prompt cache anchor の付与等）。同じ history を入力すれば同じ結果が出る決定的な加工で、history そのものを書き換えるわけでもなく、外から新しい情報を持ち込まない。 Podの状態から純粋に再現可能で、且つ揮発性の無い操作であることが望ましい。（pruning、tool result の content 切り詰め、prompt cache anchor の付与等）。
- **禁止**: ターンを跨ぐことができない情報に基づいて、history に記録せずに context だけにコンテンツを差し込むこと。これをやると LLM はそれに反応して生成を行う一方、次以降のターンでhistoryに残らないため、「自分がなぜその発言/tool call をしたか」の根拠が消えるうえ、prompt cache のヒット率も低下させることになる。 原則として、コンテキストは積み重ねるものであり、一時的にメッセージを差し込むことや、過去のメッセージを改ざんすることはKVキャッシュのヒット率を下げる。
**禁止**: ターンを跨ぐことができない情報に基づいて、history に記録せずに context だけにコンテンツを差し込むこと。これをやると LLM はそれに反応して生成を行う一方、次以降のターンでhistoryに残らないため、「自分がなぜその発言/tool call をしたか」の根拠が消えるうえ、prompt cache のヒット率も低下させることになる。
新しい input を context に乗せたいなら、必ず先に `worker.history` に append して commit すること。`history.json` への永続化はそこから自動的についてくる。Notify / PodEvent / `<system-reminder>` 系はこの原則で扱う（→ `tickets/notify-history-persist.md`）。 新しい input を context に乗せたいなら、必ず先に `worker.history` に append して commit すること。`history.json` への永続化はそこから自動的についてくる。Notify / PodEvent / `<system-reminder>` 系はこの原則で扱う（→ `tickets/notify-history-persist.md`）。
また、キャッシュを破壊するタイミングは正確にコントロールされる必要があり、キャッシュ破壊とトークン消費のトレードオフに基づいて慎重に設計されるべきである。 また、キャッシュを破壊するタイミングは正確にコントロールされる必要があり、キャッシュ破壊とトークン消費のトレードオフに基づいて慎重に設計されるべきである。
@ -26,7 +28,7 @@ LLM に投げる context への割り込みは、大きく2種類に分かれる
## Git操作 ## Git操作
Gitはpush以外のすべての操作が許可されている。 workflowで明示されない限り、読み取り以外の操作は控えること。
基本はworktree上の一時的なブランチでコミットを重ね、メインブランチに取り込む運用をしている。 基本はworktree上の一時的なブランチでコミットを重ね、メインブランチに取り込む運用をしている。
コミットメッセージは適当に`<prefix>: *簡潔な1行*`で書いている。 コミットメッセージは適当に`<prefix>: *簡潔な1行*`で書いている。
@ -34,6 +36,8 @@ Gitはpush以外のすべての操作が許可されている。
--- ---
## Ticketの運用について
`TODO.md`、`tickets/`はgitで管理されていて、時系列の管理はgitを参照して把握すること。 `TODO.md`、`tickets/`はgitで管理されていて、時系列の管理はgitを参照して把握すること。
### TODO.md ### TODO.md

10
CLAUDE.md
View File

@ -10,8 +10,10 @@
LLM に投げる context への割り込みは、大きく2種類に分かれる。**前者は許されるが、後者は禁止**。 LLM に投げる context への割り込みは、大きく2種類に分かれる。**前者は許されるが、後者は禁止**。
- **許される**: 既存 history から純粋に再現可能な変換器（pruning、tool result の content 切り詰め、prompt cache anchor の付与等）。同じ history を入力すれば同じ結果が出る決定的な加工で、history そのものを書き換えるわけでもなく、外から新しい情報を持ち込まない。 Podの状態から純粋に再現可能で、且つ揮発性の無い操作であることが望ましい。（pruning、tool result の content 切り詰め、prompt cache anchor の付与等）。
- **禁止**: ターンを跨ぐことができない情報に基づいて、history に記録せずに context だけにコンテンツを差し込むこと。これをやると LLM はそれに反応して生成を行う一方、次以降のターンでhistoryに残らないため、「自分がなぜその発言/tool call をしたか」の根拠が消えるうえ、prompt cache のヒット率も低下させることになる。 原則として、コンテキストは積み重ねるものであり、一時的にメッセージを差し込むことや、過去のメッセージを改ざんすることはKVキャッシュのヒット率を下げる。
**禁止**: ターンを跨ぐことができない情報に基づいて、history に記録せずに context だけにコンテンツを差し込むこと。これをやると LLM はそれに反応して生成を行う一方、次以降のターンでhistoryに残らないため、「自分がなぜその発言/tool call をしたか」の根拠が消えるうえ、prompt cache のヒット率も低下させることになる。
新しい input を context に乗せたいなら、必ず先に `worker.history` に append して commit すること。`history.json` への永続化はそこから自動的についてくる。Notify / PodEvent / `<system-reminder>` 系はこの原則で扱う（→ `tickets/notify-history-persist.md`）。 新しい input を context に乗せたいなら、必ず先に `worker.history` に append して commit すること。`history.json` への永続化はそこから自動的についてくる。Notify / PodEvent / `<system-reminder>` 系はこの原則で扱う（→ `tickets/notify-history-persist.md`）。
また、キャッシュを破壊するタイミングは正確にコントロールされる必要があり、キャッシュ破壊とトークン消費のトレードオフに基づいて慎重に設計されるべきである。 また、キャッシュを破壊するタイミングは正確にコントロールされる必要があり、キャッシュ破壊とトークン消費のトレードオフに基づいて慎重に設計されるべきである。
@ -26,7 +28,7 @@ LLM に投げる context への割り込みは、大きく2種類に分かれる
## Git操作 ## Git操作
Gitはpush以外のすべての操作が許可されている。 workflowで明示されない限り、読み取り以外の操作は控えること。
基本はworktree上の一時的なブランチでコミットを重ね、メインブランチに取り込む運用をしている。 基本はworktree上の一時的なブランチでコミットを重ね、メインブランチに取り込む運用をしている。
コミットメッセージは適当に`<prefix>: *簡潔な1行*`で書いている。 コミットメッセージは適当に`<prefix>: *簡潔な1行*`で書いている。
@ -34,6 +36,8 @@ Gitはpush以外のすべての操作が許可されている。
--- ---
## Ticketの運用について
`TODO.md`、`tickets/`はgitで管理されていて、時系列の管理はgitを参照して把握すること。 `TODO.md`、`tickets/`はgitで管理されていて、時系列の管理はgitを参照して把握すること。
### TODO.md ### TODO.md