4장. CLAUDE.md: 프로젝트의 헌법

혼자 제품을 만드는 사람은 늘 같은 문제를 겪는다. AI가 똑똑하지 않아서가 아니라, 매번 새로 합류한 외주 개발자처럼 굴기 때문이다. 어제는 테스트를 먼저 쓰더니 오늘은 바로 구현부터 들어가고, 방금 전까지는 app/ 구조를 잘 이해하더니 다음 세션에서는 엉뚱한 디렉터리를 뒤진다. 이럴 때 필요한 것이 더 화려한 프롬프트가 아니라, 프로젝트의 기본 질서를 담은 문서다.

그 문서가 바로 CLAUDE.md다. 이름만 그럴듯한 설정 파일이 아니다. 잘 만든 CLAUDE.md는 에이전트가 "이 프로젝트에서 무엇을 우선하고, 무엇을 피하고, 어떤 식으로 판단해야 하는지"를 이해하게 만드는 기준점이다. Anthropic이 모델의 행동을 형성하는 기초 문서를 "헌법"이라고 부르는 이유와 비슷하다. 핵심은 규칙 몇 줄을 늘어놓는 데 있지 않고, 좋은 판단이 나오게 만드는 기본 원칙을 심는 데 있다.¹

솔로 빌더에게 이건 특히 중요하다. 팀에서는 선임 개발자, 리뷰어, 아키텍트가 틀린 방향을 바로잡아 준다. 혼자 일할 때는 그 역할까지 모두 직접 해야 한다. 그런데 CLAUDE.md가 있으면 그 교정 비용의 일부를 문서로 선납할 수 있다. 한 번 잘 써두면 세션이 바뀌어도 같은 설명을 반복하지 않아도 되고, 잘못된 추론 때문에 생기는 삽질도 크게 줄어든다.

좋은 CLAUDE.md는 규칙집이 아니라 판단 프레임이다

Claude Code는 세션 시작 시 CLAUDE.md를 자동으로 읽는다. 필요하면 /init으로 초안을 생성할 수도 있다.² 이 말은 곧, 이 파일이 대화가 시작되기 전에 이미 작동하고 있다는 뜻이다. 첫 메시지를 보내기 전부터 "이 프로젝트는 어떤 프로젝트인지", "어떤 명령을 써야 하는지", "어떤 실수를 하면 안 되는지"를 알고 출발하는 셈이다.

여기서 많은 사람이 첫 번째 실수를 한다. CLAUDE.md를 장문의 운영 매뉴얼로 만들어 버리는 것이다. 하지만 이 파일은 매 세션마다 함께 로드된다. 너무 길어지면 중요한 규칙이 묻히고, 정작 필요한 순간에는 핵심이 흐려진다. 공식 가이드도 짧고 사람이 읽기 쉬운 형태를 권한다.³

좋은 CLAUDE.md는 대체로 네 가지 성질을 가진다.

• 짧다. 매번 붙는 문서이므로 길이 자체가 비용이다.

• 구체적이다. "깔끔하게 작성"보다 "모든 API 입력은 Zod로 검증"이 훨씬 잘 작동한다.

• 프로젝트 고유 정보만 담는다. 언어 기본 문법이나 누구나 아는 상식은 빼고, 이 프로젝트에서만 중요한 것에 집중한다.

• 검증 가능하다. 빌드, 테스트, 린트처럼 에이전트가 스스로 확인할 수 있는 완료 조건이 들어 있다.

여기서 핵심은 "무엇을 하라"보다 "왜 그렇게 하는가"를 함께 적는 것이다. 예를 들어 "기본 export 금지"만 적으면 규칙처럼 보인다. 반면 "기본 export 금지, 이유는 검색성과 자동 리팩터링 안정성 때문"이라고 적으면 에이전트가 낯선 상황에서도 더 잘 일반화한다. 이것이 헌법다운 문서다. 체크리스트를 암기시키는 것이 아니라 판단의 방향을 잡아 주는 것이다.¹

