클로드 기초 및 활용 25회: CLAUDE.md 쓰는 법 — 매번 말하지 않아도 되는 규칙 파일

여러 번 예고했던 그 파일입니다

18회에서 "출력 길이 규칙을 적어 두면 된다"고 했고, 21회에서 "규칙은 대화가 아니라 파일에 두라"고 했고, 23회에서 /memory와 /init을 언급했습니다.

그 모든 예고가 가리키던 것이 CLAUDE.md입니다. 오늘 드디어 다룹니다.

이름은 낯설지만 정체는 간단합니다. 클로드가 작업을 시작할 때마다 읽는 안내문입니다.

오늘의 목표

오늘이 끝나면 할 수 있게 되는 것: CLAUDE.md를 만들고, 무엇을 적고 무엇을 적지 말아야 하는지 판단하고, 개인용과 프로젝트용을 구분해 쓸 수 있게 됩니다.

CLAUDE.md란 무엇인가

작업 폴더에 두는 일반 텍스트 파일입니다. 확장자 .md는 마크다운이라는 형식인데, 그냥 글로 적으면 됩니다. 특별한 문법을 몰라도 됩니다.

이 파일이 특별한 이유는 하나입니다. 클로드 코드가 작업을 시작할 때 이 파일을 읽습니다.

그래서 여기 적힌 내용은 매번 말하지 않아도 적용됩니다. 6회에서 배운 채팅의 개인 맞춤 지시와 같은 역할을, 클로드 코드에서는 이 파일이 합니다.

두 자리 — 개인용과 프로젝트용

24회의 스킬과 같은 구조입니다.

• 개인용: ~/.claude/CLAUDE.md — 어느 폴더에서 일하든 적용
• 프로젝트용: 작업 폴더의 CLAUDE.md — 그 폴더에서만 적용

둘 다 있으면 함께 적용됩니다. 개인용이 바탕이고 프로젝트용이 그 위에 얹힙니다.

고르는 기준도 같습니다. 나에 대한 것은 개인용, 이 일에 대한 것은 프로젝트용.

만드는 가장 쉬운 방법 — /init

빈 파일부터 시작할 필요 없습니다. 작업 폴더에서 클로드 코드를 실행하고 이렇게 치세요.

/init

클로드가 폴더를 살펴본 뒤 CLAUDE.md 초안을 만들어 줍니다. 이 폴더가 무슨 일을 하는 곳인지, 어떤 파일들이 있는지 파악해서 정리해 줍니다.

초안이 나오면 그걸 고쳐서 쓰면 됩니다. 백지보다 훨씬 쉽습니다.

고치는 방법 — /memory

이미 있는 파일을 고칠 때는 /memory를 치면 편집 화면이 열립니다.

또는 그냥 말로 고치셔도 됩니다. "CLAUDE.md에 이 규칙을 추가해 줘 — 답은 항상 다섯 줄 이내로."

이쪽이 더 쉽습니다. 파일을 직접 열 필요가 없으니까요.

🔴 무엇을 적나 — 다섯 갈래

가장 중요한 부분입니다. 이 다섯 가지가 잘 통합니다.

① 이 폴더가 무엇인지 — "이 폴더는 2026년 회계 자료를 모아 둔 곳입니다."

② 지켜야 할 규칙 — "원본 파일은 절대 수정하지 말고, 사본을 만들어 작업하세요."

③ 출력 방식 — "답은 짧게, 핵심부터. 파일 내용을 통째로 출력하지 마세요."

④ 이 분야의 용어 — "여기서 '마감'은 회계 마감을 뜻합니다. 일정 마감이 아닙니다."

⑤ 하지 말아야 할 것 — "'백업' 폴더는 읽기만 하고 절대 수정하지 마세요."

무엇을 적지 말아야 하나

세 가지입니다.

① 민감 정보. 6회·8회에서 다룬 기준이 그대로입니다. 비밀번호, 계좌번호, 개인 식별번호는 넣지 마세요. 이 파일은 폴더에 그대로 있는 평범한 텍스트 파일입니다. 폴더를 공유하면 함께 갑니다.

② 자주 바뀌는 정보. 8회에서 다룬 문제입니다. 갱신을 잊으면 오래된 정보로 작업하게 됩니다.

③ 너무 많은 내용. 다음 항목에서 따로 다룹니다.

🔴 길수록 나빠집니다

가장 흔한 실패이자, 직관과 반대되는 이야기입니다.

규칙을 많이 적을수록 잘 지켜질 것 같지만 반대입니다. 6회와 8회에서 이미 겪으신 문제입니다. 규칙이 너무 많으면 클로드가 규칙을 지키느라 경직되고, 정작 중요한 것이 묻힙니다.

권하는 분량: 처음에는 열 줄 이내로 시작하세요. 쓰면서 정말 필요한 것만 늘리세요.

그리고 한 달에 한 번 읽어 보고 안 쓰이는 규칙을 지우세요. 이게 더 중요합니다.

잘 통하는 적는 방식

