CLAUDE.md가 기기마다 달라지는 건 부주의 때문이 아니다

CLAUDE.md 는 한 번 쓴다. 여섯 달 뒤 노트북에는 그 파일이 열여덟 개 있고, 어느 것이 맞는지 말할 수 없다.

가정이 아니다. 직접 쓰는 기기를 스캔해서 확인한 상태다. 아래는 그 일이 왜 일어나는지, 그리고 가장 먼저 떠오르는 해법이 왜 이 문제를 닫지 못하는지에 대한 기록이다.

사본은 사용자가 아니라 도구가 만든다

에이전트마다 자기 소유의 경로에서 지시문을 읽는다.

사본을 네 벌 유지하겠다고 결정한 적은 없다. 도구를 네 개 쓰겠다고 결정했을 뿐이다. 사본은 도구에 딸려 왔다.

드리프트는 부주의에서 나오지 않는다

세 가지 기전이 드리프트를 만든다. 셋 다 누가 대충 일해서 생기는 것이 아니다.

사용 지점에서 고친다. 작업 도중 에이전트가 이상하게 움직인다. 지금 눈앞에 열려 있는 지시문 파일을 고친다. 그 파일은 넷 중 하나고, 수정도 하나에만 반영된다.

체크아웃은 단위가 아니다. 같은 리포지토리를 두 번 클론해 둔다. 하나는 메인 브랜치, 하나는 오래 끌고 가는 브랜치용이다. 양쪽 모두 지시문 파일을 갖고 있다. 어느 한쪽을 건드리는 순간 갈라진다.

홈 디렉터리 지침은 보이지 않는다. ~/.claude/CLAUDE.md 는 어느 리포지토리에도 속하지 않는다. 어떤 CI 에도 들어가지 않는다. 리뷰에서 논쟁하고 싶지 않았던 규칙이 결국 모이는 자리다.

하나에서 생성해도 닫히지 않는다

자연스러운 대응은 사본 유지를 그만두는 것이다. AGENTS.md 를 한 번 쓰고 나머지를 생성한다.

그걸 만들어 봤다. 동작한다. agent-fanout 이다 — 단일 파일 파이썬, 의존성 없음, MIT.

python3 agent_fanout.py

create    CLAUDE.md
create    .cursor/rules/from-agents-md.mdc
create    .github/copilot-instructions.md

생성된 파일에는 직접 수정하지 말라는 헤더가 붙고, CI 에서 --check 를 걸면 손으로 고친 파생 파일이 빌드를 실패시킨다.

이것이 덮는 범위는 CI 가 돌아가는 이 리포지토리 다. 전부처럼 들리지만, 바깥에 남는 것을 적어 보면 이렇다.

• 홈 디렉터리의 전역 설정 — 리포지토리도 없고 CI 도 없다
• 수정과 수정 사이의 구간 — 에이전트는 파일이 바뀐 즉시 읽고, CI 는 푸시 시점에 안다. 푸시가 있다면
• CI 가 없는 리포지토리 — 프로토타입, 버릴 클론, 지난주의 실험. 지시문이 가장 자유롭게 다시 쓰이면서 게이트는 가장 적은 자리다
• 단위는 리포지토리가 아니라 기기다. 에이전트는 여러 체크아웃과 같은 리포지토리의 여러 사본, 그리고 홈 디렉터리를 함께 가진 노트북 위에서 돈다. 리포지토리 단위로 동작하는 것은 그 전체를 볼 수 없다

그래서 막기만 할 게 아니라 재야 한다

예방은 정책이고 탐지는 측정이다. 정책은 우회되며, 재지 않으면 우회된 사실 자체가 보이지 않는다.

agent-drift 는 리포지토리가 아니라 경로를 스캔하고, 파일명이 아니라 내용 유사도로 묶는다.

python3 agent_drift.py ~/work ~/side-projects

Scanned 47 instruction files.
DRIFT: 2 documents, 5 distinct versions between them.

  claude-code:CLAUDE.md
    6 copies, 3 versions
      9b01aeaa204d  3 files, 406 lines
      2dc3c616c279  2 files, 411 lines

여기서 파일명 매칭은 쓸모가 없다. 서로 무관한 프로젝트가 서로 다른 CLAUDE.md 를 갖는 것은 정상이고, 그것을 드리프트로 보고하는 도구는 아무도 안 보게 된다. 한 프로젝트가 아니라 작업 디렉터리 전체를 대상으로 돌려야 한다 — 의미 있는 결과는 리포지토리 경계를 넘는 쪽에서 나온다.

일은 하나가 아니라 둘이다

생성은 사본이 존재할 이유를 없앤다. 탐지는 예상하지 못한 이유로 존재하게 된 사본을 잡는다. 둘 중 하나만 하면 덮여 있다는 느낌 만 남는데, 이는 안 덮였다는 사실을 아는 것보다 나쁜 상태다. 내가 그대로 겪었다.

이 문제의 끝

솔직한 종착점은 두 스크립트가 모두 필요 없어지는 것이다. 자산이 기기 위에 파일로 흩어져 있지 않고, 검토를 마친 사본 하나가 모든 기기에 닿는 상태다. 그것을 untactit 에서 만들고 있고, 아직 공개 전(pre-launch)이다. 파편화는 각자가 손대서 생긴다. untactit 은 손댈 필요를 없앤다.

스크립트는 제품에 의존하지 않는다. 쓸모 있는 쪽만 가져가면 된다.

이 글은 DEV 에도 올려 두었습니다.