반대로 나쁜 CLAUDE.md는 이런 식이다.

"코드는 예쁘게 작성할 것."

"최신 방식으로 구현할 것."

"성능도 고려할 것."

읽는 순간 고개는 끄덕여지지만, 막상 파일을 수정할 때는 아무 도움도 되지 않는다. 예쁜 코드가 무엇인지, 최신 방식이 무엇인지, 성능 고려가 어디까지인지 전혀 알 수 없기 때문이다.

좋은 문장은 대개 이런 구조를 가진다.

• 대상: 어디에 적용되는가

• 규칙: 무엇을 해야 하는가

• 이유: 왜 그렇게 해야 하는가

• 예외: 언제는 달라지는가

• 검증: 무엇으로 끝났다고 볼 것인가

예를 들어 이렇게 쓸 수 있다.

"모든 상태 변경은 Server Action으로 구현한다. 외부 웹훅 수신만 API Route를 사용한다. 이유는 인증, 로깅, 에러 처리 패턴을 통일하기 위해서다. 변경 후 pnpm test와 pnpm build를 반드시 실행한다."

이 한 줄은 단순한 스타일 취향이 아니라, 아키텍처 의도와 작업 절차를 동시에 전달한다.

코딩 컨벤션, 아키텍처, 금지 사항은 이렇게 적는다

CLAUDE.md를 처음 만들 때는 멋진 문장을 쓰려 하지 말고, 에이전트가 매번 헤매는 질문부터 없애면 된다. 보통 필요한 내용은 아주 비슷하다. 이 프로젝트가 무엇인지, 어디를 봐야 하는지, 어떤 명령을 써야 하는지, 무엇을 건드리면 안 되는지다.

실전에서는 다음 여섯 섹션이면 충분한 경우가 많다.

• 프로젝트 요약

• 자주 쓰는 명령어

• 디렉터리 구조와 아키텍처

• 코딩 컨벤션

• 금지 사항과 위험 구역

• 완료 조건

솔로 빌더가 만드는 전형적인 SaaS 프로젝트라면, 예를 들어 이런 식으로 시작할 수 있다.

# Project
구독형 리포트 SaaS. Next.js App Router, TypeScript, Supabase, Tailwind 사용.

## Commands
- `pnpm dev` - 개발 서버
- `pnpm test` - 테스트 실행
- `pnpm lint` - 린트 검사
- `pnpm build` - 프로덕션 빌드

## Architecture
- `app/` - 라우트와 서버 액션
- `components/` - UI 컴포넌트
- `lib/` - 공용 유틸리티, API 클라이언트
- `supabase/` - SQL, 마이그레이션, 정책

## Conventions
- 기본은 Server Component, 상호작용이 필요할 때만 `use client`
- 모든 폼 입력은 Zod로 검증
- 데이터 접근은 `lib/`의 래퍼를 통해서만 수행
- named export만 사용

## Avoid
- `.env` 내용을 읽거나 출력하지 말 것
- 커밋된 migration 파일을 수정하지 말 것
- 새 의존성 추가 전 반드시 이유를 설명할 것
- `any` 타입 사용 금지

## Done Criteria
- 변경 후 관련 테스트 실행
- `pnpm lint`와 `pnpm build` 통과
- 영향 범위를 짧게 요약해 보고

이 정도만 있어도 에이전트는 훨씬 덜 헤맨다. 중요한 것은 항목 수가 아니라 밀도다.

프로젝트 요약에서는 기술 스택을 전부 나열할 필요가 없다. 에이전트가 코드를 읽으면 알 수 있는 정보는 최소화하고, 코드만으로는 잘 안 보이는 판단 기준을 적는 편이 낫다. 예를 들어 "이 프로젝트는 빠른 실험보다 안정적 결제를 우선한다" 같은 문장은 실제 의사결정에 영향을 준다. 반면 "React를 사용한다"는 대개 큰 가치가 없다.

