Claude Code

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가 실제로 잘 작동하는지 확인할 차례다. 규칙을 모아두는 것과 클로드가 그 규칙을 제대로 따르는 것은 다른 얘기다. 그 부분은 좀 더 써봐야 안다.

예약 발행 기능이 없어서 매번 이렇게 됐다. 월요일 아침마다 똑같은 일을 반복하고 있었다. 글 하나 급하게 다듬고, 올리고, 끝. 그게 매주였다.

왜 그때그때 올리는 방식에 불만을 느꼈을까?

문제는 비효율이었다. 월요일이 될 때마다 그날 올릴 글 하나를 챙기는 방식은 솔직히 별로였다. 한 번 집중해서 여러 편을 미리 써뒀는데, 그걸 굳이 하나씩 날짜 맞춰 손으로 올려야 한다는 게 이상했다.

그래서 방향을 바꿨다. 한 주치 분량을 미리 정해두고, 날짜에 맞춰 자동으로 나가게 하는 구조가 낫다고 판단했다. 어느 월요일 아침, Claude Code에 바로 요청했다. “이번 주 수요일, 토요일, 다음 주 수요일, 토요일. 4개 예약 발행 하고 싶은데 가능해?”

가능하지 않았다.

예약 발행 기능이 없다면 직접 만들어야 한다

업로드 스크립트(script, 자동으로 실행되는 명령어 묶음)에는 예약 발행 기능 자체가 없었다. 초안(draft, 공개 전 임시 저장 상태)으로 올리는 것만 됐다. 특정 날짜에 자동으로 글이 나가도록 하는 옵션은 아예 존재하지 않았다.

당연히 있을 거라고 생각했다. 없어서 좀 당황스럽긴 했지만! 근데 어쩔 수 없다. 이것 역시 내가 지금까지 겪었던 것처럼 없으면 만들면 된다.

그 자리에서 바로 Claude Code에 추가 구현을 요청했다. 기존 스크립트를 고쳐서 날짜를 지정하면 그 시각에 발행되도록 하는 옵션을 넣는 작업이었다.

–schedule 옵션을 추가한 과정

Claude Code에게 요청한 방향은 단순했다. 기존 업로드 스크립트에 --schedule 옵션(option, 명령어를 실행할 때 추가로 붙이는 설정값)을 새로 추가해 달라는 것이었다. 날짜를 함께 넘기면 해당 시각에 발행되는 구조다.

예를 들어 이런 식이다.

• 기존 방식: 스크립트를 실행하면 바로 발행되거나 초안으로 저장
• 추가된 방식: --schedule 2025-07-09처럼 날짜를 붙이면 그 날짜에 자동 발행

Claude Code가 기존 코드 구조를 파악하고 옵션을 붙이는 로직(logic, 기능이 작동하는 규칙과 흐름)을 추가했다. 내가 직접 코드를 짠 게 아니다. 요청했고, 결과를 확인했다. 그게 전부였다.

기능 자체는 복잡하지 않았다. 처음부터 있었어야 했다고 생각한다.

4개 글을 한 번에 처리하려면 기준을 낮춰야 현실적이다

SEO(Search Engine Optimization, 검색엔진 최적화) 점수 기준 얘기를 해야 한다. 평소에는 랭크매스 기준 80점을 맞추고 올렸다.

이번엔 달랐다. 한 번에 4개를 처리해야 했다. 4개 전부 80점을 맞추려고 시간을 쓰다 보면 예약 발행의 의미가 없어진다. 그래서 기준을 낮췄다. 70점 이상이면 올린다고 정했다.

Claude Code에 요청할 때도 명확하게 전달했다. “랭크매스는 70점 이상만 맞춰줘.” 완벽하게 다듬는 것보다 4개를 제때 내보내는 게 이번의 목표였다.

기준을 낮추는 게 맞냐 틀리냐의 문제가 아니다. 현실적인 선택이었다. 한 번에 처리하는 분량이 늘어나면 기준도 거기에 맞게 조정해야 한다. 그렇지 않으면 결국 아무것도 못 올린다.

실제로 예약 발행을 돌려본 결과

4개 글을 한 번에 예약 걸었다. 이번 주 수요일, 토요일, 다음 주 수요일, 토요일. 각각 날짜를 지정해서 스크립트를 돌렸다.

작동했다. 상태가 “future”로 바뀌면서 예약이 정상적으로 걸린 걸 확인했다. 이제 지정한 날짜가 되면 자동으로 발행된다. 월요일 아침에 급하게 뭔가를 챙기는 일은 없어졌다.

다만 솔직히 말하면, 70점 기준으로 올린 글들이 80점짜리보다 성과가 어떻게 다를지는 아직 모른다. 데이터가 쌓여야 안다. 지금은 그냥 지켜보는 중이다.

예약 발행 자체는 앞으로도 유지할 생각이다. 그때그때 올리는 방식으로는 안 돌아간다. 미리 묶어서 처리하는 게 훨씬 낫다. 다음엔 4개가 아니라 더 늘릴 수 있을지 한번 봐야겠다.