nwlnexus/agent-skills

無雜訊 GitNexus

若直接使用 GitNexus，會產生兩種重複性雜訊：

1. 索引過時。索引會記錄建立時的 commit；每次提交後都會顯示「落後 N 個 commits」，且 Claude hook 會提示重新執行 analyze。
2. 文件改寫。單純執行 gitnexus analyze 會將不穩定的符號計數注入受管理的 <!-- gitnexus:start -->…<!-- gitnexus:end --> 區段（位於 CLAUDE.md/AGENTS.md 中），並重新安裝技能，因此每次重新索引都會產生一個需要提交的差異。

每個儲存庫的修復方式都相同：git hooks 使用 --index-only 將索引維持在 HEAD，且文件在建立時使用 --no-stats，僅在 gitnexus 升級後才重新產生。以一個 chore(gitnexus): … 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 lefhook.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

決定：hook 管理工具（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

Hook 內容為一行：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（使用與現有 hooks 相同的 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 框架：新增一個 repo: local hook，設定 stages: [post-commit, post-merge, post-checkout, post-rewrite]、always_run: true、pass_filenames: false；提醒使用者執行 pre-commit install --hook-type post-commit --hook-type post-merge --hook-type post-checkout --hook-type post-rewrite。
• 無：在儲存庫中建立一個 commit 的 .githooks/ 目錄，內含上述四個檔案，並在儲存庫的設定腳本/Makefile 目標中執行 git config core.hooksPath .githooks（永遠不要依賴未 commit 的 .git/hooks）。

絕對不要將 hook 放在 pre-commit/pre-push 之下：這些 hook 必須保持快速，且索引應跟隨最終的 HEAD。

步驟 3 — 讓文件穩定

1. 不使用計數重新產生一次受管理的區段：gitnexus analyze --force --no-stats --skip-skills。預期差異只會移除 (N symbols, …) 的標頭計數以及每個區域的計數表格。如果儲存庫從未擁有受管理的區段且不想要，則全部使用 --index-only 並跳過此步驟。

2. 依據儲存庫慣例暴露兩個命令：

   • 例行重新整理 → gitnexus analyze --index-only（例如 pnpm gitnexus:index / make gitnexus-index）
   • 文件重新整理 → gitnexus analyze --force --no-stats --skip-skills（例如 gitnexus:refresh-docs），僅在 gitnexus 升級改變其範本後執行。

3. 在 CLAUDE.md（以及若有 AGENTS.md）的標記之外，新增一個簡短的 「GitNexus 索引衛生」 區段，根據儲存庫調整：

   索引（.gitnexus/，未追蹤）由 post-commit/post-merge/post-checkout/post-rewrite hooks（<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 升級後執行，並將結果 commit。請勿手動編輯標記之間的內容。

4. 如果儲存庫仍有已廢棄的巢狀 .claude/skills/gitnexus/<skill>/ 佈局或已 commit 的 .claude/skills/generated/**，請將其替換為 GitNexus ≥1.6 寫入的平面 .claude/skills/gitnexus-* 佈局（gitnexus analyze --skills --skip-agents-md 會重新產生 gitnexus-area-*；git rm 移除舊目錄）。區域技能僅在其內容中包含計數 — 這沒問題，因為 hooks 不會重新產生它們。

步驟 4 — 在開啟 PR 前驗證

git commit …                      # 觸發 post-commit
sleep 10; tail -3 .gitnexus/refresh.log; gitnexus status   # Indexed == Current，✅ 已是最新
git status --short                # 必須乾淨：無 CLAUDE.md/AGENTS.md/skills 差異

然後推送、開 PR、合併（若獲授權）、拉取 main — 拉取會觸發 post-merge；再次確認 gitnexus status。

經驗法則

• 自動化操作一律使用 --index-only；任何會觸及文件的操作使用 --no-stats；永遠不要使用裸 analyze。
• 索引重新整理成本低（數秒，增量），但快速變基會佇列多次執行；gitnexus 自身的鎖會串行化它們 — 不要在 hook 中額外加上鎖定。
• 多個工作目錄各自有獨立的 .gitnexus/；hooks 會獨立處理每一個。
• 透過 npx 執行 gitnexus 很慢（需查詢 registry、對 TLS 敏感）且可能超過 MCP 的 30 秒連線超時 — 請安裝它（mise/npm global）並直接參考二進位檔。
• 不要從儲存庫內部更改每個使用者的 GitNexus MCP/hook 設定；那屬於使用者的 Claude 配置（對 Nigel 而言是 nix 管理）。