claude.md 작성방법 2026, 써 놔도 안 지키는 줄은 검사로 옮기세요

claude.md 작성방법에서 제일 먼저 알아야 할 건 하나입니다. 클로드는 이 파일을 '지켜야 할 법'이 아니라 '참고할 메모'로 읽어요. 공식 문서에 그렇게 적혀 있습니다. 그래서 길게 더 쓰는 것보다, 꼭 지켜야 할 줄을 골라 검사로 옮기는 쪽이 효과가 큽니다.

 

오늘 글 네 줄

• 공식 권장: claude.md 는 파일당 200줄 이하, 길수록 덜 지킴
• "잘 해라" 대신 "태그는 6~10개"처럼 확인되는 문장으로
• 개수·길이·포함 여부는 검사 파일로 옮겨 걸리면 멈추게
• 이 계정 규칙 파일 12개 1,512줄, 가장 긴 건 393줄(10월 27일)

스레드에서 이런 하소연을 봤습니다. 규칙 파일에 원칙을 다 적어 뒀는데 클로드가 매번 같은 AI 말투로 돌아온다는 거죠. 디자인 문서를 꼭 보라고 적었더니 "시간이 걸려서 안 읽었다"는 답이 돌아왔다는 분도 있었죠. 파일을 대충 써서 생긴 일이 아닙니다. 파일이 원래 그렇게 읽힙니다.

써 놨는데 안 지킨다면, 한 줄씩 세 갈래로

이 블로그를 쓰는 예약 작업의 규칙 맨 앞에는 이런 문장이 있습니다. 라벨 규칙, 발행 금지, 중복 주제 피하기 모두 지시문으로는 안 지켜지다가 코드로 막고서야 지켜졌다고요. 그래서 줄마다 '기계가 잴 수 있나'부터 묻습니다. 잴 수 있으면 검사로 보내고, 매번 알아야 하는 사실만 파일에 남깁니다.

아래 단락을 클로드 코드에 그대로 붙이면 같은 정리를 해 줍니다. 대괄호 안만 내 것으로 바꾸면 됩니다.

[내 CLAUDE.md 경로]를 읽고 줄마다 셋 중 하나로 분류해 표로 보여 줘. ① 개수·길이·포함 여부·형식처럼 기계가 판정할 수 있는 것 ② 매 작업마다 알아야 하는 사실·주소·순서 ③ 특정 작업에서만 쓰는 긴 절차. ①은 [작업 폴더]/check.py 에 검사로 옮기고 원래 줄은 지워. check.py 는 원고 파일 하나를 받아 어긴 항목을 한 줄씩 출력하고, 하나라도 있으면 종료 코드 1로 끝내. ②는 남기되 지켰는지 확인되는 한 문장으로 고쳐. ③은 [작업 폴더]/rules/ 아래 주제별 파일로 옮기고 CLAUDE.md 에는 그 파일 경로 한 줄만 남겨. 다 하면 CLAUDE.md 가 200줄 이하인지 세고, 마지막 줄에 "결과물을 저장하기 전에 python3 check.py 를 돌리고 1이면 고친 뒤 다시 돌린다"를 넣어. 서로 부딪히는 규칙이 있으면 고치지 말고 나한테 먼저 물어봐.

이 단락이 해 주는 건 규칙 파일 하나를 검사 하나로 바꾸는 데까지입니다. 매일 글을 올리면서 실제로 터진 실수 11가지를 날짜째 적고, 그걸 막으려고 만든 자동 검사 20가지, 같은 주제·겹치는 글을 잡는 검사 코드, 코딩 없이 대화창에 붙여 쓰는 검사 지시문은 제가 만든 책에 묶었습니다. 검사를 너무 빡빡하게 만들어 멀쩡한 글까지 막았던 날과, 그 뒤로 '막을 것'과 '알려만 줄 것'을 나눈 기준도 들어 있습니다. 오늘(10월 27일) 상품 페이지 기준 A4 19쪽 PDF에 9,900원이고, 앞 4쪽은 결제 없이 볼 수 있습니다.

 

자동 검사 20가지 목차 4쪽 넘겨 보기

아직 예약 작업도 안 만들었다면, 지시서·기억 파일 틀이 든 0원짜리 5쪽 맛보기가 순서상 먼저입니다.

 

 

클로드 md 만드는 방법, 첫 장은 이렇게

