인스타 피드에서 이걸 봤어요.
앤트로픽이 CLAUDE.md를 진단해주는 플러그인을 공개했다는 소식이요.
그 자리에서 클로드 코드를 켜고 이렇게 시켰습니다.
(링크 던지고) 자 이거해보자
먼저, CLAUDE.md가 뭐냐면
AI가 작업 시작할 때마다 자동으로 읽는 안내문이에요. 어떤 폴더에 뭐가 있고, 서버는 어떻게 켜고, 뭘 조심해야 하는지 적어두는 파일입니다. 사람으로 치면 새 직원이 출근할 때마다 읽는 인수인계 노트요.
챗봇 창에 매번 배경 설명을 붙여넣는 대신, 파일 하나에 적어두면 알아서 읽는 구조라고 보시면 돼요. 클로드 코드나 커서를 쓰신다면 이미 만들어져 있을 거고, 안 쓰셔도 이 글의 교훈은 그대로 적용됩니다. AI한테 주는 배경 설명은 어디서든 낡거든요.
498줄 중 255줄이 "없는" 폴더 설명이었어요
플러그인이 정한 검사 항목대로 하나씩 확인해봤어요. 폴더가 실제로 있는지 없는지를 직접 열어서요.
자리만 차지하는 거면 그나마 나아요. 진짜 문제는 클로드가 이걸 지금 사실로 믿고 판단한다는 거예요. 없는 폴더에 파일을 만들려 하거나, 끝난 워크숍의 할 일을 챙기려 들 수 있는 거죠.
냉장고를 생각하면 쉬워요. 문 열면 안쪽 절반이 작년에 사둔 소스들이에요. 유통기한은 지났는데 버리진 않아서 자리는 그대로 차지하고 있고요. 근데 AI는 그걸 오늘 쓸 수 있는 재료로 알고 씁니다.
만화 수달이 냉장고 앞에 서 있다
정작 매일 쓰는 39개는 안 적혀 있었어요
최근 2주 안에 파일이 수정된 폴더를 세어보니 43개였는데, 그중 39개는 CLAUDE.md에 이름조차 없었어요. (폴 더 수정 시각 기준으로 셌습니다.)
블로그 자동 발행, 항공권 값 감시, 호텔 메일 모니터링처럼 맥이 알아서 돌리는 작업도 35개가 등록돼 있는데 한 줄도 없었고요. 진단하던 순간 서버 네 개가 켜져 있었는데, 문서에 적힌 포트 번호(프로그램마다 배정되는 통로 번호예요)와 하나도 겹치지 않았습니다. 문서에 적힌 포트는 전부 없어진 프로젝트 것이었거든요.
왜 이렇게 됐냐면, 다른 파일이 대신 떠받치고 있었어요. 클로드에는 메모리라는 기능이 따로 있는데(작업하면서 알게 된 걸 쌓아두는 곳), 그게 어느새 CLAUDE.md보다 커져 있더라고요. 안쪽은 상한 것들이 점령했고 매일 쓰는 계란이랑 우유는 식탁 위에 나와 있던 셈이에요.
목록을 적지 말고, 세어보라고 시켰어요
냉장고 얘기를 조금만 더 할게요.
안에 뭐가 들었는지 종이에 적어서 문에 붙여놨다고 쳐요. 우유 한 통, 계란 열 개, 김치 한 통. 그럼 뭘 하나 꺼내 먹을 때마다 종이도 같이 고쳐야 해요. 한 번만 깜빡해도 그때부터 그 종이는 거짓말을 시작합니다.
근데 종이에 이렇게만 적어두면요. "뭐 있는지는 열어보고 확인해."
이 종이는 안 썩어요. 1년 뒤에 봐도 맞는 말이거든요. CLAUDE.md도 똑같이 바꿨습니다.
전에는 이렇게 적었어요
"내 프로젝트 폴더는 A, B, C, D 네 개다"
→ 폴더가 하나 늘거나 줄면 그 순간부터 틀린 말이 됨
지금은 이렇게 적습니다
"폴더 목록은 이 명령을 실행해서 세어봐"
→ 물어볼 때마다 지금 값이라 썩을 일이 없음
제 파일엔 "깃 저장소는 5개"라고 적혀 있었는데 세어보니 24개였어요. 적어둘 당시엔 분명 맞는 말이었을 거예요. 그게 함정입니다. 맞는 말이었기 때문에 아무도 다시 안 열어봐요.
그래서 문서에는 이런 것만 남겼습니다. 몇 년이 지나도 안 바뀌는 규칙, 조심할 것, 왜 이렇게 했는지 같은 이유들이요.
한국 테디베어가 종이 한 장을 들고 있다
진행 중인 프로젝트 43개도 똑같이 처리했어요. 이름을 하나하나 적으면 또 썩으니까, "STATUS.md라는 파일이 있는 폴더 = 지금 살아있는 프로젝트"라는 규칙만 두고 목록은 명령으로 뽑게 했습니다.
대신 매일 켜는 서버 7개는 포트 번호까지 표로 넣었어요. 이건 자주 안 바뀌면서 매번 찾기는 번거로운 정보라서요. 다 명령으로 바꾸는 게 능사는 아니더라고요.
죽은 경로를 자동으로 잡는 검사기
사람이 기억해서 관리하면 또 똑같아집니다. 그래서 검사기를 하나 만들었어요. 지금 아무것도 없어도 되고, 클로드 코드에 이 문장만 복사해서 붙여넣으면 처음부터 만들어줍니다.
내 CLAUDE.md에 적힌 경로를 전부 뽑아서 실제로 존재하는지 검사하는 파이썬 스크립트를 만들어줘. 없는 경로가 하나라도 있으면 오류로 끝나게 하고, GitHub 저장소 이름처럼 내 컴퓨터 경로가 아닌 건 검사에서 빼줘.
돌리면 이렇게 나와요.
확인된 경로 15건 정상
죽은 경로 없음다만 이 검사기가 잡는 건 "경로가 있냐 없냐"뿐이에요. 폴더는 멀쩡히 있는데 그 안의 설명이 낡은 경우, 예를 들어 서버 포트가 바뀌었거나 실행 명령이 달라진 경우는 못 잡습니다. 앞에서 제가 걸린 게 정확히 그런 종류였고, 그건 결국 손으로 열어봐서 찾았어요. 자동 검사는 바닥을 받쳐주는 거지 사람 눈을 대체하진 못하더라고요.
그리고 하나 더 있어요. 이걸 만들어놓고 보니 제가 기억날 때 돌리는 스크 립트더라고요. 이 글에서 "사람이 기억해서 관리하면 또 썩는다"고 해놓고 정작 검사기를 그렇게 남겨둔 거죠. 그래서 CLAUDE.md를 고칠 때마다 자동으로 돌게 연결했습니다. 이제 없는 경로를 적으면 그 자리에서 바로 걸려요.
CLAUDE.md에 존재하지 않는 경로가 있다. 적어두기 전에 확인하라:
- ~/vod_system/pipeline-prototype/server.js498줄에서 206줄로
플러그인이 정한 채점 기준으로 처음엔 41점, 정리 후엔 88점이었어요. 그런데 이 숫자는 그대로 믿으시면 안 됩니다. 두 가지 이유 예요.
첫째, 점수를 매긴 건 플러그인이 아니라 클로드예요. 플러그인을 깔았는데 그 대화에서는 바로 안 잡혔어요(다시 켜야 목록에 뜨더라고요). 그래서 플러그인 폴더를 열어 안에 든 지침 파일을 직접 읽고, 거기 적힌 절차와 배점대로 진행했습니다.
둘째, 88점은 채점 기준을 아는 상태에서 고치고 스스로 다시 매긴 점수예요. 시험 문제를 알고 다시 시험 본 셈이라, 41점과 나란히 놓고 "이만큼 좋아졌다"고 하기엔 무리가 있어요.
그래서 점수보다 믿을 만한 건 사실 확인이 되는 숫자들이에요. 폴더가 있는지 없는지, 몇 줄인지, 포트 번호가 몇 번인지는 전부 직접 실행해서 봤습니다. 498줄이 206줄이 된 것, 없어진 폴더가 다섯 개였던 것, 그건 세어보면 나오는 값이니까요.
원본은 따로 복사해뒀어요. 지운 것 중에 나중에 필요한 게 있을 수도 있으니까요.
그리고 이번에 못 푼 게 하나 남았습니다. 앞에서 말한 메모리랑 CLAUDE.md에 같은 내용이 겹쳐 있는 문제요. 없어진 폴더를 지우는 건 확인만 하면 되니까 쉬웠는데, 두 군데 다 살아있는 정보가 적혀 있을 때 어느 쪽을 원본으로 삼을지는 규칙을 새로 정해야 하더라고요. 잘못 정리하면 멀쩡한 정보가 사라지고요. 그건 다음으로 미뤘습니다.
원본 지침(CLAUDE.md)과 작업하며 쌓이는 클로드의 메모리(Memory) 사이에 겹치는 정보를 어떻게 정리하고 원본(Single Source of Truth)을 유지할 것인지는 아직 답을 찾 지 못했습니다. 혹시 이 둘의 우선순위를 깔끔하게 관리하고 계신 분이 있다면 노하우를 공유해 주세요.
정리하면
AI가 뭘 읽고 있는지는 한 번도 안 열어봤으면서, 답이 이상하면 모델 탓부터 했던 것 같아요. 저는 그 파일을 오래 방치했고, 그 사이 조용히 과거를 가리키고 있었습니다. 이번에 고친 게 결과를 얼마나 바꿨는지는 솔직히 아직 몰라요. 며칠 더 써봐야 알겠죠. 다만 없는 폴더를 사실로 알고 있던 상태보다 나빠질 일은 없더라고요.
그리고 한 번 버리는 걸로는 부족했어요. 또 상할 것을 아예 안 넣는 게 진짜 해결이었습니다. 세어보면 알 수 있는 건 그때 세어보게 하고, 변하지 않는 것만 적어두는 것.
마지막으로 하나. 청소하는 사람도 기억에 의존한다는 게 이번에 제일 뜨끔했던 부분이에요. 고치는 김에 새로 적은 것들이 오히려 검증을 안 거친 값이었거든요.
혹시 지금 AI가 자꾸 엉뚱한 걸 물어보거나, 없는 폴더를 찾거나, 이미 끝낸 일을 다시 챙기려 든다면. AI한테 뭘 읽히고 있는지 한번 열어보세요.
