全体設計が概ね固まり、随所の細かい仕様を詰めながら実装を進めている。 ## このシステムに置ける設計要旨 - プロンプトはすべて resources/promptsに集約している。管理効率の工場と同時に、ユーザーがオーバーライドする形式でもある。 - E2E(実プロセスをスポーンさせてのテスト)は未設計。 ### LLM コンテキストの加工原則 LLM に投げる context への割り込みは、大きく2種類に分かれる。**前者は許されるが、後者は禁止**。 - **許される**: 既存 history から純粋に再現可能な変換器（pruning、compaction による要約、tool result の content 切り詰め、prompt cache anchor の付与等）。同じ history を入力すれば同じ結果が出る決定的な加工で、history そのものを書き換えるわけでもなく、外から新しい情報を持ち込まない。 - **禁止**: Pod の現在状態（受信した notification、active な内部キュー、time-of-day、外部イベント等）に基づいて、history に commit せずに context だけに新規 input を差し込むこと。これをやると LLM はそれに反応して history を変化させる一方、トリガーは worker.history に残らないため、次ターン以降「自分がなぜその発言/tool call をしたか」の根拠が消える。resume 時にはさらに露骨に再現不能になる。prompt cache の prefix も毎回ズレる。 新しい input を context に乗せたいなら、必ず先に `worker.history` に append して commit すること。`history.json` への永続化はそこから自動的についてくる。Notify / PodEvent / `` 系はこの原則で扱う（→ `tickets/notify-history-persist.md`）。 --- Gitは基本的にすべてユーザーが操作している。書き込みが必要な操作は明示的に許可されない限り行わないこと 外部の参考プロジェクトはexternal checkoutでローカルでReadする運用をしている。 --- `TODO.md`、`tickets/`はgitで管理されていて、時系列の管理はgitを参照して把握すること。 ### TODO.md - 1チケット = 1行。未完了のみ記載し、完了したら行ごと削除する（履歴はgitで追える） - ネストは同一領域のグルーピング（表示用）にのみ使う。実装上の依存関係はネストで表現しない - 完了した子は削除し、親は未完了の子がある限り残す。最後の子が完了したら親ごと削除 - Ticketを追加する際は、合わせてTODOも書くこと ### Ticket の粒度 - 1チケット = 完了時点で、実装が仕様又は機能として説明できる粒度。 - 作成時、背景や要件を前提として書き、実装の方針やコードの詳細は不必要に増やさない。 - チケット内のステップ（Phase 1, 2, ...）は実装順序であり、TODO等、外に出さない - ビルドが通り、その機能に限り,まだ動作できないと明示出来ている場合を除いて全体を通して動作させられる状態である必要がある。 ### Ticket のライフサイクル gitがタイムラインの単一の情報源。ファイル操作とcommitで状態遷移を表現する。 a. 作成: `tickets/foo.md` を作成してcommit b. 詳細化や前提の変化: `tickets/foo.md` を更新してcommit c. レビュー: `tickets/foo.md` にレビュー状態を追記 + `tickets/foo.review.md` を作成してcommit d. 完了: `tickets/foo.md` と `tickets/foo.review.md` を両方削除してcommit TODO.mdのリンクは完了後に切れるが、そのリンクを元にgitで消されたファイルを読み、内容を把握できる。 `.review.md` にはレビューの指摘事項と判断結果を記載する。 レビューはdiffの確認だけでなく、チケットはどのような前提・要件であり、それが達成されたかの確認まで含めて行う。 常に、提出された実装で良いのか、コードベースを歪めていないか、不必要な実装ではないかを確認すること。 --- insomniaでinsomniaを開発している際、AI自身のフィードバックを元に改善を回すために `docs/report/`ディレクトリに感じた障壁や改善案等を書き残す形にした。 明確に力不足な点/ツールの問題があった場合や、ユーザーからの指示があった際に作ること。