클로드 코드에서 /init 을 치면 지금 폴더를 훑어보고 시작용 CLAUDE.md 를 만들어 줍니다. 모든 작업에 쓸 내 습관은 ~/.claude/CLAUDE.md, 한 폴더에만 쓸 규칙은 그 폴더의 CLAUDE.md 에 둡니다. 제대로 읽혔는지는 /context 를 쳐서 Memory files 목록에 그 파일이 있는지로 확인하면 됩니다(클로드 코드 공식 문서, 10월 27일 열람).

문장은 확인할 수 있게 씁니다. "글을 자연스럽게"는 클로드가 지켰는지 본인도 모릅니다. "첫 문장에 검색어를 그대로"는 지켰는지 한눈에 보여요.

반대로, 검사로 보내면 안 되는 줄

말투가 사람 같은지, 숫자가 사실인지는 기계가 확실히 못 잽니다. 이런 줄까지 검사로 막으면 멀쩡한 글이 멈춥니다. 그래서 우리 검사는 둘로 나뉩니다. 요약 상자·질문 칸·버튼이 빠지는 건 확실하니 고칠 때까지 다음 단계로 안 넘어가고, 서브 검색어가 본문에 있는지 같은 애매한 건 경고만 띄운 채 한 번 고치고 올립니다. 10월 10일에 "검사가 발행을 멈추면 안 된다"고 정한 뒤로 이렇게 돌고 있습니다.

claude.md 관리 방법, 우리 파일도 393줄이었습니다

이 글을 쓰면서 줄 수를 직접 세어 봤습니다. 규칙 파일은 12개로 나눠 뒀는데 합치면 1,512줄이고, 티스토리 발행 규칙 하나가 393줄입니다. 공식 권장의 두 배쯤입니다. 지적받을 때마다 한 절씩 붙인 결과라, 남 얘기가 아니었던 거죠.

줄이는 기준은 공식 문서에 있습니다. 두 규칙이 서로 부딪히면 클로드가 아무거나 하나를 고를 수 있으니 오래된 줄부터 지우고, 사람만 볼 메모는 <!-- --> 주석으로 감싸면 클로드가 읽는 분량에서 빠집니다. 부딪히는 줄을 찾아 주는 /doctor prompt-audit 은 2.1.283 이상에서 되는데, 이 계정은 2.1.201이라 아직 못 돌려 봤습니다.

끝까지 안 지키면 도구를 빼세요

8월 27일, 글만 쓰라고 시킨 보조 에이전트가 예약 작업을 하나 새로 만든 일이 있었습니다. "만들지 마"를 적는 대신 그 에이전트에게 예약 도구 자체를 안 주는 걸로 끝냈어요. 클로드 코드에서는 특정 행동을 실행 전에 막는 훅(정해진 순간마다 자동으로 도는 검사)이 그 역할을 한다고 공식 문서가 안내합니다.

규칙 파일 정리할 때 나오는 질문

클로드 md 파일 사용 방법, 프로젝트마다 따로 써야 하나요?

모든 작업에 같은 습관은 ~/.claude/CLAUDE.md 한 곳에, 그 폴더에만 해당하는 건 폴더 안 CLAUDE.md 에 둡니다. 둘 다 읽히고, 작업 폴더 쪽이 나중에 읽힙니다.

claude.md 작성방법, "반드시"를 붙이면 더 잘 지키나요?

공식 문서가 꼽는 건 강조가 아니라 구체적이고 짧은 문장이에요. 꼭 지켜야 하면 문장을 세게 쓰기보다 검사로 옮기는 게 확실해요.

검사 파일은 코딩을 몰라도 만들 수 있나요?

위 단락처럼 클로드에게 만들어 달라고 하면 됩니다. 이 계정의 검사 파일도 클로드와 대화하며 만들었고, 사람은 "무엇을 막을지"만 정했습니다.

검사를 붙였는데도 "성공"이라 떠 놓고 글이 안 올라간 날이 있다면, 성공이라 떠도 안 올라간 여섯 번이 바로 다음 이야기입니다. 말투가 자꾸 똑같아지는 쪽이 더 급하면 글이 다 비슷해질 때 바꾼 순서를 먼저 보세요.

파일이 200줄 아래라면 문장만 확인 가능하게 고치면 되고, 넘는다면 오늘은 ③번 절차부터 따로 빼는 게 제일 빨리 줄어듭니다.