클로드가 우리 팀 방식대로 일하게 — 규칙 파일 심기 (CLAUDE.md)

클로드는 대화를 닫으면 「우리 팀은 이렇게 쓴다」는 말을 잊습니다. 그래서 같은 부탁을 매번 새로 칩니다. 그 부탁을 규칙 파일에 한 번 적어 두면, 클로드가 새 대화를 열 때마다 먼저 읽습니다. 아래 말을 순서대로 한 줄씩 치면 됩니다. (예시 자료는 가짜 이름입니다.)

시작 전에

• 빈 폴더 하나를 만들고(이름은 영문으로, 예: 문서 폴더 안 weekly-report), 그 폴더에서 클로드(Claude Code)를 엽니다. 데스크톱 앱이면 Code 탭에서 Local → Select folder, 터미널이면 그 폴더 안에서 claude 를 입력합니다. 설치·구독은 아래 「준비물 자세히」에 있습니다. 02편에서 쓴 작업 폴더를 그대로 써도 되지만, 이 편은 새 폴더가 깔끔합니다.
• 클로드가 파일을 만들 때 허락을 묻는 창이 뜨면 무엇을 쓰는지 읽고 허락하세요. 처음에는 이렇게 묻는 방식(Manual)이 안전합니다.
• 제 화면과 클로드의 답이 글자 하나까지 같지는 않을 것입니다. 단계마다 쓴 「이렇게 나오면 성공」 표시만 맞으면 다음으로 가세요.

1단계 · 규칙 파일이 이미 있는지 보기

클로드에게 이 폴더에 규칙 파일이 있는지 물어봅니다. 아무것도 만들어지지 않습니다. 내 PC 전체에 적용되는 개인 규칙 파일이 따로 있으면 그 이야기도 함께 나올 수 있습니다.

✅ 이렇게 나오면 성공 — 「없다」는 말과 「만들어 드릴 수 있다」는 제안이 나오면 다음 단계로. 이미 있다고 나오면 덮어쓰지 말고 /memory 로 내용을 먼저 확인하세요(「막히면」 6번).

2단계 · 글 쓰는 규칙 만들기

내 팀 이야기로 바꿔 쳐도 됩니다. 규칙을 한꺼번에 다 말하지 않아도 됩니다. 이 단계에서는 글을 쓰는 규칙만 말하고, 파일을 저장하는 규칙은 다음 단계에서 더합니다. 아래 5·7단계처럼 나중에 늘려도 됩니다. (프로그램 코드가 든 폴더라면 /init 이 폴더를 살펴 첫 판을 만들어 주기도 합니다. 이 편은 코드가 없는 폴더라 말로 시킵니다.)

✅ 이렇게 나오면 성공 — 폴더에 CLAUDE.md 가 생기고, 내가 말한 규칙이 번호 붙은 줄로 들어 있으면 다음 단계로. 파일을 열어 읽어 보세요. 규칙 문장이 클로드마다 조금 달라도 괜찮습니다. (허락 창이 뜨면 내용을 훑고 허락하세요.)

3단계 · 저장 규칙 더하기

같은 대화에서 이어서, 보고서를 어디에 어떤 이름으로 저장할지 규칙에 더합니다. CLAUDE.md 에 저장 규칙 칸이 새로 생깁니다.

✅ 이렇게 나오면 성공 — CLAUDE.md 에 「저장 규칙」 칸이 생기고 reports 와 날짜-제목.md 가 들어 있으면 다음 단계로. 날짜 꼴(YYYY-MM-DD)은 클로드가 정해 준 것이니 팀 방식이 다르면 고쳐 달라고 하세요.

4단계 · 새 대화에서 규칙대로 하는지 시험하기

가장 중요한 단계입니다. 지금 대화를 닫고 같은 폴더에서 새 대화를 엽니다. 터미널이면 /exit 로 나갔다가 그 폴더에서 claude 를 다시 입력하고(/clear 도 새 대화를 시작합니다), 데스크톱 앱이면 같은 폴더로 새 대화를 시작하세요. 이 대화는 앞 이야기를 모릅니다. 규칙은 파일에서 읽어 와야만 지킬 수 있습니다. 규칙을 말하지 않고 일만 시킵니다.