같은 내용도 적는 방식에 따라 효과가 다릅니다.

모호한 표현: "깔끔하게 정리해 주세요." → 뭘 어떻게 하라는 건지 모릅니다.
구체적인 표현: "정리 결과는 항목마다 한 줄씩, 열 줄을 넘기지 마세요."

금지만 적기: "장황하게 쓰지 마세요." → 방향이 없습니다.
방향 주기: "핵심부터 쓰고, 부연은 필요할 때만."

5회에서 배운 "하지 마"보다 "이렇게 해"가 여기서도 그대로 적용됩니다.

이유를 함께 적으면 더 잘 지켜집니다

15회에서 규격 문서를 다룰 때 했던 이야기입니다. "왜"를 함께 적으세요.

"원본 파일은 수정하지 마세요."보다
"원본 파일은 수정하지 마세요. 회계 감사 때 원본 대조가 필요하기 때문입니다."

후자가 더 잘 지켜집니다. 그리고 새로운 상황에서 판단할 수 있게 됩니다. 규칙에 없는 상황이 와도 이유를 알면 맞게 행동합니다.

따라 하기 ① /init으로 초안 만들기

작업 폴더에서 /init을 실행하세요. 초안이 만들어집니다.

만들어진 내용을 읽어 보세요. 클로드가 이 폴더를 어떻게 이해했는지가 보입니다. 틀린 부분이 있으면 그것만으로도 유용한 정보입니다.

따라 하기 ② 규칙 세 줄 추가하기

초안에 여러분의 규칙 세 줄을 추가하세요. 말로 하면 됩니다.

"CLAUDE.md에 다음 세 가지를 추가해 줘. 첫째, 답은 짧게 핵심부터. 둘째, 파일을 고치기 전에 반드시 물어볼 것. 셋째, 원본 파일은 수정하지 말고 사본을 만들 것."

따라 하기 ③ 효과 확인하기

중요한 단계입니다. /clear로 대화를 비우고 새로 요청해 보세요.

아무 요청이나 하고, 답이 CLAUDE.md의 규칙을 따르는지 확인하세요. 짧게 나오는지, 고치기 전에 묻는지요.

따르지 않는다면 규칙이 모호하거나, 파일 위치가 잘못됐을 수 있습니다.

따라 하기 ④ 개인용 만들기

이번엔 어디서든 적용될 규칙입니다.

"개인용 CLAUDE.md를 만들어 줘. 내용은 — 나는 개발자가 아니다, 전문 용어는 처음 나올 때 풀어 쓸 것, 답은 짧게 핵심부터, 확실하지 않은 것은 확실하지 않다고 표시할 것."

이 네 줄이 모든 폴더의 모든 작업에 적용됩니다.

자주 겪는 오류 ① "규칙이 안 지켜져요"

네 가지를 확인하세요.

① 파일 위치 — 프로젝트용이라면 작업 폴더 바로 아래에 있어야 합니다.
② 구체성 — "적절히"나 "잘"이 들어간 규칙은 지킬 수가 없습니다.
③ 분량 — 규칙이 너무 많으면 묻힙니다. 줄이세요.
④ 충돌 — 개인용과 프로젝트용이 서로 다른 말을 하고 있을 수 있습니다.

오류 ② "답이 너무 뻣뻣해졌어요"

규칙을 너무 강하게 적은 경우입니다. 6회·8회에서 반복된 문제입니다.

"반드시 세 줄로"보다 "대체로 짧게, 필요하면 늘려도 좋음"이 낫습니다.

여지를 남기세요. 기준선은 못 박고 그 위에서는 자유롭게가 원칙입니다(15회).

오류 ③ "파일이 계속 길어져요"

겪었던 일을 하나씩 추가하다 보면 자연히 길어집니다. 주기적으로 덜어 내세요.

클로드에게 시킬 수 있습니다.

"CLAUDE.md를 읽고, 서로 겹치거나 지금은 불필요해 보이는 규칙이 있으면 알려 줘. 아직 지우지는 말고."

제안을 보고 판단해 지우면 됩니다.

오류 ④ "팀원과 공유했더니 문제가 생겼어요"

프로젝트용 CLAUDE.md는 폴더를 공유하면 함께 갑니다. 그래서 두 가지를 조심해야 합니다.

① 개인 취향을 프로젝트용에 넣지 마세요. "나는 개발자가 아니다" 같은 것은 개인용에 넣습니다. 프로젝트용에는 모두에게 해당하는 규칙만.

② 민감 정보 재확인. 공유되는 파일이라는 사실을 잊지 마세요.

실전 사례 ① 자료 폴더용

회계·계약 등 원본이 중요한 폴더의 예시입니다.

"이 폴더는 2026년 계약서 원본을 보관하는 곳입니다.
— 원본 파일은 절대 수정하지 마세요. 감사 대조에 쓰이기 때문입니다.
— 작업이 필요하면 '작업본' 폴더에 사본을 만들어 거기서 하세요.
— 파일 이름은 '연도-월_거래처_문서종류' 형식입니다. 새로 만들 때도 이 형식을 지켜 주세요.
— 금액과 날짜는 원문 그대로 옮기고, 임의로 반올림하거나 형식을 바꾸지 마세요."