자주 쓰는 명령어는 생각보다 중요하다. 사람 개발자는 package.json을 열어보면 되지만, 에이전트는 잘못된 명령을 추측해서 시간을 낭비하기 쉽다. 테스트가 pnpm test인지, 단일 테스트가 가능한지, 빌드 전에 타입체크를 따로 해야 하는지 적어두면 시행착오가 크게 줄어든다. Anthropic의 가이드도 명령어와 워크플로 규칙을 CLAUDE.md에 넣는 것을 강하게 권한다.²³

아키텍처 섹션에서는 파일 설명서를 쓰는 것이 아니라 지도를 그린다고 생각하면 좋다. "인증 로직은 src/auth/", "DB 쿼리는 src/server/db/만 사용", "외부 API 통신은 lib/integrations/에서만 수행"처럼 경로와 책임을 연결해 주면 된다. 그래야 Claude가 새 파일을 어디에 만들어야 할지, 수정은 어느 계층에서 해야 할지 감을 잡는다.

코딩 컨벤션은 취향보다 일관성에 집중해야 한다. 예를 들어 "함수는 읽기 쉬워야 한다"보다 "복잡한 비즈니스 로직은 작은 순수 함수로 분리한다", "API 응답은 { data, error } 형태를 유지한다" 같은 문장이 훨씬 유용하다. 특히 팀이 아닌 혼자 일할수록, 미래의 내가 싫어할 코드를 미리 금지하는 효과가 있다.

금지 사항은 더 짧고 더 단단해야 한다. 이 부분은 철학적으로 설명하기보다 레드라인을 명확히 긋는 편이 낫다. NEVER 같은 강조를 써도 괜찮다. 빌더가 실제로 자주 넣는 금지 사항은 보통 이렇다.

• 비밀키, 토큰, .env 내용 출력 금지

• 운영 DB 직접 수정 금지

• 커밋된 마이그레이션 파일 수정 금지

• force push, 대량 삭제, 파괴적 명령 실행 전 확인 필수

이런 문장들은 "생산성"보다 "사고 방지"에 가깝다. 솔로 빌더에게 가장 비싼 비용은 하루에 한 번의 큰 사고다. CLAUDE.md는 그 사고를 줄이는 쪽으로 먼저 설계해야 한다.

마지막으로 완료 조건을 넣어야 한다. 그래야 에이전트가 "코드를 썼다"와 "작동을 검증했다"를 구분한다. 테스트, 린트, 빌드, 스모크 체크처럼 스스로 확인 가능한 절차가 들어가면 결과물의 신뢰도가 달라진다. Claude Code는 검증 기준이 있을수록 훨씬 좋은 성능을 낸다.³

13KB 미만으로 유지하는 정보 압축 기술

CLAUDE.md는 편리하지만 공짜는 아니다. 이 파일은 세션마다 자동으로 따라붙는다. 다시 말해, 너무 길면 매번 내는 컨텍스트 세금이 된다. 그리고 세금은 길이만의 문제가 아니다. 길어질수록 중요한 규칙이 희석된다. 공식 문서와 여러 실전 가이드는 대체로 200~400줄 안팎, 혹은 아주 짧은 운영 문서 수준을 추천한다.³⁶

이 책에서는 더 기억하기 쉽게 한 가지 기준을 제안하겠다. CLAUDE.md는 13KB 미만을 목표로 유지한다. 법은 아니다. 하지만 이 선을 넘기기 시작하면 대체로 같은 일이 벌어진다. 설명은 많아지고, 행동은 덜 좋아진다.

압축은 요약이 아니라 선별이다. 다음 다섯 가지 원칙이 특히 잘 먹힌다.

• 코드에서 바로 알 수 있는 것은 빼기

• 자주 틀리는 것만 남기기

• 긴 문서 대신 경로만 알려주기

• 범용 규칙과 경로별 규칙을 분리하기

• 오래된 규칙을 주기적으로 삭제하기

