CLAUDE.md를 현명하게 쓰는 법 — 2026년 최신 조언
적게, 정확하게, 자주 업데이트 — 실무에서 검증된 CLAUDE.md 고급 활용 7가지 조언.
한 줄 요약: CLAUDE.md를 잘 쓰는 핵심은 '적게, 정확하게, 자주 업데이트'다. 2026년 기준 실무에서 검증된 7가지 조언을 정리했다.
CLAUDE.md의 기본 구조는 가이드 #2에서 다뤘다. 이 글은 그 다음 단계다. '작성했는데 Claude가 무시한다', '길게 썼는데 효과가 없다', '팀원마다 제각각이다' — 이런 문제를 겪고 있다면 이 조언들이 직접적인 답이 된다.
조언 1 — 결과물 기준으로 작성하라
CLAUDE.md에서 가장 흔한 실수는 의도를 쓰는 것이다. Claude는 의도가 아닌 지시를 따른다.
비교해보자.
| 약한 지시 | 강한 지시 |
|---|---|
| TypeScript를 사용해 | 모든 함수에 반환 타입을 명시해. void도 예외 없음. |
| 코드를 깔끔하게 써 | 함수 하나는 하나의 역할만. 20줄 초과 시 분리해. |
| 주석을 달아줘 | 공개 함수에 JSDoc 주석 필수. 파라미터 타입과 반환값 설명 포함. |
행동 지시는 Claude가 무엇을 해야 하는지를 알려준다. 결과 기대치는 어떤 상태여야 하는지를 알려준다. 결과 기대치가 훨씬 명확하고 검증 가능하다.
"코드 품질을 높여줘"는 지시가 아니다. 모호한 바람이다. Claude는 그 모호함 안에서 자기 판단으로 채운다.
조언 2 — 나쁜 예시를 함께 넣어라
좋은 패턴만 보여주면 Claude는 거기서 변형을 만들어낸다. 의도와 다른 방향으로. 이유는 단순하다. Claude는 학습된 패턴의 집합이기 때문에, 제약이 없으면 자신이 '자연스럽다'고 판단하는 쪽으로 간다.
"이렇게 하지 마라" 섹션은 그 자연스러운 이탈을 막는다.
CLAUDE.md — 나쁜 예시 포함 작성법## 에러 처리 ### 해야 하는 것 - try/catch 블록에서 에러 타입을 명시적으로 확인 - 사용자에게 의미 있는 메시지 반환 - 에러 로그는 반드시 error 객체 포함 ### 하지 말아야 하는 것 - catch (e) {} 빈 블록 금지 - console.error('에러 발생') 같은 context 없는 로그 금지 - throw new Error('뭔가 잘못됨') 같은 무의미한 메시지 금지 나쁜 예: catch (e) { console.error('에러 발생'); } 좋은 예: catch (e) { logger.error({ err: e, context: 'fetchUser', userId }); throw new AppError('USER_FETCH_FAILED', { cause: e }); }
이 접근법이 효과적인 이유가 하나 더 있다. 새로운 팀원이 프로젝트에 합류할 때, CLAUDE.md의 나쁜 예시 섹션은 그 자체로 코드 리뷰 기준이 된다. Claude만이 아니라 사람도 읽는 문서다.
조언 3 — 세션 시작 자동 작업을 정의하라
Claude Code는 세션 시작 시 CLAUDE.md를 읽는다. 이 타이밍을 활용해서 매번 반복할 필요 없는 지시를 자동화할 수 있다.
실무에서 검증된 세션 행동 규칙 예시:
- 파일 우선 읽기: "이 프로젝트에서 작업 시작 전
data/posts.js와RULE.md를 먼저 읽어라" - 커밋 메시지 형식 강제: "커밋을 생성할 때마다 [타입]: 설명 형식을 제안해라"
- 검증 명령 자동 실행: "JS 파일 수정 후 반드시
node --check {파일}을 실행해라" - 참조 금지 명시: "외부 API 호출 없이 로컬 파일만 참조해라 (인터넷 없는 환경)"
이 규칙들이 없으면 매 세션마다 같은 말을 반복하게 된다. 세션 행동 규칙은 그 반복을 제거한다.
세션 시작 행동 규칙 예시## 세션 시작 체크리스트 1. 이 파일(CLAUDE.md)을 다 읽었는지 확인해라 2. `data/posts.js`를 열어서 현재 포스트 수를 파악해라 3. 작업 전 `git status`로 변경사항을 확인해라 4. JS 파일 수정 시 항상 `node --check {파일}`로 검증해라 5. 커밋 메시지는 항상 제안 후 확인을 받아라
조언 4 — 계층 구조를 활용하라
Claude Code는 루트 CLAUDE.md뿐 아니라 하위 디렉토리의 CLAUDE.md도 읽는다. 이 계층 구조를 활용하면 공통 규칙과 디렉토리 특화 규칙을 분리할 수 있다.
계층형 CLAUDE.md 구조 예시project-root/ ├── CLAUDE.md ← 전체 프로젝트 공통 규칙 │ (코딩 표준, 커밋 형식, 금지 사항) ├── pages/ │ └── CLAUDE.md ← 페이지 컴포넌트 특화 규칙 │ (라우팅 규칙, SEO 메타 필수 여부) ├── api/ │ └── CLAUDE.md ← API 레이어 특화 규칙 │ (인증 미들웨어 필수, 응답 형식) └── data/ └── CLAUDE.md ← 데이터 파일 특화 규칙 (스키마 검증 필수, ID 체계)
루트 CLAUDE.md가 너무 길어진다면 계층 구조로 분산하는 게 낫다. 공통 규칙은 루트에, 특화 규칙은 해당 디렉토리에.
이 방식의 실질적인 장점은 두 가지다. 첫째, 루트 파일이 짧아져서 토큰 비용이 줄어든다. 둘째, Claude가 특정 디렉토리 작업 중일 때 관련 규칙만 더 강하게 인식한다.
조언 5 — 자주 업데이트하라
CLAUDE.md를 한 번 작성하고 방치하는 건 오히려 역효과를 낸다. 프로젝트가 바뀌면 CLAUDE.md도 바뀌어야 한다.
오래된 규칙이 현재 코드와 충돌하는 상황을 생각해보자. CLAUDE.md에는 "Redux를 사용해"라고 적혀 있는데, 코드베이스는 이미 Zustand로 마이그레이션됐다면? Claude는 두 신호를 동시에 받는다. CLAUDE.md의 지시와 실제 코드의 패턴. 이때 Claude는 어느 쪽을 따라야 할지 판단해야 하고, 그 판단이 항상 의도대로 되지는 않는다.
업데이트 트리거 목록:
- 주요 라이브러리 교체 또는 추가
- 디렉토리 구조 변경
- 코딩 컨벤션 변경 결정
- 배포 환경 변경
- Claude가 반복적으로 같은 실수를 할 때 (규칙이 없다는 신호)
마지막 항목이 중요하다. Claude가 세 번 이상 같은 방향으로 틀린다면, CLAUDE.md에 해당 규칙이 없다는 뜻이다. 그 자리에 추가하면 된다.
조언 6 — 토큰 비용을 의식하라
CLAUDE.md는 매 세션마다 읽힌다. 길수록 토큰을 많이 소비한다. Claude Code를 많이 쓸수록, 또는 Pro/Max 플랜 한도를 자주 건드린다면 이 비용이 쌓인다.
실제 측정 기준은 아니지만, 경험적으로 CLAUDE.md가 200줄을 넘어가면 '정말 다 필요한가'를 점검할 시점이다.
토큰 효율을 높이는 전략:
- 핵심만 루트에 유지: 모든 규칙을 한 파일에 쑤셔 넣지 말고, 세부 규칙은 보조 파일(RULE.md, SKILL.md 등)로 분리
- 보조 파일 참조 방식: CLAUDE.md 안에 "세부 규칙은 RULE.md 참조"라고 명시하고, 필요할 때 그 파일을 읽도록 지시
- 중복 제거: 같은 내용이 두 곳에 있으면 한 곳을 삭제. 중복은 명확성이 아니라 혼란을 만든다
- 예시는 간결하게: 좋은 예시 한 쌍이면 충분. 세 쌍은 불필요하다
보조 파일 분리 패턴## CLAUDE.md (루트 — 핵심 규칙만) ## 세부 규칙 파일 - 코딩 컨벤션 세부: RULE.md 참조 - 포스팅 작업 방식: SKILL.md 참조 - 콘텐츠 수집 규칙: INGESTION_RULES.md 참조 작업 전에 관련 파일을 읽어라. 모든 파일을 매번 읽을 필요는 없다. 포스팅 작업 → SKILL.md 필수 데이터 수집 작업 → INGESTION_RULES.md 필수
조언 7 — 팀 공유 전략
CLAUDE.md는 git에 커밋해야 한다. 그래야 팀 전체가 동일한 규칙을 적용받는다. 특정 개발자의 로컬에만 있는 CLAUDE.md는 없는 것과 같다.
팀 공유 시 고려할 역할 분리:
| 파일 | 역할 | git 커밋 |
|---|---|---|
CLAUDE.md | 프로젝트 공통 규칙, 코딩 표준 | 필수 |
.claude/settings.json | 도구 허용/차단 설정, 환경 변수 | 권장 (민감정보 제외) |
.claude/settings.local.json | 개인 환경 설정 (경로, 키 등) | .gitignore 처리 |
CLAUDE.md와 .claude/settings.json의 역할 차이: CLAUDE.md는 "무엇을 해야 하는가"를 정의한다. settings.json은 "어떤 도구를 사용할 수 있는가"를 정의한다. 두 파일이 충돌하는 영역은 없다. 서로 보완적이다.
팀이 크다면 CLAUDE.md 변경을 PR 리뷰 대상에 포함시키는 것을 권장한다. CLAUDE.md 변경은 모든 팀원의 Claude 행동을 바꾼다. 코드 변경만큼 중요하게 다뤄야 한다.
Claude가 CLAUDE.md 지시와 반대로 행동한다면 두 가지를 확인해라. 첫째, 규칙이 모호하게 작성돼 있지 않은지. 둘째, 코드베이스 자체가 규칙과 다른 패턴으로 쌓여 있지 않은지. Claude는 CLAUDE.md와 실제 코드 양쪽에서 신호를 받는다. 실제 코드의 패턴이 압도적으로 많으면 그쪽으로 기운다.
규칙이 너무 많으면 Claude는 어떤 규칙을 우선해야 할지 판단하다 정작 중요한 규칙을 흘려보낸다. 경험적으로 핵심 규칙 10~15개가 잡다한 규칙 40개보다 효과적이다. 규칙을 추가할 때마다 "이게 없으면 실제로 문제가 생기는가"를 자문해라.
빈 파일에서 시작하지 말고 역방향으로 접근해라. 지난 한 달간 Claude에게 반복해서 말한 것들을 모아라. 그게 CLAUDE.md에 들어가야 할 내용이다. 처음부터 완벽한 CLAUDE.md를 만들 필요는 없다. 작게 시작하고 반복적으로 추가하는 것이 낫다.
7가지 조언 요약
- 결과물 기준으로 작성: "TypeScript 써"가 아니라 "모든 함수에 반환 타입 명시"
- 나쁜 예시 포함: "이렇게 하지 마라" 섹션이 좋은 예시만큼 중요하다
- 세션 행동 규칙 정의: 매번 반복하는 지시를 CLAUDE.md에 한 번 써라
- 계층 구조 활용: 루트는 공통 규칙, 하위 디렉토리는 특화 규칙
- 자주 업데이트: 프로젝트가 바뀌면 CLAUDE.md도 바뀌어야 한다
- 토큰 비용 의식: 핵심만 루트에, 세부는 보조 파일로 분리
- 팀 공유: git 커밋 필수, CLAUDE.md 변경은 PR 리뷰 대상