다섯 줄이지만 사고를 막는 다섯 줄입니다.

실전 사례 ② 글쓰기 폴더용

"이 폴더는 블로그 원고를 쓰는 곳입니다.
— 독자는 이 분야를 처음 접하는 일반인입니다. 전문 용어는 처음 나올 때 한 줄로 풀어 주세요.
— 문체는 존댓말, 담백하게. 이모지는 쓰지 마세요.
— 초안은 짧게 잡고, 제가 방향을 확인한 뒤에 늘려 주세요.
— 'style.md'에 문체 규격이 있습니다. 글을 쓸 때 참고해 주세요."

마지막 줄에 주목하세요. 다른 파일을 가리키는 것도 됩니다. 15회에서 만든 디자인 규격을 이렇게 연결할 수 있습니다.

실전 사례 ③ 저시력 사용자를 위한 개인용 CLAUDE.md

이 시리즈에서 계속 나눠 이야기한 것들이 여기서 하나로 모입니다. 개인용 CLAUDE.md에 이 내용을 넣어 두시면, 모든 폴더의 모든 작업에 적용됩니다.

권하는 내용:

"나는 화면을 크게 확대해서 사용합니다. 다음을 지켜 주세요.
— 답은 짧게, 핵심부터. 다섯 줄을 기준으로 하되 꼭 필요하면 늘려도 됩니다.
— 파일 내용을 통째로 출력하지 말고 요약해 주세요. 전체가 필요하면 제가 요청하겠습니다.
— 진행 상황은 한 줄씩만 알려 주세요. 무엇을 왜 하는지가 중요하고, 세부 과정은 필요 없습니다.
— 작업이 끝나면 마지막에 전체 요약을 한 번 주세요.
— 목록은 다섯 항목을 넘기지 마세요. 더 있으면 나눠서 알려 주세요.
— 표는 꼭 필요할 때만 쓰고, 쓸 때는 아래에 같은 내용을 문장으로도 적어 주세요."

마지막 줄이 특별합니다. 표는 확대 환경이나 화면 낭독에서 읽기 어려운 형태입니다. 같은 내용을 문장으로도 받으면 그 문제가 해결됩니다.

이 여섯 줄을 한 번 적어 두면, 앞으로 모든 작업에서 매번 말할 필요가 없습니다. 이 시리즈에서 배운 접근성 요청들이 자동으로 적용되는 것입니다.

핵심 정리 3줄

• /init으로 시작하세요. 백지보다 초안을 고치는 편이 훨씬 쉽습니다.
• 열 줄 이내로 시작하고, 정기적으로 덜어 내세요. 길수록 나빠집니다.
• "왜"를 함께 적으세요. 이유를 알면 규칙에 없는 상황도 맞게 판단합니다.

용어 정리

• CLAUDE.md — 클로드 코드가 작업 시작 시 읽는 안내문 파일.
• /init — 폴더를 살펴 CLAUDE.md 초안을 만들어 주는 명령.
• /memory — CLAUDE.md를 편집하는 화면을 여는 명령.
• 개인용 / 프로젝트용 — 전자는 모든 폴더에, 후자는 그 폴더에만 적용됩니다.
• 마크다운(.md) — 간단한 텍스트 형식. 문법을 몰라도 그냥 글로 적으면 됩니다.

다음 회차 예고와 실습 과제

26회 「명령어 활용 예시 모음」에서는 제5부를 마무리하며 상황별 레시피를 모읍니다. "이럴 땐 이 명령" 형태로 정리하고, 명령들을 조합해 쓰는 방법도 다룹니다. 22~25회에서 배운 것들이 실제 작업 흐름으로 엮이는 회차입니다.

실습 과제 두 가지

• ① 작업 폴더에서 /init을 실행하고, 규칙 세 줄을 추가한 뒤 /clear 후 효과를 확인해 보세요.
• ② 개인용 CLAUDE.md를 만들어 여러분에게 필요한 규칙 서너 줄을 넣어 보세요. 짧게 시작하는 것이 요령입니다.

①번에서 /init 초안이 여러분의 폴더를 잘못 이해한 부분이 있었다면 댓글로 남겨 주세요. 어떤 폴더에서 그런 일이 생기는지 알아 두면 유용합니다.

본 회차는 2026년 8월 2일 기준입니다. CLAUDE.md의 위치와 동작 방식은 버전에 따라 바뀔 수 있습니다. 이 파일은 폴더에 그대로 저장되는 평범한 텍스트 파일이므로, 폴더를 공유할 때 함께 전달된다는 점을 유의하시기 바랍니다.

협업문의 : kuroicode@gmail.com
블로그 : https://ghost-production-0ec2.up.railway.app/
홈페이지 : https://kuroicode-beep.github.io/svil-homepage/