5.3 KiB
全体設計が概ね固まり、随所の細かい仕様を詰めながら実装を進めている。
このシステムに置ける設計要旨
- プロンプトはすべて resources/promptsに集約している。管理効率の工場と同時に、ユーザーがオーバーライドする形式でもある。
- E2E(実プロセスをスポーンさせてのテスト)は未設計。
- 変更量を最小にするために設計を歪めたり、設計問題に対して不必要な後方互換性を作らない。長期的なメンテナンスと型安全性を追求すること。
LLM コンテキストの加工原則
LLM に投げる context への割り込みは、大きく2種類に分かれる。前者は許されるが、後者は禁止。
Podの状態から純粋に再現可能で、且つ揮発性の無い操作であることが望ましい。（pruning、tool result の content 切り詰め、prompt cache anchor の付与等）。 原則として、コンテキストは積み重ねるものであり、一時的にメッセージを差し込むことや、過去のメッセージを改ざんすることは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）。
また、キャッシュを破壊するタイミングは正確にコントロールされる必要があり、キャッシュ破壊とトークン消費のトレードオフに基づいて慎重に設計されるべきである。
実際のセッションを読んでデバッグする
~/.insomnia/sessionsにすべてのセッションがある。jsonlなので、いい感じにBashで読むこと。
Git操作
workflowで明示されない限り、読み取り以外の操作は控えること。
基本はworktree上の一時的なブランチでコミットを重ね、メインブランチに取り込む運用をしている。
コミットメッセージは適当に<prefix>: *簡潔な1行*で書いている。
外部の参考プロジェクトは必要に応じてローカルの外部 checkout からReadすること。
Ticketの運用について
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
worktreeと併用して作業を進める場合、必ずブランチを切る前に対象のチケットをコミットしてから切ること。
TODO.mdのリンクは完了後に切れるが、そのリンクを元にgitで消されたファイルを読み、内容を把握できる。
.review.md にはレビューの指摘事項と判断結果を記載する。
レビューはdiffの確認だけでなく、チケットはどのような前提・要件であり、それが達成されたかの確認まで含めて行う。
常に、提出された実装で良いのか、コードベースを歪めていないか、不必要な実装ではないかを確認すること。
insomniaでinsomniaを開発している際、AI自身のフィードバックを元に改善を回すために docs/report/ディレクトリに感じた障壁や改善案等を書き残す形にした。 明確に力不足な点/ツールの問題があった場合や、ユーザーからの指示があった際に作ること。