✅ 이렇게 나오면 성공 — reports 폴더에 보고서 파일이 생기고, 파일 맨 위가 결론 한 줄이며, 내가 주지 않은 정보(원인·출처 따위)가 「확인 필요」로 남아 있으면 규칙이 읽힌 것입니다. 클로드가 「규칙에 따라」라고 말해 주기도 합니다. (규칙을 안 지키면 아래 「막히면」 1번.)

5단계 · 마음에 안 드는 곳을 짚고, 규칙에 한 줄 더하기

보고서를 열어 읽어 봅니다. 내가 말하지 않은 말이 들어 있으면 그것을 짚고, 「규칙에 한 줄 더해 줘」라고 덧붙이세요. 제 화면에서는 이런 일이 있었습니다. 내 화면에서 다른 곳이 마음에 안 들면 그곳을 같은 식으로 짚으면 됩니다.

✅ 이렇게 나오면 성공 — CLAUDE.md 의 쓰는 규칙에 번호가 하나 늘어 5번이 생기고, 보고서에서 그 말이 빠졌으면 됩니다. 규칙 파일을 다시 열어 보세요.

6단계 · 새 대화에서 다시 시험하기 — 이번엔 다른 문제가

고친 규칙이 지켜지는지 새 대화에서 다시 봅니다. 이번에는 다른 공정으로 시험합니다.

✅ 이렇게 나오면 성공 — 이번에는 출처나 시스템 이름을 지어내지 않았습니다. 그런데 reports 폴더를 열어 보세요. 보고서가 두 개(도장·조립) 있어야 하는데 제 화면에서는 파일이 하나뿐이었습니다. 클로드가 이번 보고서를 아까와 같은 이름으로 저장하면서 4단계의 도장 보고서를 덮어썼습니다. 내 화면에서 파일이 둘이면 이 문제가 안 난 것이니 7단계는 눈으로만 읽고 넘어가도 됩니다.

7단계 · 그 문제도 규칙으로 막기

같은 말을 또 치지 않도록, 이 문제도 규칙 파일에 넣습니다. 도장 보고서가 사라졌다면 4단계 말을 다시 쳐서 새로 만들면 됩니다.

✅ 이렇게 나오면 성공 — 저장 규칙에 「덮어쓰지 않는다」가 들어갔으면 됩니다. 새 대화로 4단계 말(도장 12건)을 다시 쳐서 확인하세요. 제 화면에서는 이렇게 나왔습니다.

reports 에 파일 둘이 나란히 있고, 옛 파일이 그대로면 성공입니다. 클로드가 한 번 영어로 답하기도 했습니다. 그러면 「막히면」 5번을 보세요.

8단계 · 클로드가 규칙 파일을 읽었는지 확인하기 (내가 직접)

이 단계는 클로드에게 부탁하지 않고 내가 직접 합니다. 터미널에서 클로드를 연 상태로 입력하세요.

1. /context 를 입력합니다. 대화가 쓰는 자리를 나눠 보여 주는 표가 나옵니다.
2. Memory files(규칙 파일) 목록에 이 폴더의 CLAUDE.md 가 있는지 봅니다.
3. 파일을 직접 열어 고치고 싶으면 /memory 를 입력해 목록에서 고릅니다.

✅ 이렇게 나오면 성공 — 목록에 이 폴더의 CLAUDE.md 경로가 보이면 클로드가 읽고 있는 것입니다. 개인 전체 규칙 파일이 있으면 그것도 함께 보입니다. 데스크톱 앱 Code 탭에서 /context 가 같은 모양으로 되는지는 확인하지 못했습니다. 안 보이면 「막히면」 1번을 보세요.

다 됐습니다 — 이제 이렇게 말하면 됩니다

항상 이 폴더에서 클로드를 열고 이야기합니다.

• 「이번 주 ○○ 공정 불량은 ○건이야. 주간보고 초안 써 줘.」 (규칙은 말하지 않아도 읽힙니다.)
• 「방금 보고서에서 ○○이 마음에 안 들어. 앞으로 안 그러게 규칙에 한 줄 더해 줘.」
• 「CLAUDE.md 를 읽고 서로 어긋나는 규칙이 있는지 알려 줘.」
• 「CLAUDE.md 가 너무 길어졌어. 겹치는 규칙은 합쳐서 한눈에 보이게 줄여 줘. 지울 줄은 먼저 보여 주고.」

