AI를 위한 규칙을 적는다

5편에서 README와 Issue를 저장소에 넣었습니다. 이 글은 같은 저장소에 한 파일을 더합니다. CLAUDE.md입니다. Claude Code가 세션을 시작할 때마다 읽는 파일이므로, 여기에 적힌 것은 매번 말하지 않아도 전달됩니다. 무엇을 적고 무엇을 적지 않는지, 그리고 어떻게 키워 가는지를 다룹니다. 다음 편 폴더 구성과 기술 선정에서는 사람이 정하지 않아도 되는 것을 AI에게 넘깁니다.

핵심 요약

• CLAUDE.md는 프로젝트 루트에 두는 마크다운 파일이고, Claude Code가 모든 세션 시작 시 읽습니다.
• 새로 온 직원에게 건네는 업무 매뉴얼처럼 씁니다. 다섯 항목이면 충분합니다.
• 코드에서 알 수 있는 것, 한 번만 쓸 절차는 적지 않습니다. 200줄을 넘기지 않습니다.
• 초판은 짧게 만들고, 같은 지적을 두 번 했을 때 한 줄씩 키웁니다.

CLAUDE.md는 AI와의 약속

공식 문서는 CLAUDE.md를 "프로젝트, 개인 워크플로우, 조직에 대해 Claude에 지속적인 지침을 제공하는 마크다운 파일"이라고 설명합니다. 두는 자리는 프로젝트 루트의 ./CLAUDE.md(또는 ./.claude/CLAUDE.md)이고, 모든 프로젝트에 적용할 개인 규칙은 ~/.claude/CLAUDE.md에 둡니다. 저장소에 올리고 싶지 않은 개인 설정은 ./CLAUDE.local.md에 두고 .gitignore에 넣습니다. 세션에 어떤 파일이 읽혔는지는 /memory 명령으로 확인할 수 있습니다.

한 가지를 분명히 해 두어야 합니다. 공식 문서 표현대로 CLAUDE.md는 "강제된 구성이 아닌 컨텍스트"입니다. AI는 이것을 읽고 따르려 하지만, 반드시 막아야 하는 동작은 훅(hook)으로 강제해야 합니다. 그래서 우리는 이 파일을 "규칙"보다 "약속"이라고 부릅니다. 약속은 구체적일수록 잘 지켜집니다. 우리 2주차 교재에서 처음 만드는 3줄이 바로 이 약속의 첫 장입니다.

새로 온 사람에게 건네는 업무 매뉴얼이라고 생각하고 적는다

CLAUDE.md를 기술 문서라고 생각하면 쓰기 어렵습니다. 대신 이렇게 생각하십시오. 내일 새 직원이 오는데 내가 출장이라 말로 설명할 수 없다. 책상 위에 종이 한 장을 두고 간다면 무엇을 적겠는가. "우리 고객은 누구다", "이건 절대 하지 마라", "끝나면 이렇게 보고해라" 같은 것입니다. 그 종이가 CLAUDE.md입니다. 새 직원이 스스로 찾을 수 있는 것은 적지 않습니다.

적어야 할 것

다섯 항목입니다. 우리 4주차 교재의 템플릿을 이 코스에 맞게 줄였습니다.

# 상담일지 변환기 작업 규칙

## 1. 이 프로젝트는 무엇인가
정책자금 컨설턴트의 상담 녹음을 상담일지로 바꾸는 도구다. 자세한 것은 README.md.

## 2. 절대 하지 말 것
- 고객 실명을 결과 문서에 그대로 쓰지 않는다. 홍OO 형태로 가린다.
- API 키나 비밀번호를 코드나 문서에 직접 쓰지 않는다. .env로 관리한다.
- data/ 안의 원본 녹음 파일을 수정하거나 삭제하지 않는다.

