CLAUDE.md 정리를 한 번도 안 했다면 점검해볼 만하다. Claude Code(AI 코딩 도우미)를 쓰다 보면 어느 순간 CLAUDE.md 파일이 여러 개가 된다. 내 환경에는 세 개가 있었다. 그냥 두면 되는 줄 알았는데 점검해보니 아니었다.
CLAUDE.md가 뭐고 왜 여러 개일까?
CLAUDE.md는 Claude Code가 세션(session, 작업을 시작하고 끝내는 한 번의 대화 구간)을 시작할 때 자동으로 읽는 설정 파일이다. “나는 이렇게 일하는 사람이야, 이 규칙을 따라줘”라고 클로드에게 미리 알려두는 메모다.
문제는 이 파일이 한 군데만 있는 게 아니라는 점이다. Claude Code는 공식 문서에 나온 것처럼 여러 위치에서 CLAUDE.md를 찾는다. 홈 폴더(~/CLAUDE.md), 전역 설정 폴더(~/.claude/CLAUDE.md), 그리고 각 프로젝트 폴더 안의 CLAUDE.md까지.
내 세 파일은 ~/CLAUDE.md, ~/.claude/CLAUDE.md, 자동화 프로젝트 폴더의 CLAUDE.md였다. 그래서 클로드에게 직접 점검을 시켰다. 파일 내용을 실제 폴더와 대조해서 읽고, 수정하거나 지워도 되는 부분이 있으면 알려달라고 했다.
CLAUDE.md 정리 전 점검: 세 파일에서 나온 문제
세 파일 모두 문제가 있었다. 종류는 달랐다.
~/CLAUDE.md는 131줄짜리 파일이었다. 클로드가 읽고 나서 이상한 걸 발견했다. 1번 줄과 67번 줄에 똑같이 # CLAUDE.md라는 제목이 있었다. 1~65줄과 67~131줄을 비교했더니 완전히 같은 내용이었다. 같은 지침 블록이 두 번 들어가 있었다는 뜻이다.
위는 정리 전 131줄, 정리 후 65줄과 두 블록 비교 결과를 찍은 화면이다. 왜 두 번 들어갔는지 원인은 지금도 모른다.
자동화 프로젝트 CLAUDE.md에는 다른 문제가 있었다. workflows/ 폴더를 전제로 한 규칙이 세 곳에 흩어져 있었다. “Workflow는 내 허락 없이 새로 만들거나 삭제하지 마”, 에러 처리 절차의 ‘Workflow 업데이트’, 보안 절의 ‘Workflow’ 표현. 그런데 workflows/ 폴더가 실제로 없었다. 폴더는 사라졌는데 규칙은 그대로 남아 있었다.
CLAUDE.md 정리 중 만난 NotebookLM 지시 문제
~/.claude/CLAUDE.md는 또 다른 문제였다. 세션 시작 때 NotebookLM(구글의 AI 노트 정리 도구) 노트북을 먼저 검색하라고 되어 있었다. 그런데 NotebookLM 연결은 로그인 감지 버그와 구글 장애로 2026-09-01부터 막혀 있었다. 매 세션마다 실패할 게 뻔한 명령이 설정에 그냥 살아 있었던 거다.
위는 전역 CLAUDE.md의 NotebookLM 지시를 고친 변경 부분이다.
그 외에 자동화 프로젝트 CLAUDE.md에 ‘실제 사용 중인 블로그는 tistory 1개뿐’이라고 적혀 있었다. 지금 이 블로그, ujinify.com이 훨씬 더 활발히 쓰는 프로젝트인데도 설정에는 반영이 안 되어 있었다.
CLAUDE.md 정리 첫 단계: 중복 찾는 쉘 명령어
쉘(shell, 명령어를 입력해서 컴퓨터에게 일을 시키는 창)에서 두 가지 명령어로 확인할 수 있다.
먼저 파일이 몇 줄인지 센다.
wc -l ~/CLAUDE.md, 줄 수를 보여준다. wc는 ‘word count’의 줄임말이다.grep -n '^# ' ~/CLAUDE.md, 파일 안에서#으로 시작하는 제목 줄을 찾아서 몇 번째 줄인지 함께 보여준다. grep은 파일 안에서 특정 단어나 패턴을 찾는 명령어다.
내 경우에는 grep 결과에 # CLAUDE.md가 1번 줄과 67번 줄, 두 군데 나왔다. 같은 제목이 두 번 뜨면 중복을 의심해야 한다. 그다음엔 두 블록의 내용이 실제로 같은지 확인해야 한다.
앞 블록과 뒤 블록을 비교하는 짧은 스크립트(script, 명령어를 순서대로 묶어둔 파일)를 돌렸다. 완전히 같다는 결과가 나왔고, 그래서 뒤 블록을 지웠다.
자기 파일에서 확인하려면 이 순서로 해보면 된다. wc -l로 줄 수 확인 → grep -n '^# '로 제목 위치 확인 → 같은 제목이 두 군데 이상 있으면 두 블록 내용 비교. 간단하다.
CLAUDE.md 정리에서 없는 폴더 규칙 지우기
workflows/ 폴더가 실제로 없다는 걸 어떻게 확인했냐고 하면, ls 명령어로 봤다. ls는 폴더 안에 뭐가 있는지 목록으로 보여주는 명령어다. 없으면 없다고 나온다.
있어야 할 폴더가 없으면 그 폴더를 전제로 한 규칙은 전부 의미가 없다. 클로드가 “Workflow 삭제 전 허락을 받아야 한다”는 규칙을 읽어도, 지킬 대상이 없다. 그냥 노이즈다.
위는 workflows 폴더가 없다는 결과와 정리 전후 ‘Workflow’ 문구 검색 결과다.
수정 전에 파일을 /tmp에 백업했다. /tmp는 임시 파일을 저장하는 폴더다. 백업 없이 수정하지 마라. 잘못 지우면 돌아올 방법이 없다.
백업 뒤에 workflows/ 관련 문구를 세 곳 모두 지웠다. 113줄이던 파일이 106줄이 됐다.
파일 구조를 설명하는 절도 실제와 달랐다. tools/ 폴더에 파이썬(.py)과 타입스크립트(.ts) 파일이 섞여 있고, 새 코드는 타입스크립트로 작성된다는 실제 구조로 고쳤다. ujinify를 활성 블로그 목록에 올리고, 폐기된 프로젝트 목록은 4줄로 줄였다. 보관 방침은 그대로 뒀다.
실제 안 쓰는 도구 지시는 지우기로 했다
NotebookLM 지시는 지울지 남길지 갈렸다. 연결이 복구되면 다시 켜야 해서, 재개 규칙까지 통째로 지우면 나중에 처음부터 다시 써야 한다.
그래서 지우지 않고 ‘보류 중’으로 바꿨다. 지시 자체는 남겨두고, 현재 상태를 주석처럼 표시한 거다. 연결이 복구되면 ‘보류 중’ 표시만 지우면 된다. 재개 규칙은 그대로 살아 있다.
이건 판단의 문제다. 완전히 폐기된 도구라면 지우는 게 맞다. 일시 중단 상태라면 보류 표시를 남겨두는 쪽이 낫다. 어느 쪽이든 원칙은 하나다. 지금 작동하지 않는 도구에 대한 지시가 설정에 살아 있으면 클로드는 매 세션마다 실패할 명령을 실행하려 한다. 그 부분만큼은 반드시 정리해야 한다.
ujinify 전용 CLAUDE.md를 새로 만든 이유
점검하면서 ujinify 블로그 파이프라인 폴더에 전용 CLAUDE.md를 새로 만들기도 했다. 여기저기 흩어져 있던 규칙들, 글 내용 규칙, 이미지 캡처 규칙, 랭크매스 점수 규칙, 릴스·링크 처리 순서를 한 파일에 모았다.
알려진 문제도 적었다. 이미지 캡션과 사실을 지어내는 문제, 랭크매스 포커스 키워드가 REST로 저장되지 않는 문제. 고친 게 아니라 기록한 거다. 기록해두지 않으면 클로드도 나도 같은 실수를 반복한다.
정리 후 나한테 달라진 점, 너도 확인해보는 방법
솔직하게 말하겠다. CLAUDE.md 정리 후 확인한 건 줄 수뿐이다. ~/CLAUDE.md가 131줄에서 65줄이 됐다. 프로젝트 CLAUDE.md가 113줄에서 106줄이 됐다. 그게 다다.
응답이 빨라졌는지, 컨텍스트가 몇 토큰 줄었는지는 측정하지 않았다. 그래서 효과는 “읽는 분량이 줄었다”까지만 말할 수 있다. 더 좋아졌다고 단정하지 않겠다.
내 환경의 CLAUDE.md 정리 상태 확인하는 법
자기 환경에서 확인하고 싶다면 세 가지만 해보면 된다.
wc -l로 CLAUDE.md 줄 수를 세고,grep -n '^# '로 같은 제목이 반복되는지 확인한다.- CLAUDE.md 안에 언급된 폴더 이름을 찾아서
ls로 실제로 있는지 확인한다. - 세션 시작 때 실행하라고 적어둔 도구가 지금도 작동하는지 직접 돌려본다.
나는 이 세 가지에서 각각 문제가 나왔다. 처음 점검해보는 사람이라면 하나쯤은 걸릴 거라고 본다. 오래된 설정일수록 더 그렇다.
스킬과 메모리 폴더를 정리한 이야기는 Claude Code 스킬 정리 후기에 적어뒀다.
다음엔 새로 만든 ujinify 전용 CLAUDE.md가 실제로 잘 작동하는지 확인할 차례다. 규칙을 모아두는 것과 클로드가 그 규칙을 제대로 따르는 것은 다른 얘기다. 그 부분은 좀 더 써봐야 안다.
