nwlnexus/agent-skills

无干扰的 GitNexus

GitNexus 在简单使用时会产生两种重复性噪音：

1. 索引过期。 索引记录了它构建时的提交；每次提交都会让它“落后 N 个提交”，Claude 钩子会提示重新运行 analyze。
2. 文档重写。 裸 gitnexus analyze 会将易变的符号计数注入 CLAUDE.md/AGENTS.md 的受管理 <!-- gitnexus:start -->…<!-- gitnexus:end --> 部分，并重新安装技能，因此每次重新索引都会产生一个需要提交的差异。

每个仓库的修复方法相同：git 钩子使用 --index-only 将索引保持在 HEAD，并且文档使用 --no-stats 生成一次，仅在 gitnexus 升级后重新生成。以一个 chore(gitnexus): … PR 应用它。

第 0 步 — 前置条件（只读）

command -v gitnexus && gitnexus --version          # 必须已安装（mise/npm 全局）；永远不要依赖 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 脚本、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）。除非仓库的约定要求（例如不同的脚本目录），否则不要为每个仓库 fork 它。

第 2 步 — 连接 post-commit、post-merge、post-checkout、post-rewrite

钩子主体是一行：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 框架：添加一个 repo: local 钩子，带有 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。
• 无：创建一个已提交的 .githooks/，包含这四个文件，并在仓库的设置脚本/Makefile 目标中设置 git config core.hooksPath .githooks（永远不要依赖未提交的 .git/hooks）。

永远不要将钩子放在 pre-commit/pre-push 下：这些必须保持快速，并且索引应跟随结果 HEAD。

第 3 步 — 使文档稳定

1. 使用不带计数的 --no-stats 重新生成受管理部分一次：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 钩子（<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 全局）并引用二进制文件。
• 不要从仓库内部更改每个用户的 GitNexus MCP/钩子设置；那位于用户的 Claude 配置中（Nigel 使用 nix 管理）。