첫째, 코드에서 바로 알 수 있는 것은 뺀다. package.json, pyproject.toml, go.mod를 보면 아는 정보를 굳이 중복해서 적지 않는다. "React 19 사용" 정도는 큰 의미가 없다. 대신 "이 프로젝트는 브라우저 상태보다 서버 액션을 우선한다"처럼 코드만 읽어선 놓치기 쉬운 판단 기준을 남긴다.

둘째, 자주 틀리는 것만 남긴다. 가장 좋은 CLAUDE.md는 상상으로 쓰는 문서가 아니라, 실제 마찰에서 태어난 문서다. 같은 실수를 두 번 봤다면 넣을 가치가 있다. 예를 들어 Claude가 자꾸 API 응답 형식을 제각각 만들었다면 "모든 API는 { data, error }를 유지"를 넣는다. 반대로 아직 한 번도 문제가 된 적 없는 규칙은 후보일 뿐이다.

셋째, 긴 설명 대신 파일 경로를 남긴다. 예를 들어 결제 정책이 길다면 docs/billing-rules.md 참고처럼 연결하고, CLAUDE.md에는 "결제 로직 수정 전 해당 문서 확인"만 남긴다. Anthropic은 @path/to/file 형태의 가져오기도 지원한다.³ 다만 뭐든 가져와 붙이면 결국 비대해진다. 핵심은 자동 포함될 상시 컨텍스트를 최소화하는 것이다.

넷째, 범용 규칙과 경로별 규칙을 분리한다. 루트 CLAUDE.md에는 어디서나 통하는 원칙만 두고, 특정 디렉터리에만 필요한 규칙은 하위 CLAUDE.md나 .claude/rules/로 옮긴다. 그래야 웹 프론트 규칙이 DB 마이그레이션 작업까지 따라붙지 않는다.⁵

다섯째, 오래된 규칙을 지운다. 이게 은근히 중요하다. 죽은 규칙은 없는 규칙보다 나쁘다. 예전에는 Jest였는데 지금은 Vitest인데도 문서가 안 바뀌어 있으면, 에이전트는 틀린 명령을 진지하게 실행한다. 결국 사람은 또 교정하고, 문서는 또 신뢰를 잃는다.

압축의 감각은 이런 질문으로 점검할 수 있다.

"이 줄을 지우면 Claude가 실제로 더 자주 실수할까?"

대답이 아니라 "음, 그냥 있으면 좋아 보여서"라면 지우는 편이 낫다.

모노레포와 멀티 프로젝트에서는 층을 나눠 써야 한다

프로젝트가 하나일 때는 루트에 CLAUDE.md 하나만 있어도 된다. 하지만 앱이 둘 이상이 되면 한 파일에 모든 규칙을 욱여넣는 순간 무너진다. 프론트엔드 규칙, 백엔드 규칙, 인프라 규칙, 공통 패키지 규칙이 서로의 집중력을 갉아먹기 때문이다.

Claude Code는 전역, 프로젝트 루트, 하위 디렉터리 단위로 문맥을 겹쳐서 읽을 수 있다.⁴ 이 구조를 잘 쓰면 모노레포에서도 꽤 우아하게 정리된다.

가장 실용적인 구조는 보통 이렇다.

• ~/.claude/CLAUDE.md : 내가 모든 프로젝트에서 공통으로 쓰는 습관

• repo/CLAUDE.md : 저장소 전반에 적용되는 공통 원칙

• apps/web/CLAUDE.md : 웹 앱 전용 규칙

• apps/api/CLAUDE.md : API 서버 전용 규칙

• packages/ui/CLAUDE.md : 디자인 시스템이나 공유 패키지 전용 규칙

예를 들면 이런 형태다.

~/.claude/CLAUDE.md
saas-studio/
├─ CLAUDE.md
├─ apps/
│  ├─ web/
│  │  └─ CLAUDE.md
│  └─ api/
│     └─ CLAUDE.md
├─ packages/
│  └─ ui/
│     └─ CLAUDE.md
└─ .claude/
   └─ rules/
      ├─ migrations.md
      └─ security.md

