zaivern-code CLAUDE.md

CLAUDE.md — Zaivern Code 開発ガイド（AIエージェント向け）

このファイルはリポジトリで作業する全ての AI エージェント／開発者が最初に読むこと。

絶対ルール

• ハードコーディング禁止。 どの環境（macOS / Windows / Linux、任意のユーザー名・ホーム・ロケール）でも動くコードのみ。
  • パスは std::env::temp_dir() / dirs クレート / 設定から導出。/tmp・/Users/...・C:\ の直書き禁止。
  • OS 差分は cfg!(windows) 等で分岐し、両側を実装する。
  • エージェント固有値（resume フラグ、コマンド名等）は agents.rs のカタログにデータとして持つ。
• egui 0.29 固定（アップグレード禁止）・rustc 1.88+。
• 道具は Rust に置く。シェル (tools/*.sh) までは可。Python は置かない。 検証・生成・変換の道具を .py で書くと、リポジトリに第 2 の言語と第 2 の 実行環境が増える（どの python か・依存はあるか・Windows で動くか）。 Rust なら zai <sub> として利用者にもそのまま渡せて、番人テストと同じ実装を 共有できる（2 つ持つとずれて、番人が緑なのに製品が壊れている嘘が出る）。
  • 実例: 翻訳の保守は zai i18n missing / apply / check。走査と エスケープ解除は src/locale.rs の scan_source_literals / unescape_rust 1 か所だけを、CLI とテストの両方が呼ぶ
  • 一度きりの作業スクリプトはリポジトリの外（scratchpad）で書き捨てる
• vendor/vt100 はパッチ済みベンダリング。 visible_rows 修正を外すと deep scrollback で debug パニックが再発する。バージョンアップ時は必ずパッチを移植。
• リリースは checksums.txt を必ず作り、インストーラは必ずそれを検証する。 release.yml の checksums ジョブ (5 ターゲット + install.sh + install.ps1 + SBOM = 8 行、 形式検査つき fail-closed) と、install.sh の verify_checksum / install.ps1 の Test-Checksum は対である。片方だけ外してはいけない。
  • 検証は展開の前（tar xzf / Expand-Archive より前）。書き出してから 気付いても、そのファイルはもうディスクにある
  • 取得失敗・行が無い・道具が無い・不一致 — どの理由でも中止する。 「確かめられなかったので、とりあえず入れた」は検証していないのと同じ
  • 番人は cli::tests::インストーラは展開前にsha256を検証する と cli::tests::検証できないときは中止する。落ちたら直すのは実装であってテストではない
  • 0.16.0 まで checksums.txt は生成されていたのに、最重要の自動インストール経路 (curl | sh / irm | iex) が一度も見ていなかった。作っているのに使っていない チェックサムは、作っていないのと同じ意味しか持たない
• main へ直接コミットしない。作業はブランチ＋隔離ワークツリー（.claude/worktrees/）で行う（複数の AI エージェントが同時編集する前提）。
• 統合したワークツリーは即座に消す。 ブランチが統合先の祖先になった時点で git worktree remove + git branch -D まで行う。各ワークツリーは独立した target/ を持つため、放置すると1つあたり数 GB積み上がる (実測: 15 個で 47GB)。ディスクだけの問題ではなく、ページキャッシュが 押し出されてテスト実行が数倍遅くなる。
• git stash を使わない。 stash スタックは全ワークツリーで共有されるため、 同時に動いている別のインスタンスの退避を巻き込む。退避が要るなら WIP コミットを切る。
• UI から到達できない実装は「未完成」。 完了報告の前に cargo check の never used 警告を必ず確認し、自分が追加した公開関数・型・コマンドが 実際に呼ばれていることを確かめる。この警告は「作ったのに繋いでいない」の検出器である。 到達経路（パレット / メニュー / ボタン / キーバインドのいずれか）を必ず1つ以上用意し、 用意できないなら README には機能として書かず、未完項目として残す。
• 機能を増やす前に減らせないかを考える。 同じ操作への到達経路が3つあるなら 2つ削る。常に0を表示するバッジ、中身より空状態を見せる時間が長いパネル、 ツールバーとヘッダで重複するボタンは、実装した本人が消す。
• 新しい機能は src/features/<名前>.rs を新規作成するだけで足す。 app.rs / palette.rs / feature.rs / main.rs を編集しない。