nwlnexus/agent-skills

チャーンのないGitNexus

GitNexusをそのまま使うと、次の2種類の繰り返しノイズが発生します。

1. スタイルインデックス。インデックスはビルド時のコミットを記録します。そのため、コミットするたびに「Nコミット遅れている」と報告され、Claudeフックがanalyzeの再実行を促します。
2. ドキュメントの書き換え。素のgitnexus analyzeは、CLAUDE.md/AGENTS.mdの管理セクション（<!-- gitnexus:start -->…<!-- gitnexus:end -->）に揮発性のシンボルカウントを注入し、スキルを再インストールするため、再インデックスごとにコミットを必要とする差分が生まれます。

どのリポジトリでも修正方法は同じです。Gitフックが--index-onlyでインデックスをHEADに保ち、ドキュメントは--no-statsで一度だけ生成し、gitnexusのアップグレード後にのみ再生成します。chore(gitnexus): …という1つのPRとして適用してください。

ステップ0 — 前提条件（読み取り専用）

command -v gitnexus && gitnexus --version          # インストールされていること（mise/npm global。npxは使わないこと）
test -f .gitnexus/gitnexus.json && gitnexus status # インデックス済み？ 未インデックスなら: gitnexus analyze --index-only
git config core.hooksPath; ls .husky lefthook.yml .lefthook.yml .pre-commit-config.yaml 2>/dev/null
ls CLAUDE.md AGENTS.md; grep -c 'gitnexus:start' CLAUDE.md AGENTS.md 2>/dev/null
ls package.json Makefile justfile 2>/dev/null

決定事項: フックマネージャー（husky → lefthook → pre-commit → プレーン）、リポジトリローカルスクリプトの配置場所（scripts/、tools/、bin/…リポジトリに合わせる）、リポジトリがコマンドを公開する方法（package.jsonのscripts、Makefile、justfile、なし→生コマンドを記述する）。

ステップ1 — リフレッシュスクリプトのインストール

このスキルディレクトリからscripts/gitnexus-refresh.shをリポジトリのスクリプト配置場所（例: scripts/git-hooks/gitnexus-refresh.sh）にコピーし、chmod 755します。このスクリプトはリポジトリに依存しません。gitルートを解決し、gitnexusがない場合やクローンがインデックスされていない場合は静かに終了し、インデックスがすでにHEADと一致している場合はスキップし、それ以外の場合はgitnexus analyze --index-onlyをデタッチ（ログは.gitnexus/refresh.log）で実行します。リポジトリの慣習（例: 異なるスクリプトディレクトリ）で要求されない限り、リポジトリごとにフォークしないでください。

ステップ2 — post-commit、post-merge、post-checkout、post-rewriteの配線

フックの中身は1行: sh <path>/gitnexus-refresh.sh。post-checkoutはHEADを移動させるブランチチェックアウトの場合のみ実行します。最初に[ "$3" = "1" ] && [ "$1" != "$2" ] || exit 0とします。

• husky（.husky/が存在する場合）: .husky/post-commit、post-merge、post-checkout、post-rewriteを追加します（既存のフックと同じshebang/モード。husky 9はsh -eで実行します）。
• lefthook: post-commit、post-merge、post-checkout、post-rewriteセクションを単一のgitnexus-refreshコマンドで追加します。post-checkoutの場合はrun: sh <path>/gitnexus-refresh.sh {1} {2} {3}とします。
• pre-commit framework: stages: [post-commit、post-merge、post-checkout、post-rewrite]、always_run: true、pass_filenames: falseを持つrepo: localフックを追加します。ユーザーにpre-commit install --hook-type post-commit --hook-type post-merge --hook-type post-checkout --hook-type post-rewriteの実行を促します。
• なし: 4つのファイルを持つコミット済みの.githooks/を作成し、リポジトリのセットアップスクリプト/Makefileターゲットでgit config core.hooksPath .githooksを設定します（コミットされていない.git/hooksに依存しないこと）。