같은 말을 두 번 치게 되면 규칙에 넣을 때입니다. 공식 문서도 「클로드가 같은 실수를 두 번째 했을 때」를 규칙을 보탤 때로 꼽습니다.

막히면

1. 새 대화인데 규칙을 안 지킨다 → 먼저 8단계로 /context 의 Memory files 에 이 폴더 CLAUDE.md 가 있는지 보세요. 없으면 클로드를 연 폴더가 규칙 파일이 있는 폴더가 아닌 경우가 흔합니다(클로드는 시작한 폴더와 그 위쪽 폴더의 규칙 파일을 읽습니다). 이렇게 다시 말하세요: "지금 열려 있는 폴더 경로를 말하고, 그 폴더의 CLAUDE.md 를 읽은 다음 규칙을 한 줄씩 요약해 줘."
2. 규칙은 읽히는데 가끔 어긴다 → 규칙 문장이 모호해서입니다. 이렇게 다시 말하세요: "CLAUDE.md 에서 애매한 규칙을 찾아서, 지켰는지 눈으로 확인할 수 있는 문장으로 바꿔 줘. 예를 들어 '보고서를 간결하게'는 '한 문단은 세 줄 안'처럼."
3. 규칙 속 예시가 결과물에 그대로 나온다 → 5단계 일입니다. 이렇게 다시 말하세요: "CLAUDE.md 의 예시 중 실제 이름처럼 보이는 것을 <시스템 이름> 같은 자리 표시로 바꿔 줘."
4. 파일이 덮어써졌거나 지워졌다 → 클로드가 말없이 그랬다면 규칙이 없었던 것입니다. 이렇게 다시 말하세요: "파일을 만들거나 고치거나 지울 때는 먼저 무엇을 어떻게 할지 알려 주고, 같은 이름이 있으면 덮어쓰지 말라고 CLAUDE.md 에 넣어 줘." 되살릴 방법이 없는 폴더라면 중요한 폴더는 먼저 복사해 두세요.
5. 클로드가 영어로 답한다 → 7단계 시험에서 한 번 영어로 답했고, 02편에서도 있었던 일입니다. 이렇게 다시 말하세요: "한국어로 답해 줘. 앞으로도 계속 한국어로 답하게 CLAUDE.md 에 한 줄 적어 줘."
6. 이미 CLAUDE.md 가 있다고 나온다 → 있는 파일을 덮어쓰지 말고 이렇게 말하세요: "지금 CLAUDE.md 를 읽고 내용을 요약해 줘. 새 규칙은 기존 규칙과 겹치거나 어긋나지 않게 맨 아래에 이어서 써 줘."
7. 규칙 파일이 길어지고 서로 모순된다 → 공식 문서는 한 파일을 200줄 아래로 쓰길 권하고, 두 규칙이 어긋나면 클로드가 아무거나 고를 수 있다고 합니다. 이렇게 다시 말하세요: "CLAUDE.md 를 읽고 겹치는 규칙은 합치고, 어긋나는 규칙은 나한테 물어봐. 200줄 안으로 줄이되 지울 줄은 먼저 보여 줘."
8. 내가 만든 규칙을 클로드가 파일에 안 적고 「기억해 두겠다」고만 한다 → 클로드의 자동 기억(별개 기능)에 저장된 경우입니다. 이렇게 다시 말하세요: "그걸 이 폴더의 CLAUDE.md 에 적어 줘."

한 번에 맡기기 (익숙해진 다음에)

역할: 너는 내 PC 에서 일하는 도우미다. 이 폴더에서 앞으로 글을 쓸 때 지킬 「규칙 파일」(CLAUDE.md)을 만들고, 규칙대로 쓰는지 시험 글 한 편까지 써서 보여 준다. 나는 초보자이니 어려운 말은 풀어서, 한 단계씩 말해 줘.

맥락: 지금 열려 있는 이 폴더가 작업 폴더다. 너는 이 폴더에서 시작한 Claude Code 이고, 이 폴더의 CLAUDE.md 는 새 대화를 열 때마다 자동으로 읽힌다. 규칙 파일은 부탁이지 강제가 아니다. 훅·플러그인·설정 파일은 만들거나 고치지 않는다.

입력: <운영체제>, <쓰는 클로드: Claude Code 터미널 / 데스크톱 앱의 Code 탭>, <팀 이름>, <쓰는 글의 종류: 예 주간보고>, <내가 지키고 싶은 규칙 두세 개를 한 줄씩>

