같은 말을 세 번 하기 싫어서 정리한 CLAUDE.md 작성법

Claude Code를 쓰다 보면 같은 말을 반복하게 되는 순간이 옵니다. "공통 컴포넌트 있으니까 새로 만들지 마", "색은 토큰으로 써", "답변은 한국어로". 새 세션을 열 때마다 이걸 다시 말하다가, 이걸 CLAUDE.md에 적어 두면 된다는 걸 뒤늦게 알았습니다.

Claude Code는 세션을 시작할 때 프로젝트 루트의 CLAUDE.md를 읽어서 컨텍스트에 넣습니다. 그러니까 이 파일은 모든 대화의 첫 문단인 셈입니다. 잘 써 두면 같은 설명을 반복할 필요가 없고, 대충 써 두면 매번 쓸모없는 내용으로 컨텍스트만 차지합니다. 이 글에서는 제가 몇 번 고쳐 쓰면서 정리한 작성 기준을 공유합니다.

1. CLAUDE.md는 어디에 두나요

세 군데에 둘 수 있습니다.

~/.claude/CLAUDE.md는 내 모든 프로젝트에 공통으로 적용됩니다. 응답 언어 같은 개인 취향은 여기에 둡니다. 프로젝트 루트의 CLAUDE.md는 그 저장소의 규칙이고, 팀과 공유하려고 커밋합니다. 하위 폴더에 두면 그 폴더에서 작업할 때 추가로 읽힙니다.

참고로 이 블로그 저장소의 CLAUDE.md는 딱 한 줄입니다.

@AGENTS.md

@경로는 다른 파일을 불러오는 문법입니다. 다른 AI 도구와 규칙을 같이 쓰려고 실제 내용은 AGENTS.md에 두고, CLAUDE.md에서는 그 파일만 가리키게 했습니다.

2. 무엇을 넣어야 하나요

기준은 하나로 정했습니다. 코드를 읽어서 알 수 있는 건 쓰지 않는다. 폴더 구조나 쓰는 라이브러리 목록은 에이전트가 알아서 찾아봅니다. 대신 코드만 봐서는 알 수 없는 것들을 씁니다.

2-1. 하지 말 것과 선호하는 방식

## 컴포넌트
- 새 UI를 만들기 전에 `src/shared/ui/`를 먼저 확인한다. 있는 컴포넌트는 반드시 재사용한다.
- 같은 역할의 컴포넌트를 화면 폴더에 새로 만들지 않는다(중복 생성 금지).
- 필요한 variant가 없으면 공용 컴포넌트에 prop을 추가한다.
 
## 스타일
- 색·간격·반경은 디자인 토큰(CSS 변수)만 쓴다. hex 값을 직접 쓰지 않는다.
- Tailwind 설정과 NativeWind 설정은 같은 토큰 파일을 공유한다. 한쪽만 고치지 않는다.

Tailwind와 NativeWind 규칙은 Expo로 모바일 앱 프로토타입을 만들 때 추가한 겁니다. 웹 쪽 토큰만 바꾸고 앱 쪽을 안 바꿔서 색이 어긋난 적이 있었거든요.

2-2. 끝났다고 말하기 전에 돌릴 것

에이전트가 "다 됐습니다"라고 하기 전에 무엇을 확인해야 하는지 적어 둡니다. 이게 없으면 확인 없이 끝내는 경우가 많습니다.

## 완료 조건
- `pnpm typecheck` (strict) 통과
- 화면을 바꿨다면 `pnpm e2e -- <해당 spec>` 통과
- UI 변경은 라이트/다크 스크린샷을 첨부

2-3. 이 프로젝트에만 있는 함정

## 주의
- 이 프로젝트의 Next.js는 학습 데이터와 API가 다를 수 있다.
  코드를 쓰기 전에 node_modules/next/dist/docs/ 의 해당 가이드를 먼저 읽는다.
- 지도 좌표는 내부적으로 EPSG:3857이다. API 응답(EPSG:4326)을 그대로 넣지 않는다.

첫 번째 항목은 이 블로그의 AGENTS.md에 실제로 들어 있는 문장입니다. 프레임워크 버전이 올라간 지 얼마 안 됐을 때, 에이전트가 예전 API로 코드를 쓰는 걸 막아 줍니다.

2-4. 대화하는 방식

## 응답
- 설명은 한국어로, 코드 식별자는 원문 그대로.
- 큰 변경은 계획을 먼저 보여 주고 승인 후 진행한다.

3. 무엇을 빼야 하나요

처음 쓴 CLAUDE.md는 길었습니다. 프로젝트 배경, 팀 소개, 기술 스택 설명까지 다 넣었는데, 지금 보면 대부분 필요 없는 내용이었습니다.

배경 설명은 규칙이 아닙니다. package.json에 이미 있는 스크립트 목록을 다시 쓸 필요도 없습니다. "깔끔하게 작성한다", "성능을 고려한다" 같은 문장은 지킬 수가 없는 규칙입니다. 이런 건 "컴포넌트 파일이 200줄을 넘으면 나눈다"처럼 확인할 수 있는 문장으로 바꿔야 합니다.

그리고 규칙이 많을수록 정작 중요한 규칙이 묻힙니다. 그래서 자세한 내용은 docs/에 두고, CLAUDE.md에서는 위치만 알려 주는 쪽으로 바꿨습니다.

## 문서
- 아키텍처: docs/architecture.md
- 컴포넌트 목록: docs/components.md (새 UI 작업 전 필독)
- 모션: docs/motion.md

4. 같은 지적이 세 번 나오면 규칙으로

Figma 디자인을 화면으로 옮기는 작업에서 같은 말을 몇 번이나 했습니다. "고정 폭 말고 auto-layout의 hug처럼 내용에 맞춰", "헤더 높이를 옆 패널이랑 맞춰". 세 번째쯤 같은 말을 하고 나서 그냥 규칙으로 옮겼습니다.

## Figma → 코드
- Figma의 auto-layout "hug"는 고정 width/height가 아니라 내용 크기(fit-content)로 옮긴다.
- 같은 행에 놓인 패널의 헤더 높이는 하나의 토큰(--header-h)으로 맞춘다.

Claude Code에는 대화 중에 알게 된 걸 저장해 두는 메모리 기능도 있습니다. 저는 팀 전체에 해당하는 규칙은 CLAUDE.md에, 저와 에이전트 사이의 작업 습관은 메모리에 두는 식으로 나눠 쓰고 있습니다.

5. 고친 다음에는 이렇게 확인합니다

CLAUDE.md를 고치고 나면 새 세션을 열어서 "이 프로젝트에서 버튼이 필요하면 어떻게 해?"라고 물어봅니다. 규칙대로 답하면 잘 적은 거고, 엉뚱한 답이 나오면 문장이 모호한 겁니다. 그 밖에 각 규칙이 확인 가능한 문장인지, 코드에 이미 있는 내용을 또 쓰진 않았는지, 완료 조건이 들어 있는지 정도를 같이 봅니다.

마치며

CLAUDE.md는 한 번 쓰고 끝나는 문서가 아니었습니다. 저는 에이전트에게 같은 말을 두 번 하게 되면 그때 한 줄씩 추가합니다. 처음부터 완벽하게 쓰려고 하기보다, 오늘 반복한 지적 하나를 옮겨 적는 것부터 시작해 보시길 권합니다.

다음 글에서는 에이전트가 디자인과 브라우저를 직접 볼 수 있게 해 주는 MCP 이야기를 해 보겠습니다.