フックをpre-commit/pre-pushに絶対に配置しないでください。これらのフックは高速に保つ必要があり、インデックスは結果のHEADに従うべきです。

ステップ3 — ドキュメントを安定させる

1. 管理セクションを一度だけカウントなしで再生成します: gitnexus analyze --force --no-stats --skip-skills。差分は(N symbols、…)のヘッダーカウントとエリアごとのカウントテーブルのみ削除することを期待します。リポジトリに管理セクションがなく、不要な場合は、すべての場所で--index-onlyを使用し、この手順をスキップします。

2. リポジトリの慣習に従って2つのコマンドを公開します:

   • 定期リフレッシュ → gitnexus analyze --index-only（例: pnpm gitnexus:index / make gitnexus-index）
   • ドキュメントリフレッシュ → gitnexus analyze --force --no-stats --skip-skills（例: gitnexus:refresh-docs）、gitnexusのアップグレードでテンプレートが変更された場合のみ

3. 短い**「GitNexus index hygiene」**セクションをマーカーの外側にあるCLAUDE.md（および存在する場合はAGENTS.md）に追加し、リポジトリに合わせて調整します:

   インデックス（.gitnexus/、追跡対象外）はpost-commit/post-merge/post-checkout/post-rewriteフック（<path>/gitnexus-refresh.sh）によって自動的にリフレッシュされます: インデックスオンリー、バックグラウンド、ログは.gitnexus/refresh.log。それでも遅れていると報告される場合は、<index command>を実行してください。

   • 素のgitnexus analyze（またはnode .gitnexus/run.cjs analyze）を実行しないでください。CLAUDE.md、AGENTS.md、.claude/skills/gitnexus-*を書き換えます。代わりに<index command>を使用してください。
   • <docs command>は、揮発性のカウントなしで管理gitnexus:start…gitnexus:endセクションを再生成します。gitnexusのアップグレード後にのみ実行し、結果をコミットしてください。マーカーの間を手動で編集しないでください。

4. リポジトリにまだ古いネストされた.claude/skills/gitnexus/<skill>/レイアウトやコミットされた.claude/skills/generated/**がある場合は、GitNexus ≥1.6が書き込むフラットな.claude/skills/gitnexus-*レイアウトに置き換えます（gitnexus analyze --skills --skip-agents-mdがgitnexus-area-*を再生成します。古いディレクトリはgit rmします）。エリアスキルはボディにのみカウントを持ちます。これは問題ありません。フックによって再生成されることはありません。

ステップ4 — PRを開く前に確認

git commit …                      # post-commitが起動
sleep 10; tail -3 .gitnexus/refresh.log; gitnexus status   # Indexed == Current、✅ up-to-date
git status --short                # クリーンであること: CLAUDE.md/AGENTS.md/skillsに差分がないこと

その後、プッシュ、PR、マージ（承認された場合）、mainをプルします。プルでpost-mergeが起動します。gitnexus statusで再度確認してください。

経験則

• 自動化するものには--index-only、ドキュメントに触れるものには--no-stats。素のanalyzeは絶対に使用しないでください。
• インデックスリフレッシュは軽量（秒単位、増分）ですが、高速なリベースでは複数回の実行がキューイングされる可能性があります。gitnexus自身のロックがそれらを直列化するため、フックにロックを追加しないでください。
• 複数のワークツリーにはそれぞれ独自の.gitnexus/があります。フックはそれぞれ独立して処理します。
• npxを介したgitnexusの実行は遅く（レジストリラウンドトリップ、TLSに敏感）、MCPの30秒の接続タイムアウトを超える可能性があります。インストール（mise/npm global）してバイナリを直接参照してください。
• リポジトリ内からユーザーごとのGitNexus MCP/フックセットアップを変更しないでください。それはユーザーのClaude設定（Nigelの場合はnix管理）にあります。