CLAUDE.md로 프로젝트 규칙 알려주기

01반복해서 말하는 규칙만 프로젝트 파일로 옮기기

앞 글에서는 Claude Code에 요청할 때마다 입력 파일, 표준 라이브러리 사용, 원본 CSV 수정 금지, 실행 명령, 기대 출력까지 직접 적었습니다. 같은 프로젝트를 계속 작업한다면 이런 규칙을 매번 다시 쓰는 대신 CLAUDE.md에 정리할 수 있습니다. Claude Code는 세션 시작 시 이 파일을 읽어 프로젝트 맥락으로 사용합니다.

다만 CLAUDE.md를 접근 제어 장치나 절대적인 강제 규칙으로 생각하면 안 됩니다. 공식 문서 기준으로 이 파일은 맥락이며, 구체적이고 간결할수록 따르기 쉽습니다. 따라서 '항상 완벽하게 지켜진다'고 가정하지 말고 실제 변경 내용은 계속 확인해야 합니다.

02팀 공유·개인 공통·개인 프로젝트 파일 위치 구분하기

공식 문서에서 안내하는 위치는 용도가 다릅니다. 프로젝트 루트의 `./CLAUDE.md`는 팀과 공유할 프로젝트 규칙에 적합합니다. `~/.claude/CLAUDE.md`는 개인 전체 프로젝트에 공통으로 적용할 메모이고, `./CLAUDE.local.md`는 특정 프로젝트에서 개인적으로만 쓰며 .gitignore에 추가할 수 있습니다.

./CLAUDE.md
~/.claude/CLAUDE.md
./CLAUDE.local.md

이번 예제는 실행 명령과 데이터 규칙처럼 프로젝트 자체에 속하는 내용을 담으므로 `./CLAUDE.md`를 사용합니다. 개인적인 선호나 로컬 경로를 팀 공유 파일에 섞지 않는 편이 관리하기 쉽습니다.

03/init으로 초안을 만들고 그대로 확정하지 않기

세션에서 `/init`을 사용하면 Claude Code가 코드베이스를 분석해 빌드·테스트 명령과 관례를 담은 CLAUDE.md 초안을 만들 수 있습니다. 이미 CLAUDE.md가 있다면 덮어쓰지 않고 개선을 제안하는 방식으로 동작한다고 공식 문서에 설명되어 있습니다. 따라서 `/init`은 규칙을 자동으로 결정하는 명령이 아니라, 사람이 다듬을 초안을 얻는 출발점으로 보는 편이 적절합니다.

/init

초안이 만들어지면 실제 프로젝트와 맞지 않는 명령, 존재하지 않는 테스트, 과도하게 일반적인 지시가 들어갔는지 확인합니다. 이 글에서는 Claude Code를 실제 실행하지 않았으므로 `/init`이 어떤 문장을 생성했다고 예시 응답을 꾸며 제시하지 않습니다.

04가계부 예제용 CLAUDE.md를 35줄로 정리하기

아래 예시는 이 시리즈의 가상 프로젝트에 필요한 규칙만 모은 CLAUDE.md입니다. 공식 문서에서는 파일당 200줄 미만을 권장하며, 이번 예제는 35줄로 유지했습니다. 목표·데이터·Python 규칙·실행 명령·기대 결과·작업 규칙을 구분해 사람이 읽어도 바로 이해할 수 있게 합니다.

# Project: vibe-expenses

## Goal
- Read expenses.csv and summarize expense amounts.
- Keep the example small and understandable for beginners.

## Data
- Input file: expenses.csv
- Encoding: UTF-8
- Columns: date, category, amount
- date format: YYYY-MM-DD
- category values stay in English.
- amount is treated as an integer.

## Python rules
- Use only the Python standard library.
- Prefer csv for reading CSV files.
- Do not add third-party packages.
- Keep functions short and names descriptive.
- Do not modify expenses.csv.

## Commands
- Run: python summarize.py expenses.csv
- On Windows, py summarize.py expenses.csv is also acceptable.