작업:
① 확인 — 아무것도 만들기 전에 먼저 본다. 지금 폴더의 전체 경로를 내게 말해 준다. CLAUDE.md 가 이미 있으면 덮어쓰지 말고 멈춰서 어떻게 할지 묻는다.
② 만들기 — CLAUDE.md 를 만든다. 아래 「틀 시작」과 「틀 끝」 사이의 내용대로 쓰되, 꺾쇠 <…> 자리는 내 입력으로 채우고, 규칙 한 줄은 한 가지만 구체적으로 쓴다(예: 「잘 써라」가 아니라 「첫 줄에 결론 한 문장」). 내가 말한 규칙이 3개를 넘으면 5번부터 이어서 번호를 붙인다.

=== 틀 시작 ===
# <팀 이름> <글의 종류> 작업 폴더

이 폴더에서 <글의 종류>를 쓰거나 고칠 때 아래 규칙을 지킨다.

## 쓰는 규칙
1. <내 규칙 1>
2. <내 규칙 2>
3. 자료에 없거나 확실하지 않은 내용은 지어내지 말고 "확인 필요"라고 적는다.
4. 내가 말하지 않았거나 자료에 없는 시스템 이름·사람 이름은 쓰지 않는다. 이 파일 속 예시는 자리 표시일 뿐 그대로 쓰지 않는다.

## 저장 규칙
- 글은 reports 폴더에 「날짜-주제-제목.md」로 저장한다. 날짜는 2026-10-10 꼴로 쓴다.
- 같은 이름의 파일이 이미 있으면 덮어쓰지 말고 끝에 -2, -3 을 붙인다. 저장한 파일 이름을 알려 준다.
- 기존 글은 내가 고쳐 달라고 할 때만 고친다.

## 지키는 것
- 비밀번호·키·고객 개인정보는 글에 쓰지 않는다.
- 이 폴더 밖의 파일은 읽지도 쓰지도 않는다.
=== 틀 끝 ===

③ 시험 글 — 방금 만든 규칙대로 시험 글 한 편을 reports 폴더에 쓴다. 파일 이름은 「오늘날짜-시험-규칙확인.md」. 내용은 이 가짜 자료로 쓴다: 「가나다전자 도장 공정 불량이 이번 주 12건, 지난주 9건. 원인은 모름.」 규칙에 없는 정보를 지어내지 않는다.
④ 검증 — 아래 「검증」 칸의 (가)~(라)를 파일을 다시 열어서 하나씩 확인하고 결과를 적는다.
⑤ 사람이 할 일 안내 — 내가 직접 해야 하는 두 가지를 말해 준다. 가) 이 폴더에서 클로드를 새 대화로 열고 규칙을 말하지 않은 채 "이번 주 불량이 ○건이야. 초안 써 줘"라고 시켜 본다. 나) 터미널이면 /context 를 입력해 Memory files 목록에 이 폴더의 CLAUDE.md 가 있는지 본다.
⑥ 마무리 — 초보자 눈높이로 무엇이 만들어졌고, 앞으로 어떻게 말하면 되는지(예: "방금 건 마음에 안 들어. 앞으로 안 그러게 규칙에 한 줄 더해 줘") 설명한다. 시험 글은 내가 "시험 글 지워 줘"라고 하면 지우면 된다고 알려 준다.

제약: 비밀키·토큰·비밀번호를 출력하거나 파일에 쓰지 않기. 오류를 건너뛰지 않기. 기존 파일을 지우거나 덮어쓰지 않기. 이 폴더 밖의 파일을 읽지도 쓰지도 않기. 프로그램을 대신 설치하지 않기. 규칙 파일에 개인정보·고객 자료·반출금지 도면 내용을 적지 않기.

출력: 한 일, 확인된 상태(폴더가 비어 있었는지), 만든 파일 목록, 검증 결과((가)~(라) 각각 통과/실패), 내가 해야 할 두 가지(⑤ 그대로), 남은 문제와 다음 조치.

