CLAUDE.md 제대로 쓰기

지난 강의 끝에서 이상한 걸 봤어요. 대화를 /clear로 통째로 지웠는데, 에이전트가 여전히 규칙을 지켰죠.

시즌 1에서 다섯 줄 적어둔 CLAUDE.md 덕분이에요. 그때는 "규칙을 적어두면 기억한다" 정도로만 알고 넘어갔어요.

오늘은 그 파일을 제대로 씁니다. 그리고 더 중요한 걸 배워요. 적어둔다고 다 지켜지는 게 아니라는 것.

오늘 만들 것

두 개의 규칙 파일. 하나는 이 프로젝트만의 규칙, 하나는 모든 프로젝트에 통하는 내 규칙.

그리고 규칙이 진짜로 작동하는지 새 대화에서 시험해본 경험.

준비물

• 시즌 2의 1강을 마친 상태 (/clear와 /compact를 써 봤어요)
• 시즌 1에서 만든 my-page 폴더
• 30분

따라 하기

1. 초안을 받아보기

빈 종이에서 시작하지 않아도 돼요. 에이전트가 프로젝트를 훑어보고 초안을 써 줍니다.

my-page 폴더를 연 상태에서 이걸 치세요.

/init

에이전트가 폴더의 파일들을 읽고 CLAUDE.md 초안을 만들어요. 이 프로젝트가 뭘 하는 건지, 어떤 파일이 있는지 요약해 두죠.

2. 초안을 의심하기

여기서 대부분이 실수해요. 초안을 그대로 두는 거요.

초안을 읽으세요. 에이전트가 짐작으로 쓴 줄이 반드시 있어요. 없는 파일을 언급하거나, 내가 안 쓰는 도구를 적어두거나요.

사실이 아닌 줄은 지우세요. 규칙 파일에 거짓말이 한 줄 있으면, 에이전트는 그 거짓말을 근거로 판단해요.

시즌 1에서 적었던 다섯 줄도 여기로 옮겨 정리하세요.

3. 지켜지는 규칙과 무시되는 규칙

이게 오늘의 절반이에요.

규칙에는 두 종류가 있어요. 에이전트가 판단할 수 있는 규칙과, 판단할 수 없는 규칙.

무시되는 규칙이에요.

• "깔끔하게 만들어 줘"
• "예쁘게 해 줘"
• "좋은 코드를 써 줘"

무엇이 깔끔한 건지 기준이 없어요. 에이전트는 이 문장을 읽고도 아무것도 바꿀 수 없어요.

지켜지는 규칙이에요.

• "HTML과 CSS는 index.html 한 파일에 유지할 것"
• "한 번에 한 가지만 바꾸고, 뭘 바꿨는지 알려줄 것"
• "큰 변경 전에는 먼저 물어볼 것"
• "전문 용어를 쓸 때는 한 줄로 풀어서 설명할 것"

각각 지켰는지 안 지켰는지 눈으로 확인할 수 있어요. 그게 차이예요.

내 CLAUDE.md를 열어서, 확인할 수 없는 문장을 찾아 고치세요.

CLAUDE.md를 읽고, 지켰는지 안 지켰는지 눈으로 확인할 수 없는 규칙을
찾아 줘. 각각을 확인 가능한 문장으로 어떻게 바꾸면 좋을지 제안해 줘.

내가 고르면 그때 고쳐 줘. 지금 바로 고치지는 마.

4. 규칙에도 자리가 있다

규칙 파일은 한 곳이 아니에요. 크게 두 자리예요.

프로젝트 규칙 — my-page 폴더 안의 CLAUDE.md. 이 프로젝트에서만 통해요. "index.html 한 파일 유지" 같은 것.

내 규칙 — 홈 폴더의 ~/.claude/CLAUDE.md. 어떤 프로젝트를 열든 따라와요. "항상 한국어로 답할 것", "전문 용어는 풀어서 설명할 것" 같은 것.

지금 my-page의 규칙을 보면 두 종류가 섞여 있을 거예요. 나눠주세요.