## Expected result
- 2026-09 = 26600
- 2026-10 = 9800

## Working rules
- Explain the planned change before editing files.
- Change only files needed for the requested task.
- Do not invent extra input columns or business rules.
- If a requirement is unclear, ask before expanding scope.
- After editing, show what changed and how to verify it.

여기에는 비밀번호, API 키, 실제 고객 경로 같은 비밀정보를 넣지 않습니다. 프로젝트 지침 파일은 작업 맥락을 전달하기 위한 것이므로, 공개되거나 공유되어도 문제가 없는 규칙 중심으로 작성하는 편이 안전합니다.

05긴 설명보다 확인 가능한 규칙을 우선하기

CLAUDE.md가 길어질수록 좋은 것은 아닙니다. '코드를 잘 작성해라'처럼 판정하기 어려운 문장보다 '외부 패키지를 추가하지 않는다', 'expenses.csv를 수정하지 않는다', '실행 명령은 이것이다'처럼 실제 변경 결과와 대조할 수 있는 규칙이 유용합니다. 필요하다면 `@경로` 문법으로 다른 파일의 내용을 가져올 수 있지만, 이번 작은 예제에서는 별도 파일을 가져올 필요가 없습니다.

• 프로젝트에 실제로 존재하는 파일명과 명령만 적는다.
• 한 번만 필요한 작업 지시는 매번 CLAUDE.md에 쌓지 않는다.
• 금지사항은 무엇을 하지 말아야 하는지 구체적으로 적는다.
• 완료 여부를 판단할 수 있는 기대값이나 확인 명령을 남긴다.
• 개인 비밀정보와 API 키를 프로젝트 규칙 파일에 넣지 않는다.

규칙을 추가한 뒤에도 Claude Code가 실제로 어떤 파일을 바꾸는지는 별도로 확인해야 합니다. CLAUDE.md는 검토를 대신하는 장치가 아니라, 반복해서 설명해야 하는 프로젝트 맥락을 줄이는 장치입니다.

06규칙 파일을 만든 뒤 다음 작업 전에 다시 읽기

CLAUDE.md를 저장했다면 다음 기능을 요청하기 전에 사람이 파일을 한 번 읽어 봅니다. 현재 코드와 실행 명령이 달라졌는데 오래된 지시가 남아 있으면 오히려 잘못된 맥락을 줄 수 있습니다. 특히 기대 출력이나 파일명이 바뀌면 규칙 파일도 함께 갱신해야 합니다.

다음 글에서는 이 규칙을 유지한 채 새 기능을 바로 구현하지 않고 plan 모드에서 먼저 설계합니다. 목표는 `--by-category` 옵션으로 2026-09의 food 20500, transport 2900, supplies 3200을 출력하는 기능이 어떤 변경을 요구하는지 계획 단계에서 검토하는 것입니다.

직접 확인할 항목

Claude Code 공식 문서(2026-09-22 확인)와 이 시리즈의 가상 예제를 기준으로 작성 · Claude Code 실제 실행 없음 · 본 글에 실행 대상 Python 코드 없음

• 프로젝트 `./CLAUDE.md`, 개인 전체 `~/.claude/CLAUDE.md`, 개인 프로젝트 `./CLAUDE.local.md` 위치와 용도가 공식 문서와 일치하는지 확인
• `/init`이 코드베이스를 분석해 초안을 만들며 기존 CLAUDE.md를 덮어쓰지 않고 개선을 제안한다는 설명을 공식 문서와 대조
• CLAUDE.md를 강제 설정이 아닌 프로젝트 맥락으로 설명했는지 확인
• 예시 CLAUDE.md가 35줄이며 공식 문서 권장인 파일당 200줄 미만 범위인지 확인
• 예시 규칙에 실행 명령·데이터 규칙·금지사항·기대 결과·확인 흐름이 포함됐는지 확인
• 실제 `/init` 실행 결과나 Claude Code 응답을 만들어냈다고 표현하지 않았는지 확인