전역 파일에는 개인 취향과 습관만 넣는다. 예를 들어 "답변은 한국어", "커밋 메시지는 Conventional Commits", "파괴적 명령 전 반드시 확인" 같은 내용이다. 다른 프로젝트로 가도 여전히 참인 정보만 있어야 한다.

루트 파일에는 저장소 전체의 규칙을 둔다. 예를 들어 "패키지 간 직접 참조 금지", "공통 타입은 packages/shared를 통한다", "CI 통과 전 머지 금지" 같은 것이다. 웹이든 API든 모두에게 해당하는 것들이다.

하위 앱의 CLAUDE.md에는 비로소 각자의 세부 규칙을 둔다. apps/web/CLAUDE.md에는 Server Component 원칙, 디자인 시스템 사용법, 라우팅 규칙을 쓰고, apps/api/CLAUDE.md에는 인증 미들웨어, 응답 형식, 마이그레이션 절차를 쓴다. 이렇게 해야 프론트 작업 중에 SQL 규칙이 계속 끼어들지 않는다.

여기서 한 단계 더 가면 .claude/rules/가 유용해진다. 경로 기반 규칙은 필요한 파일을 다룰 때만 활성화되므로, 루트 CLAUDE.md를 비대하게 만들지 않고도 높은 우선순위의 지침을 유지할 수 있다.⁵ 예를 들어 supabase/migrations/에서만 적용되는 마이그레이션 규칙, src/api/에서만 적용되는 응답 형식 규칙을 따로 둘 수 있다.

중요한 원칙은 하나다. 같은 규칙을 여러 층에 중복해서 쓰지 않는다. 중복이 많아질수록 충돌이 생기고, 나중에는 어느 쪽이 최신인지 사람도 모르게 된다. 공통은 위로, 특수는 아래로 내린다. 이 단순한 원칙만 지켜도 모노레포의 절반은 정리된다.

솔로 빌더답게 운영하라

좋은 CLAUDE.md는 한 번에 완성되지 않는다. 제품처럼 다뤄야 한다. 실제로 써 보고, 틀린 지점을 발견하고, 문장을 고치고, 불필요한 설명을 덜어내야 한다. 중요한 것은 "많이 쓰는 것"이 아니라 "계속 다듬는 것"이다.

혼자 만드는 제품에서는 특히 다음 리듬이 잘 맞는다.

• 첫날에는 /init로 초안을 만든 뒤, 명령어와 금지 사항만 바로잡는다.

• 첫 주에는 Claude가 반복해서 틀리는 부분만 추가한다.

• 둘째 주부터는 새 규칙을 넣기보다 죽은 규칙을 지우는 데 더 많은 시간을 쓴다.

• 한 달에 한 번은 "이 규칙이 아직도 유효한가?"만 점검한다.

이 과정을 거치면 CLAUDE.md는 점점 길어지지 않고, 오히려 더 날카로워진다. 그 상태가 가장 좋다. 헌법은 두꺼워서 권위가 생기는 문서가 아니다. 혼란스러운 순간에 바로 판단 기준이 되어 주는 문서다.

솔로 빌더에게 CLAUDE.md는 문서가 아니라 분신에 가깝다. 내가 자주 하는 설명, 내가 싫어하는 실수, 내가 지키고 싶은 구조를 대신 말해 준다. 그리고 그 한 장이, 프롬프트 열 장보다 오래 간다.

참고

¹Claude's new constitution

²Using CLAUDE.md files: Customizing Claude Code for your codebase

³Best Practices for Claude Code

⁴The Complete Guide to CLAUDE.md Rules for 2025

⁵Claude Code Rules Directory: Modular Instructions That Scale

⁶Claude Code's Four-Part Environment Setup: CLAUDE.md, Rules, Memory, and Hooks Explained