AGENTS.md

このリポジトリで作業するときの前提。使い方は README.md を見る。

構成

開発時は docs/develop.md を読む。開発環境、検証・ビルド手順、Makefile の決まりはそこにまとめてある。

配布は「クローン + uv tool install -e <クローン>」だけ。skill は PATH の ix-ssh を呼ぶ。 gh skill install は skill ディレクトリしか複製しない (src/ が付いてこない) ので README から 外してある。戻さない。 共通のクローン先は ~/.agents/skills/ix-toolkit。 manualbook の変換結果の形 (<manuals>/<系列>/<冊子>/ と索引の列) は ix-manual の SKILL.md が そのまま読む。片方を変えたらもう片方も直す。

機器運用 (src/ix_ssh/) とマニュアル整備 (internal/manualbook/) は独立した領域として扱い、 層の切り方と依存の向きは両方で同じにする。domain は他の層、HTTP、PDFium、HTML DOM、 netmiko / paramiko、ファイル入出力に依存させない (ix-ssh は tests/test_layering.py がこれを検証する)。 infrastructure は domain を使い、application / cli には依存させない。 application は domain と infrastructure を組み合わせる。cli は application だけを呼ぶ (infrastructure を直接呼ばない)。プロセス終了は cli に置く。manualbook では原因を表示し終えた 失敗を application.ReportedError で終了コードだけ伝え、ix-ssh ではユーザーが直せる失敗を domain.UsageError にして cli が本文を表示して 1 で終わる。netmiko / paramiko の import は セッションを開く関数の中に置き、--list / --help が両方無くても動くようにしておく。

skill を書き換えるときの決まり

skill は Claude Code を主に、Codex など SKILL.md を読む他のエージェントでも同じように動く形を保つ。 本文に特定のエージェントの記法を書かない。

• $ARGUMENTS を使わない。置換するのは Claude Code だけで、Codex は置換しない。対象は「ユーザーの 依頼から読み取る」と書く。
• 他の skill は /ix-ssh ではなく ix-ssh と名前で参照する（/ は Claude Code、$ は Codex の 呼び出し記法）。
• ツール名を単独で要求しない。Read / Grep / Glob を例として書くのは可。ただしやることが 本体で、シェルでも同じことができると分かるように書く。
• frontmatter は name と description が必須。argument-hint / allowed-tools / compatibility / license は Claude Code 向けで、読まないエージェントは黙って無視する （Codex は name / description / metadata.short-description だけを読む）。
• ix-ssh は PATH のコマンドとして呼ぶ。スクリプトのパスや python … の呼び出しを skill に書かない （クローンの置き場所はエージェントごとに違い、agent 非依存に書く方法が無い）。
• データのパスはエージェントの home に置かない。インベントリは ~/.ix-toolkit/devices.json（場所は ix-ssh --list が表示する）、マニュアルは $IX_MANUALS → ~/.ix-toolkit/manuals/ → ~/.claude/ix-manuals/ の順に探し、その下が <系列>/<冊子>/（ix/crm, ix-r/fd …）。 系列間の対応表は <manuals>/ix-r/diff.tsv。
• 系列は 2 つ（ix = IX2000/IX3000、ix-r = IX-R/IX-V）でコマンドが違う。skill は系列を インベントリの model → 会話 → ユーザーに聞く、の順で決める。model はヒントであって ゲートではない（無くても止まらない）。系列で変わるコマンド名（show logging / show syslog 等）を skill に書くときは両方を併記し、ix-manual の diff.tsv の項と食い違わせない。

リポジトリに入れないもの

• 機器の資格情報とインベントリ（~/.ix-toolkit/devices.json）。
• マニュアル本文・変換結果・ページ画像・Web の取得キャッシュ（pdf/）。NEC の著作物で、各自の 手元で取得・変換する。定期的に取りに行く仕組みも作らない（各自が最初に 1 回取り、NEC の 更新情報を見て自分で manifest.json を直して取り直す）。