지금 프로젝트의 CLAUDE.md를 읽고, 규칙을 두 묶음으로 나눠 줘.

1. 이 프로젝트에만 해당하는 것 → 프로젝트 CLAUDE.md에 남길 것
2. 어떤 프로젝트에서든 내가 원하는 것 → 개인 설정으로 옮길 것

나눈 결과를 먼저 보여 주고, 내가 확인하면 실제로 옮겨 줘.
개인 설정 파일의 위치도 알려 줘.

한국어로 답하라는 규칙을 프로젝트마다 다시 적고 있었다면, 오늘로 끝이에요.

편집은 이걸로도 할 수 있어요.

/memory

5. 규칙을 시험하기

적어뒀다고 끝이 아니에요. 작동하는지 확인해야 해요.

먼저 도마를 치웁니다.

/clear

그리고 일부러 규칙을 어기는 요청을 넣으세요.

CSS를 style.css 파일로 따로 빼 줘.

CLAUDE.md에 "한 파일 유지"를 적어뒀다면, 에이전트가 그냥 하지 않아요. 규칙을 언급하며 정말 할지 되물을 거예요.

되묻지 않고 그냥 했다면, 규칙이 작동하지 않는 거예요. 이유는 보통 셋 중 하나예요.

• 파일 이름이 정확히 CLAUDE.md가 아니거나
• 파일이 프로젝트 폴더의 맨 위가 아니라 하위 폴더에 있거나
• 규칙 문장이 확인 불가능한 종류거나

고치고 다시 시험하세요. 시험을 통과할 때까지가 오늘 할 일이에요.

6. 규칙은 자라난다

한 번에 완벽하게 쓰려고 하지 마세요. 규칙은 짜증에서 태어나요.

같은 말을 두 번 했다면, 그게 규칙 후보예요. 에이전트가 매번 하는 실수가 있다면, 그것도요.

앞으로 이렇게 하세요.

방금 내가 두 번 말한 걸 CLAUDE.md에 규칙으로 추가해 줘.
확인 가능한 문장으로.

막혔을 때

/init이 없다고 나와요. 괜찮아요. 초안 없이 직접 시작하면 돼요. "이 폴더를 읽고 CLAUDE.md 초안을 만들어 줘"라고 말로 시켜도 결과는 비슷해요.

/init이 만든 초안이 너무 길어요. 지우세요. 규칙 파일은 짧을수록 좋아요. 안 지켜질 규칙 스무 줄보다 지켜지는 다섯 줄이 나아요.

규칙을 적었는데 에이전트가 무시해요. 위의 5번 세 가지를 확인하세요. 그래도 안 되면 규칙 문장이 모호한 거예요. "적절히", "필요하면", "가능하면" 같은 단어가 들어 있는지 보세요. 그 단어들이 규칙을 무력화해요.

개인 설정 파일을 어디에 만들어야 할지 모르겠어요. 에이전트에게 물어보세요. "내 개인 CLAUDE.md는 어디에 만들면 되는지 정확한 경로를 알려 줘." 운영체제마다 달라서 직접 알려주는 게 확실해요.

규칙이 서로 충돌해요. 프로젝트 규칙과 개인 규칙이 다른 말을 하면 헷갈려요. 개인 규칙에는 취향(말투, 언어)만 두고, 작업 방식은 프로젝트 규칙에 두세요.

마무리 체크

나가기 전에 하나씩 확인해요:

• /init 초안을 받아서 사실이 아닌 줄을 지웠어요
• 확인 불가능한 규칙("깔끔하게")을 확인 가능한 문장으로 고쳤어요
• 프로젝트 규칙과 내 개인 규칙을 나눠 뒀어요
• /clear 후 일부러 규칙을 어기는 요청을 넣어 되묻는 걸 확인했어요
• 규칙 파일이 스무 줄을 넘지 않아요

네 번째가 핵심이에요. 시험하지 않은 규칙은 규칙이 아니라 희망사항이에요.

이제 에이전트가 내 취향을 알아요. 다음은 순서예요. 시키기 전에 계획을 먼저 받아보고, 바꾼 걸 확인한 다음 승인하는 법.