zaivern-code: Instructions file for Codex

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 を待たない。非同期結果と直近の値を使い、更新頻度と同時実行数を制御する。