zaivern-code

Imported from tacyan/zaivern-code (AGENTS.md). Install upstream with npx skills add tacyan/zaivern-code. Copyright stays with the author.

AGENTS.md — Zaivern Code 開発ガイド

このリポジトリで作業するエージェント・開発者向けの現行ルール。 回答・進捗・完了報告は日本語で行い、着手前に変更対象と影響範囲を確認する。 ユーザーの明示的な依頼を優先する。適用できないルールは理由と代替策を報告する。 過去の事例は 履歴資料 の関連箇所だけ参照する。 履歴資料の命令形・測定値は、現在の指示・仕様・性能保証として扱わない。

作業と変更の保護

• コード変更はブランチ＋隔離ワークツリー（.Codex/worktrees/）で行い、main へ直接コミットしない。指定された未追跡の文書・設定は、元の内容を保全して指定場所へ反映してよい。
• 着手時に Git の状態を確認する。他人の変更を上書き・削除しない。git stash は使わず、必要なら自分の変更だけを WIP コミットにする。
• git checkout --、git reset --hard、強制削除を他人の作業の整理に使わない。サブエージェントにも同じ制約を伝える。
• 自分のワークツリーは、統合済み・未コミット変更なし・使用中のエージェントやプロセスなしを確認してから git worktree remove で片付ける。ブランチは原則 git branch -d で削除する。squash 統合等では内容の取り込みも確認する。
• 積み上げた PR の土台が squash 統合された場合は差分を確認し、必要なら rebase --onto で取り込み済み変更を外す。共有履歴の変更前に利用状況を確認する。
• 変更点は意味のある作業単位で差分を表示する。大きい差分は要点と完全な差分ファイルを提示する。
• 完了報告には変更内容・検証結果・未確認事項を記す。依頼されていない公開・リリースは行わない。

実装と設計

• 環境依存値を直書きしない。パスは std::env::temp_dir()、既存 API、設定から導出する。仕様上の定数・安定 ID は許可する。性能上の上限には根拠と到達時の挙動を持たせる。
• macOS / Windows / Linux の対応を維持する。OS 専用 API は #[cfg(...)] 等で分離する。cfg!(...) だけでは対象外 OS の型検査を除外できない。非対応の場合は明示的に扱う。
• egui は 0.29 系、rustc は 1.88+ を維持する。明示的な依存更新の依頼では互換性を別途検証する。
• 保守する検証・生成・変換ツールは Rust を優先する。既存のシェルやフロントエンド環境は利用してよい。Python の保守ツールを新設しない。一度限りの作業スクリプトはリポジトリ外に置く。
• エージェント固有のコマンド・フラグ・環境変数は agents.rs のカタログへ集約する。存在と実際の効果を区別し、未確認の設定を追加しない。
• vendor/vt100 の独自修正（visible_rows、スクロールバック等）を維持し、更新時は差分と関連テストを確認する。
• 負荷・データ量・遅延要件に基づいて設計する。全機能に巨大なアクセス数や DB 構成を一律に仮定しない。不要な抽象化・設定・依存を増やさない。
• 永続キーは history::workspace_key / workspace_set_key に集約し、版に依存するハッシュを使わない。移行を維持する。詳細は キーの仕様 を参照する。
• PTY・スクロールバック・セッションの寿命をビューから分離する。非表示ビューへの転送は上限と欠落表示を設け、ビューの都合で PTY の読み取りを停止させない。
• エージェント状態は構造化プロトコル・公式フック・状態ファイルを優先する。画面解析は根拠と不確実性を示す。診断は既存の in-process 設計を優先する。
• 承認を回避するフラグを自動注入しない。既存の承認経路と監査可能性を維持する。

機能の接続と UI

• 新機能の登録は原則 src/features/<名前>.rs に閉じ、Cmd::Feature("<module>.<action>") を使う。生成一覧はコミットせず、ID の一意性と接頭辞を守る。
• app.rs / palette.rs / feature.rs / main.rs の変更は必要な接続・基盤変更に限定し、理由を説明する。config.rs / keybinds.rs 等は並列作業時に担当を決めて統合する。
• ZaivernApp のフィールドを接続のために公開しない。必要な操作を pub(crate) メソッドで提供する。実処理へ接続しない空の登録を置かない。
• GUI 機能は UI 操作から、CLI 機能は CLI から、内部機能は製品コードから到達することを確認する。未接続の機能を完成済みと記載しない。
• dead_code / never used 警告は補助であり、警告ゼロは到達可能性の証明ではない。未完成を警告抑制で隠さない。必要な抑制は範囲と理由を明示する。
• 重複 UI は目的を確認して整理する。操作経路の数だけでキーボード操作やアクセシビリティを削らない。
• 更新でレイアウトやフォーカスを不用意に変えない。空状態は次の操作を示し、狭い画面でも見切れを防ぐ。排他的なビューは単一の状態型で管理する。
• 複雑なレイアウト判断は純粋関数に分け、境界サイズで検証する。CJK / IME、選択・コピー、フォーカスを重点的に確認する。
• 打鍵表記は keybinds::format_shortcut / key_hint から生成し、OS 予約と再割り当てを考慮する。消費は既存の keybinds::consume_shortcut_compat を利用する。
• UI スレッドで Git・外部プロセス・重い I/O を待たない。非同期結果と直近の値を使い、更新頻度と同時実行数を制御する。

多言語