검증: 아래가 파일을 다시 열어서 전부 확인돼야 "자동 확인 통과"라고 보고한다. 하나라도 실패하면 완료로 보고하지 말 것.
 (가) 이 폴더에 CLAUDE.md 가 있고 첫 줄이 "# "로 시작하며 200줄 이하다.
 (나) CLAUDE.md 의 「쓰는 규칙」에 번호 줄이 4개 이상 있고, 내가 말한 규칙이 그대로 들어 있다.
 (다) CLAUDE.md 에 「확인 필요」, 「덮어쓰지」, 「비밀번호」 세 낱말이 각각 들어 있다.
 (라) reports 폴더에 시험 글이 정확히 한 장 있고, 첫 줄이 결론 한 문장이며, 내가 주지 않은 정보(원인·담당자 따위)는 「확인 필요」로 적혀 있다.
 단, 사람이 직접 해야 하는 ⑤는 네가 확인할 수 없으므로 "완료"가 아니라 "남은 일"로 적는다. 새 대화에서 규칙대로 쓰고 /context 목록에 CLAUDE.md 가 보여야 비로소 전체 완료다.

내가 만들 때는

처음엔 이렇게 시켰습니다. 2026-09-16 아침, 제 개인 비서 AI 파이스의 저장소에서 작업하던 대화였습니다. 클로드는 「메모(기억 노트)는 무슨 일이 있었나의 기록이지 이 프로젝트에선 이렇게 일하라는 규칙이 아니다. 그래서 오늘만 해도 커밋 문구 형식, 푸시할지 말지, 시험을 먼저 돌릴지를 매번 새로 판단했다. 규칙으로 박아 두면 다음 세션부터 안 물어봐도 된다. 만들까요?」라고 제안했습니다. 저는 이렇게 답했습니다. 「ㅇㅋ 해줘봐..」(09:42) 1분 뒤인 09:43에 규칙 문서 60줄이 저장소에 들어갔습니다. 지금은 63줄입니다. 담은 것은 「파이스는 자기 코드를 스스로 고쳐 커밋하니 푸시 전에 먼저 확인한다」 「숫자를 문서에 박지 않는다」 「브랜치 없이 한 곳에 직접 올린다」 「고장은 재발 방지까지」 「겪어서 아는 함정」 「세션을 끝낼 때 기억에 남길지 묻는다」 같은 것입니다. 이 편의 5단계(틀릴 때마다 한 줄씩)와 같은 방식이고, 회사 이름·주소·키는 이 글에 옮기지 않았습니다.

규칙 문서도 낡습니다. 8월 6일에 설계 문서에 「도구 41종」이라고 적었는데 그날 저녁 코드는 47종이었고, 그 문장은 9월 16일까지 41일 남아 있었습니다. 파이스는 그 문서를 읽고 자기 코드를 고치는 근거로 삼으므로 틀린 숫자는 틀린 전제가 됩니다. 그래서 규칙 문서에 「숫자는 코드가 진실이다」를 적고 문서에서 숫자를 뺐습니다. 그런데 그 규칙 문서도 「파일 크기·줄 수」를 적었다가 어긋났습니다. 숫자를 박으면 반드시 뒤처진다는 규칙이, 박아 둔 숫자 때문에 증명된 셈입니다. 규칙 파일에는 바뀌는 숫자를 적지 말고 「어디를 보면 지금 값이 나오는지」를 적으세요. 9월 17일에는 서버가 다른 컴퓨터로 이사해서 규칙 문서도 다시 고쳤습니다. 규칙 파일은 한 번 쓰고 끝이 아니라 일이 바뀌면 같이 고치는 문서입니다.

그리고 이 편 8단계의 경고도 같은 곳에서 나왔습니다. 글로 적은 규칙은 자기 코드를 고치는 에이전트를 막지 못했습니다. 예를 들어 9월 12일에 한 스크립트의 로그 열기 방식을 고쳤는데 9월 14일에 다른 스크립트에서 같은 버그를 또 고쳤습니다. 「고칠 땐 같은 코드를 다 찾아보라」는 규칙이 이미 있었는데도 그랬습니다. 그래서 규칙을 한 줄 더 적는 대신, 자기수정이 끝나면 같은 코드가 다른 파일에 남았는지 스스로 찾아보는 검사로 바꿨습니다. 결국 같은 실수를 막는 방법은 규칙을 늘리는 것이 아니라 그 실수를 검사로 바꾸는 것이었습니다. 이 편에서 「절대 어기면 안 되는 것은 승인 방식과 훅으로」라고 쓴 이유입니다.

→ 뒷이야기 17단계에서 자세히 보세요.