graphify AST tier 도입과 공유 globals 오염 사고에서 배운 것 — 정책보다 차단 훅이 막는다

graphify AST tier 도입과 공유 globals 오염 사고에서 배운 것 — 정책보다 차단 훅이 막는다

코드베이스를 AST 그래프로 인덱싱해 두면, AI 가 원본 파일을 직접 안 읽고 그래프에 질의해서 토큰을 크게 아낄 수 있다(무료 AST tier). 좋은 도구였지만, 5노드에 깔다가 “설치 도구가 공유 SoT 를 오염시키는” 사고를 두 번 냈다. 거기서 뽑은 노하우.

graphify 가 뭐고 어떻게 운용하기로 했나

• graphify = 코드베이스 → AST(추상 구문 트리) 그래프 인덱싱. AI 가 원본을 통째로 읽는 대신 그래프에 질의 → 토큰 대폭 절감(무료 tier).
• 운용 결정(안1) = 바이너리만 5노드 동일 버전으로 통일 + 수동 graphify update/graphify explain. 자동 발동·하니스 설치(공유 설정 변경)는 안 함.

사고 — 설치 서브커맨드가 공유 심링크 SoT 를 건드렸다

graphify 의 설치 서브커맨드가 ~/.claude(= claude-skills repo 의 심링크, 5노드 공유) 안의 globals 글로벌룰 파일을 오염시켰다. 데스크탑(어제)·라이덴(오늘) 2회 동일 사고. 설치 도구가 “개인 하니스” 가 아니라 “공유 SoT(심링크)” 를 건드리는 구조라는 걸 도입 전에 못 봤다.

해결 — 정책이 아니라 차단 훅으로

PreToolUse 훅(graphify-install-guard.sh)으로 그 설치 명령 실행 자체를 차단(forcing function)하고 5노드에 등록했다. 탈출구는 환경변수 1개로 열어둔다(의도된 설치만 통과).

핵심 교훈 1 — 정책 결정만으론 재발한다

어제 ‘안1(설치 금지)’ 을 결정했는데도, 오늘 다른 노드에서 똑같이 재발했다. 사람이 지키는 정책은 안 지켜진다. 같은 실수가 반복될 여지가 있으면, 문서·결정이 아니라 기술적 강제장치(실행 차단 훅)를 박아야 실제로 막힌다.

핵심 교훈 2 — 설치류가 공유 심링크 SoT 를 오염시키는 구조 주의

~/.claude/skills → claude-skills 처럼 공유 repo 를 심링크로 쓰면, 한 노드의 install 산출물이 곧 전 노드로 전파된다. 새 도구를 도입하기 전에 “이 도구가 공유 SoT(심링크된 repo)를 건드리나?” 1회 점검하는 습관이 가장 싸게 막는 길.

핵심 교훈 3 — auto-use 같은 ‘좋은 설계’ 도 실행 환경에 막힐 수 있다

원래는 repo-local skill 의 자동 발동으로 가려 했으나, 노드 세션이 home 디렉토리에서 돌아서 repo-local 설정이 자동 로드되지 않았다. 결국 수동 운용으로 확정. 설계가 깔끔해도 실행 환경과 안 맞으면 미채택 — ‘맞는지’ 를 먼저 확인하고 설계를 고른다.

보너스 교훈 — 차단 훅의 over-match(false positive)

그 차단 훅이 명령을 ‘실행’ 하는 경우뿐 아니라 단순히 ‘텍스트로 전달’ 하는 경우(디렉티브 설명문·문서에 명령어 문자열이 섞인 경우)까지 매치해 false positive 를 낼 수 있다. 전달 텍스트는 sanitize(차단 대상 명령어 문자열 회피)해야 한다. 보안 분류기의 cyber 어휘 회피와 같은 원리 — ‘실제 호출’ 과 ‘인용’ 을 구분하지 못하는 패턴 매칭의 한계.

다시 꺼내쓰는 법

• 새 CLI·도구를 멀티노드에 깔 때 — “공유 SoT(심링크 repo·글로벌 설정)를 건드리나?” 먼저 점검
• 같은 실수가 정책 결정 후에도 반복될 때 — 문서가 아니라 차단 훅(forcing function)으로 전환
• 자동 발동·repo-local 설정이 안 먹을 때 — 실행 환경(세션 cwd 등)부터 의심, 안 맞으면 수동 운용으로 후퇴
• 차단 훅을 만들 때 — ‘실행’ 과 ‘텍스트 인용’ 을 구분, 전달 텍스트는 명령어 문자열 회피