• 画面の文言は crate::i18n::tr / trf を通し、新規キーは安定 ID にする。tr のキーには単一の文字列リテラルを渡し、行継続・concat!・動的生成を避ける。
• 同梱6言語の辞書を更新し、zai i18n missing / apply / check と関連テストで検証する。手順は 多言語の説明 を参照する。
• スマホ側の T() / data-i18n も同じ辞書を使う。Rust の走査だけで JS のキーを検証したことにしない。
• 有効な言語パックと ui_language を一致させる。機械置換では空白・語の接合を言語ごとに確認する。

変更範囲に応じた検証

• 文書だけの変更は差分・リンク・指示の整合性を確認する。実行コードやビルドに影響しなければ Rust / OS 検証は不要。
• Rust 変更は tools/verify.sh を入口とし、push 前には tools/verify.sh --lint を実行する。テストコードもコンパイルして警告を確認する。同じ目的で check と test を重複実行しない。
• OS 分岐・ファイルシステム・プロセス・端末・打鍵・依存・ビルドの変更は、影響する OS を検証する。Linux は tools/linux-test.sh、Windows は tools/windows-check.sh を使い、ホストの成果物を分離する。
• 保存済み Windows 検証 VM の起動・終了・再現手順は Windows VM 手順 を参照する。
• クロスチェック成功を、対象 OS の実行・GUI・リソース埋め込みの確認と扱わない。GUI 変更は対象の操作と表示を検証する。プロセス生存確認は起動の検査に限定する。
• スマホ画面は必要に応じて tools/remote-check.sh を使う。実 PTY テストの全量実行には .config/nextest.toml の分離・直列化・時限設定を使う。
• 実行不能・skip は理由付きで「未確認」と報告する。Docker 固有の既知の制約は再現条件と追跡先を記録し、新しい失敗を一括除外しない。
• 再実行で緑になっても原因を負荷と断定しない。コミット・入力・環境を記録する。乱数を使う検証には seed の指定と出力を用意する。
• リリース前は tools/release-gate.sh を実行し、必要な結果がすべて揃ってから公開する。必須チェックの skip・未完了は成功ではない。詳細は リリース前検証 を参照する。

テストと測定の信頼性

• テストは test_util::unique_temp_dir 等を使う。子プロセスには Command::env 等で専用の ZAIVERN_HOME を渡し、同一プロセスではパス注入や既存の隔離ヘルパーを使う。実ユーザーの設定・セッション・台帳に触れず、自分が作成したと追跡できる資源だけを削除する。
• ポートは OS に割り当てさせる。解放後の再 bind には競合の余地があるため、既存の再試行ヘルパー等を使う。
• カウンタはテストごとに隔離する。単一スレッドの観測はスレッドローカル、複数スレッドの観測はテスト専用の共有状態を使う。
• OS 由来の既定値は OS 条件を、FS の性質は製品と同じ探針を期待値へ反映する。Git 設定はキーごとに有効なスコープを判断する。環境変数の変更を他のテストへ漏らさない。
• テキスト変換は元の改行を保存する。ソース照合は必要に応じて CRLF を正規化し、対象の関数・構造に範囲を絞る。
• 保証を検査するテスト・ハーネスは、保証を破る入力や故障注入で失敗することも確認する。行域の重複禁止と Git のマージ成功は別の性質として検査する。
• CLI の回帰は必要に応じて実バイナリで検証する。隣の古い zai を無条件に使わず、test_util::zai_gate_at を利用する。版と mtime の検査は補助であり、確実性が必要なら対象ソースからビルドする。
• コマンドの終了コードと結果件数を確認する。パイプ末尾の成功を元のコマンドの成功と解釈しない。検証スクリプトは最後に成功・失敗・未確認の判定を出す。
• 長時間の検証には進捗ログ・無進捗時限・全体上限を持たせ、時限自体も検証する。進捗で延長しても全体上限を超えない。時限の比較は単位を揃える。
• 性能は条件を揃えて前後を測る。計算量や呼び出し回数で検査できる性質は絶対時間に依存させない。遅延要件は管理された環境で測り、分布・試行数・ばらつきを記録する。
• ハーネス費用は空回し等で測って生の値と併記する。差し引きは加算可能な場合に限り、方法を説明する。効果未確認の最適化は撤回するか、未検証であることと残す理由を記す。
• GUI 性能は ZAIVERN_PERF=1 等でフレーム時間の分布・最大値・再描画理由を見る。アイドル CPU と描画負荷は別々に測る。強制再描画した値を自然なアイドルの値と扱わない。
• 性能・安全性・競合制御の重要な保証は、別のエージェントまたはレビュー担当者に反証を依頼する（反証できたら成功と伝える）。できない場合は未実施と報告し、保証を断定しない。通常の文書・文言修正は対象外。

リリースとプロセスの安全性

• checksums.txt の生成とインストーラでの検証を対で維持する。検証は展開前に行う。取得失敗・対象行なし・形式不正・検証手段なし・不一致は中止する。期待する成果物一覧はリリース定義と一致させる。
• 安全性テストを失敗解消だけのために弱めない。仕様変更では保証とテストを一緒に見直す。
• 終了済みセッションや所有を確認できない PID に kill を送らない。必要な終了は既存の procx::kill_tree 等を使う。独立したプロセスグループを使い、無関係なプロセスを巻き込まない。
• ロック待ちは進捗と上限を持たせる。Windows 固有の競合判定は lease::lock_contended を使い、一般の権限エラーを無条件に再試行しない。