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 에서 만들고 있고, 아직 공개 전()이다. 파편화는 각자가 손대서 생긴다. untactit 은 손댈 필요를 없앤다.

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

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