ここに書くのはこのプロジェクトでしか言えないことだけである。全プロジェクトに通る決めごとは共通のルールにあり、同じ文を両方に書かない。
3 節とも、実際に踏んだ落とし穴である。次のセッションが同じ順路を辿らないようにするのが目的で、一般論を並べる場所ではない。
root の CLAUDE.md はこの資料から生成した Markdown を 1 行で取り込んでいる。セッションを開くと本文が読み込まれる。
全体を示す設計書は notes/10_plan/p260829-01-設計.html である。README から「設計」としてリンクしている。
大きな変更は別の計画書（notes/10_plan/pyymmdd-nn-件名.html）を立てて実装する。実装が済んだら、設計書を最新に更新する。個別の計画書は残し、設計書からリンクで参照する。
実装したものが正である。設計書が古いと、読み手はどれが正か判断できない。
| 箇所 | 何を見るか |
|---|---|
| テーブルの役割 / スキーマ | テーブルと列。sqlite_master から取り出して貼る（推測で書かない） |
| API | 追加・変更した口 |
| コマンド表 | CLI のコマンドとオプション |
| 個別の計画書の一覧 | notes/10_plan/ の全件が表に並んでいるか。片付いたものも消さない |
スキーマは手で写さない。版を重ねるたびに写していたため、設計書が 6 か所ずれていた。cursors と archives が丸ごと無く、messages に足した 2 列と msg_kind の 2 値、索引 3 本も落ちていた。
テスト用の置き場を新しく作って版を当て、sqlite_master から取り出せばずれようがない。
計画書は設計書の表から辿れるようにする。README には代表だけを載せる。
README の資料一覧は色相を本数で割って振っている（刻み＝280 ÷（本数 − 1））。1 本足すと hsl() の指定が 28 か所すべて変わるため、計画書を足すたびに全部を振り直すことになる。
CLI は node 版（src/client/chat.mjs）と C# 版（src/cli-cs/）の 2 本ある。片方だけ直すと食い違う。
| 守ること | 中身 |
|---|---|
| 定義は 1 か所 | 出どころは src/client/options.mjs。tools/20_build/export-options.mjs が JSON に書き出し、C# 版はそれを埋め込む。手で写さない |
| 形を変えたら版を上げる | JSON の形を変えたら schema を上げる。C# 版の Definition.ExpectedSchema と tests/cli-cs.test.mjs の期待値も合わせる |
| 食い違いはテストが落とす | tests/cli-cs.test.mjs が出力・終了コード・埋め込んだ定義を突き合わせている |
2 本を保守する限り、食い違いは必ず出る。実際に、同じ秒に立った待受けの並び順が食い違った（C# 版はミリ秒まで持ち、node 版は秒に丸めていた）。say の本文なしの終了コードも片方だけ違っていた。
どちらも突き合わせのテストがあって初めて見つかった。目で読んで気づける差ではない。
走っている待受けが aichat.exe を掴んでいる。待受けは 12 時間張りっぱなしになるので、その間ずっと掴まれたままである。
掴んでいるのは自分の待受けだけではない。他プロジェクトの分も混ざる。止めれば相手は原因不明の exit 255 で落ちる（課題の i260901-07）。
tools/20_build/build-aichat.ps1 が始めに片付ける。ふつうは消し、掴まれているときだけ tmp/aichat-old-<日時>.exe へ退避する。
--- 古い exe を片付ける ---
退避済み 1 本のうち 1 本を消しました（残り 0 本は待受けが掴んでいます）
待受けが掴んでいるので退避しました: .\tmp\aichat-old-20260903-215152.exe
走っている待受けは落ちません。退避先を使い続けますWindows では、走っている exe は削除できないが名前は変えられる。走っているプロセスは名前を変えたあとの実体を使い続けるため、退避しても落ちない。空いた名前に新しいものを置ける。
退避したものは次のビルドで消せるだけ消す。残っていても構わない。