nwlnexus/agent-skills

변경을 유발하지 않는 GitNexus

GitNexus는 기본적으로 사용할 때 두 가지 종류의 반복적인 노이즈를 유발합니다:

1. 오래된 인덱스. 인덱스는 빌드된 커밋을 기록합니다. 모든 커밋은 인덱스를 "N 커밋 뒤쳐짐" 상태로 만들고, Claude 훅은 analyze를 다시 실행하라고 알립니다.
2. 문서 재작성. 단순 gitnexus analyze는 CLAUDE.md/AGENTS.md의 관리되는 <!-- gitnexus:start -->…<!-- gitnexus:end --> 섹션에 변동 가능한 심볼 카운트를 주입하고 스킬을 재설치하므로, 재인덱싱할 때마다 커밋이 필요한 diff가 생성됩니다.

모든 리포지토리에서 해결책은 동일합니다: git 훅이 --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 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/refresh.log)에서 gitnexus analyze --index-only를 실행합니다. 리포지토리의 규칙이 요구하지 않는 한(예: 다른 스크립트 디렉토리) 리포지토리별로 포크하지 마세요.

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: 단일 gitnexus-refresh 명령어로 post-commit, post-merge, post-checkout, post-rewrite 섹션을 추가합니다; post-checkout의 경우 run: sh <path>/gitnexus-refresh.sh {1} {2} {3}를 사용합니다.
• pre-commit 프레임워크: 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를 실행하라고 알립니다.
• 없음: 네 개의 파일이 있는 커밋된 .githooks/ 디렉토리를 만들고, 리포지토리의 설정 스크립트/Makefile target에서 git config core.hooksPath .githooks를 설정합니다 (커밋되지 않은 .git/hooks에 절대 의존하지 마세요).

절대 훅을 pre-commit/pre-push 아래에 두지 마세요: 해당 훅은 빨라야 하며 인덱스는 결과적인 HEAD를 따라야 합니다.

3단계 — 문서를 안정적으로 만들기

1. 관리 섹션을 카운트 없이 한 번 재생성합니다: gitnexus analyze --force --no-stats --skip-skills. (N symbols, …) 헤더 카운트와 영역별 카운트 테이블만 제거하는 diff가 예상됩니다. 리포지토리에 관리 섹션이 없었고 원하지 않는다면, 모든 곳에서 --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, ✅ 최신 상태
git status --short                # 반드시 깨끗해야 함: CLAUDE.md/AGENTS.md/skills diff 없음

그런 다음 푸시, 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 관리)에 있습니다.