AGENTS.md

AGENTS.md

概要

• このリポジトリは lssh を中心とした SSH クライアントスイートです。
• CLI エントリポイントは cmd/* にあり、実装の中心は internal/app/* と関連する internal/* にあります。
• 単一コマンドの修正でも、共有処理に触れる場合は他コマンドへの影響を必ず確認してください。

作業

• 基本的に、受け答えは日本語で対応してください。
• Go のバージョンは go.mod に合わせてください。古い Go への互換対応を勝手に追加しないでください。
• 既存のディレクトリ構成とコマンド命名 (lssh, lscp, lsftp, lssync, lsdiff, lsshfs, lsmon, lsshell, lsmux, lspipe) を維持してください。
• github.com/kevinburke/ssh_config は upstream に戻さず、./internal/ssh_config の置き換え前提を保ってください。

実装方針

• 変更範囲はできるだけ局所化し、無関係なリファクタは混ぜないでください。
• CLI フラグ、設定ファイル形式、既存のユーザー向け挙動を不必要に変えないでください。
• クロスプラットフォーム性を意識してください。特に Linux / macOS / Windows の差異がある処理では、対象 OS を明示して実装してください。
• lsshfs まわりは OS 制約があるため、Linux/macOS 前提の挙動を他コマンドに波及させないでください。
• TUI 操作や複数ホスト処理では、1台向けの変更が並列実行時に破綻しないか確認してください。
• 基本的に、コマンド実行をユーザが指定する機能以外ではOSコマンドを実行しての機能実装はしないでください。もしそれしか実現方法がない場合は都度聞いてください。
• Vendorへの修正はNGです。Vendorはgo mod以外で変化が加わることがないようにしてください。vendor配下が原因の可能性がある場合、まずはバージョンを上げることで対応できるかどうか検討してください。
• アーキテクチャの切り替えのような大きな変更を行う場合、勝手にやらず一旦ユーザへの確認を挟んでください。
• providerについては、特にクラウド等サーバへ通信が必要な処理の場合はローカルコマンド実行の類は極力行わないようにしてください。できるだけAPIを叩いたりSDKを使う実装を心がけてください。
• providerとinternalは分離してください。特に、internalにprovider向けの機能を持ち込むのは絶対にNGです。あくまでもcoreに必要な追加にとどめ、providerの対応のためにinternalに変更が必要な場合は汎用的なインターフェイスとして使える仕組みを追加するにとどめて下さい。providerがinternalに依存するのはいいですが、逆は絶対にあってはいけません。そのようなコードが存在する場合は即座に修正してください。
• provider共通で使うライブラリを作る場合は、providerapiやその他provider用のライブラリを汎用的なものとして設計し、インターナルもしくはprovider参照用のディレクトリに配置してください。固有providerのコードをlsshのコードから参照しないでください。
• 現在/providerにおいているproviderについては、公式プロバイダとして別リポジトリに外出しする予定です。それを前提として設計・開発をしてください。providerが含まれるテストに於いては、providerのテストとしてinternalなどには絶対に含めないでください。含まれている物が見つかったら、都度修正してください。

ビルドとテスト

• 変更後は、まず影響範囲に近いテストを優先して実行してください。
• 最終確認として可能なら make test を実行してください。
• ビルド確認が必要な変更では make build を実行してください。
• 変更対象が限定的な場合は、mise.toml にある個別タスクや該当パッケージの go test を優先して構いません。
• テストやビルドが未実行なら、実行していないことと理由を最終報告に明記してください。

ドキュメント更新ルール

• ユーザー向け挙動、CLI オプション、設定方法、インストール手順を変えた場合は、対応する README / docs も更新してください。
• 主に次を確認してください。
  • README.md
  • docs/*.md
  • 影響を受ける cmd/*/README.md

変更時の注意

• デフォルト値や設定キー名を変える場合は、既存ユーザーへの影響を最小化してください。
• 破壊的変更を入れる場合は、移行手順または互換レイヤを検討してください。
• 新規依存の追加は、本当に必要な場合だけにしてください。
• セキュリティや接続処理に関わる変更では、proxy / forwarding / auth への副作用を確認してください。

最終報告の書き方

• 何を変えたかを簡潔に述べてください。
• 実行したテストやビルドコマンドを列挙してください。
• 未確認事項、既知の制約、OS 依存の注意点があれば明記してください。

Code quality

• 読みやすさを優先してください。短く説明しづらい実装より、少し冗長でも意図が明確な実装を選んでください。
• 1つの関数やメソッドに複数の責務を詰め込みすぎないでください。処理が肥大化する場合は分割してください。
• 命名は省略しすぎず、役割が推測できる名前を使ってください。
• 同じロジックを3か所以上に増やさないでください。共通化の価値がある場合は helper や内部関数へ切り出してください。
• エラーは握りつぶさず、呼び出し元で判断できる形で返してください。
• 例外的な分岐や OS 依存の理由は、必要に応じて短いコメントで補足してください。
• 巨大な関数を追加するより、既存の責務境界に沿って小さく変更してください。
• 無関係な整形や大規模リネームは、今回の目的に必要な場合を除いて混ぜないでください。

Go style

• まず標準ライブラリで解決できるかを確認し、不要な依存を増やさないでください。
• Go らしい単純な実装を優先し、過度に抽象化しないでください。
• interface は必要になってから導入してください。将来の拡張だけを理由に増やさないでください。
• 並行処理を追加する場合は、複雑さに見合うかを確認してください。
• ログ、戻り値、エラー文は利用者が原因を追いやすい内容にしてください。

Change discipline

• 挙動変更とリファクタは可能なら分けてください。
• CLI フラグ、設定ファイル、接続仕様に影響する変更では、後方互換性を強く意識してください。
• 公開挙動を変えた場合は README / docs / cmd 配下の説明も更新してください。