## 3. 항상 할 것
- 파일을 고치기 전에 영향받는 파일 목록을 먼저 보여 준다.
- 확실하지 않은 수치는 지어내지 말고 "확인 필요"라고 표시한다.
- 작업 한 단락이 끝나면 커밋한다.

## 4. 어디에 무엇이 있는가
docs/ 기획과 결정, src/ 코드, data/ 샘플 입력, tests/ 검증.

## 5. 완료 보고 형식
변경한 파일, 변경 이유, 내가 확인하는 방법 세 줄로 보고한다.

공식 문서가 권하는 대로 각 줄은 "실명은 홍OO로"처럼 검증 가능할 만큼 구체적으로 씁니다. 5번 항목은 우리 5주차 황금 문장의 뒷부분("변경된 파일, 수정 이유, 테스트 방법을 정리해 달라")을 매번 말하지 않아도 되게 파일에 넣은 것입니다.

안 적어도 되는 것

• 코드를 읽으면 알 수 있는 것. 폴더 구조 전체, 함수 목록, 라이브러리 버전은 AI가 스스로 찾습니다.
• 한 번만 쓸 절차. 배포 순서처럼 길고 특정 상황에만 쓰는 내용은 skill이나 docs/로 빼라고 공식 문서가 안내합니다.
• 서로 모순되는 규칙. 두 규칙이 충돌하면 AI가 임의로 하나를 고릅니다. 새 줄을 넣을 때 기존 줄과 부딪히지 않는지 봅니다.
• 긴 설명. 공식 문서는 파일당 200줄 이하를 권장합니다. 길어질수록 컨텍스트를 먹고 준수율이 떨어집니다.

규칙은 키우는 것

초판을 완벽하게 만들려 하지 마십시오. 공식 문서가 CLAUDE.md에 추가할 시점으로 첫째로 꼽는 것이 "Claude가 같은 실수를 두 번째로 할 때"입니다. 우리 규칙도 같습니다. 같은 지적을 두 번 했으면 그 지적을 한 줄로 바꿔 CLAUDE.md에 넣습니다. 세션 안에서는 이렇게 시키면 됩니다.

방금 지적한 "결과 파일 이름에 날짜를 앞에 붙여라"를 CLAUDE.md의 3번 항목에 한 줄로 추가해 줘.

원구연의 전역 CLAUDE.md도 이렇게 자랐습니다. "공식 문서를 먼저 확인하라"는 줄은 추측으로 시간을 낭비한 사고가 있었던 날 추가됐고, 그 옆에 날짜와 이유가 적혀 있습니다. 규칙에 이유를 붙여 두면 나중에 지울지 말지도 판단할 수 있습니다.

해 보기

5편의 저장소에서 Claude Code를 켜고 아래 중 하나로 초판을 만드십시오.

방법 1은 /init입니다. 공식 명령으로, Claude가 저장소를 읽고 시작용 CLAUDE.md를 만듭니다. 이미 파일이 있으면 덮어쓰지 않고 개선을 제안합니다. 방법 2는 직접 시키는 것입니다.

README.md를 읽고, 위의 다섯 항목 구조로 CLAUDE.md 초판을 써 줘.
20줄을 넘기지 마. 쓴 뒤 /memory로 읽혔는지 확인할 거야.

만든 뒤 /memory를 입력해 CLAUDE.md가 목록에 보이는지 확인하십시오. 그것이 증거입니다. 마지막으로 커밋과 푸시를 시킵니다.

정리

• CLAUDE.md는 세션 시작마다 읽히는 약속 파일이며 강제 장치는 아닙니다.
• 새 직원용 매뉴얼처럼 다섯 항목(무엇인가, 하지 말 것, 항상 할 것, 어디에 무엇, 보고 형식)만 씁니다.
• 코드에서 알 수 있는 것과 긴 절차는 적지 않고 200줄 이하로 유지합니다.
• 같은 지적 두 번이면 한 줄 추가, 이유도 함께 적습니다.

자주 묻는 질문