컨텍스트 엔지니어링 1: CLAUDE.md로 영속 지침 만들기
Claude Code는 세션을 새로 시작할 때마다 "대화 맥락"은 초기화됩니다. 그래서 같은 프로젝트라도 매번 똑같은 설명(빌드 방법, 테스트 명령, 폴더 구조, 금지 규칙)을 반복하게 됩니다. 이 반복을 없애는 가장 강력한 장치가 CLAUDE.md입니다.
CLAUDE.md의 역할은 단순한 문서가 아니라, 팀 표준을 매 세션의 기본값으로 깔아두는 것입니다. 잘 만든 CLAUDE.md는 "설명"을 줄이는 동시에 "편차"를 줄입니다. 즉, 개인의 프롬프트 품질에 의존하던 습관을 프로젝트 규칙과 워크플로로 자동 강제하는 쪽으로 바꿉니다.
이 챕터의 목표는 하나입니다.
전역/프로젝트/하위 디렉터리
CLAUDE.md의 구조를 잡고무엇을 넣고/빼야 하는지 원칙을 세우며
내용이 커졌을 때
@import와.claude/rules/로 모듈화하는 전략을 설계합니다.
1) CLAUDE.md의 계층: "범위가 좁을수록 강하다"
CLAUDE.md는 한 파일로 끝나는 설정이 아닙니다. 같은 이름의 파일이 여러 위치에 존재할 수 있고, Claude Code는 이를 계층적으로 합쳐서 사용합니다. 중요한 직관은 이겁니다.
넓은 범위(전사/개인/루트) 규칙은 기본값을 만들고, 더 좁은 범위(특정 폴더/특정 파일 유형) 규칙이 예외와 세부를 덮어쓴다.
실무에서는 다음 3단을 기준으로 설계하면 대부분 해결됩니다.
전역(개인/조직): 어떤 프로젝트에서도 변하지 않는 원칙과 선호
프로젝트(팀 공유): 이 저장소에서만 통하는 표준과 명령
하위 디렉터리(모듈/패키지): 모노레포/멀티스택에서 폴더별 예외
여기에 .claude/rules/가 들어오면, "하위 디렉터리보다 더 세밀하게" 파일 패턴 단위로 지침을 걸 수 있습니다(예: src/api/**/*.ts에만 API 규칙 적용).
2) 로딩 규칙을 이해해야 '의도한 대로' 먹힌다
시작 시 로딩: 현재 작업 디렉터리에서 위로
Claude Code는 현재 작업 디렉터리(cwd)에서 시작해 상위 디렉터리를 타고 올라가며 CLAUDE.md를 찾습니다. 그래서 모노레포에서 packages/web/에서 실행하면, 루트의 CLAUDE.md와 packages/web/CLAUDE.md가 함께 잡힙니다.
이 규칙이 주는 설계 힌트는 명확합니다.
루트
CLAUDE.md는 "공통 규약"만 담아야 합니다.패키지/서비스별 차이는 해당 폴더의
CLAUDE.md로 내려보냅니다.
필요할 때 로딩: 하위 디렉터리의 CLAUDE.md는 "온디맨드"
현재 작업 디렉터리 아래쪽(서브트리)에 있는 CLAUDE.md는 기본적으로 전부를 시작할 때 다 읽지 않습니다. Claude가 그 디렉터리의 파일을 실제로 읽을 때(작업 범위가 그쪽으로 들어갈 때) 로딩되는 방식입니다.
이 특성 덕분에, 대규모 저장소에서도 "필요한 규칙만" 따라오게 만들 수 있습니다. 즉, 하위 디렉터리 CLAUDE.md는 컨텍스트 소음(noise)을 줄이는 설계 도구입니다.
3) 어디에 무엇을 둘 것인가: 전역/프로젝트/하위 설계
전역(개인) ~/.claude/CLAUDE.md: '당신의 기본 작업 습관'
전역 파일에는 프로젝트를 바꿔도 계속 유효한 내용만 넣습니다. 예를 들면 다음이 여기에 어울립니다.
응답 언어/톤(예: 한국어, 간결하게)
기본 검증 습관(예: "명령 실행 전 어떤 명령을 돌릴지 먼저 요약")
커밋 메시지 취향(예: Conventional Commits 선호)
반대로, 특정 프로젝트에서만 쓰는 경로/명령/아키텍처는 전역에 넣지 않습니다. 전역을 더럽히면 다른 프로젝트에서 Claude가 잘못된 가정을 시작점으로 삼습니다.
프로젝트(팀 공유) ./CLAUDE.md 또는 ./.claude/CLAUDE.md: '팀 표준의 단일 진실 소스'
프로젝트 파일은 저장소에 커밋합니다. 이 파일이 존재한다는 것 자체가 팀에 주는 이점이 큽니다.
온보딩 시간이 줄고
"어떤 명령을 돌려야 하는지"를 AI가 추측하지 않게 되고
코드 리뷰에서 반복되는 지적이 규칙으로 고정됩니다.
여기에는 다음 네 덩어리가 핵심입니다.
무엇(WHAT): 프로젝트 개요, 기술 스택, 폴더 지도
어디(WHERE): 중요한 경계(수정 금지 디렉터리, 생성물 위치)
왜(WHY): 핵심 의사결정(특이한 선택의 이유)
검증(HOW TO VERIFY): 빌드/테스트/린트의 "정확한" 커맨드
이 네 가지는 앞선 챕터에서 다룬 프롬프트 기본기와도 연결됩니다. 차이는, 이제부터는 "프롬프트로 매번 말하는 대신 파일에 고정"한다는 점입니다.
하위 디렉터리 subdir/CLAUDE.md: '모듈별 예외 규칙'
하위 파일은 다음 상황에서 특히 효과적입니다.
모노레포에서 패키지마다 스택이 다를 때(웹/백엔드/모바일)
동일 언어라도 규칙이 다른 영역이 있을 때(예:
infra/는 IaC 규칙,app/은 제품 코드 규칙)"여기는 건드리면 위험하다" 같은 로컬 금지 구역을 표시하고 싶을 때
하위 CLAUDE.md는 해당 폴더를 작업하기 전에는 로딩되지 않으므로, 루트에 넣기엔 너무 무겁거나 특정한 내용을 이쪽으로 빼면 컨텍스트 효율이 좋아집니다.
4) 포함/제외 원칙: 한 줄이 '매 세션 비용'이라는 감각
CLAUDE.md는 매 세션 시작 시 컨텍스트에 들어가므로, 한 줄이 곧 매 세션 비용입니다. 따라서 다음 질문으로 필터링합니다.
"이 줄이 없으면 Claude가 자주 틀리는가?"
포함해야 하는 것
세션마다 반복되는 설명을 제거하고, 잘못된 추측을 막는 정보가 우선입니다.
정확한 명령: dev/build/test/lint/typecheck, 단일 테스트 실행법
프로젝트 구조 지도: 어디에 무엇이 있는지(특히 비표준 구조)
중요 경계/금지: 생성물 디렉터리, 마이그레이션 정책, 보안 민감 구역
팀 워크플로: 작업 흐름(탐색→계획→실행), 커밋 전 체크리스트
프로젝트 특유의 '함정': 과거에 반복된 실수(예: 특정 폴더의 레거시 규칙)
제외해야 하는 것
다음은 넣을수록 오히려 성능이 떨어질 가능성이 큽니다.
"좋은 코드 작성", "베스트 프랙티스 준수" 같은 검증 불가능한 문장
스타일을 장황하게 늘어놓는 포맷터/린터가 대신할 수 있는 규칙
자주 바뀌는 운영 정보(매주 변하는 정책, 일회성 작업 지시)
README/설계서 내용을 통째로 복붙한 장문 설명
핵심은 "반복 설명 제거 + 팀 표준 강제"이지 "모든 지식을 한 파일에 담기"가 아닙니다.
5) .claude/rules/: 루트를 가볍게 유지하는 '규칙 모듈'
프로젝트가 커지면 루트 CLAUDE.md가 비대해집니다. 이때 권장되는 분해 방법이 .claude/rules/입니다.
규칙 파일을 주제별로 쪼갭니다(예:
testing.md,security.md,api-design.md).특히 좋은 점은 경로 스코프(paths)로 조건부 적용이 가능하다는 점입니다.
예를 들어 API 규칙은 프론트엔드에서 불필요한 소음일 수 있습니다. 그럴 때는 아래처럼 "해당 패턴 파일을 읽을 때만" 규칙이 붙도록 만듭니다.
---
paths:
- "src/api/**/*.ts"
- "src/server/**/*.ts"
---
# API 규칙
- 모든 엔드포인트는 입력 검증을 포함한다.
- 에러 응답은 표준 포맷을 사용한다.
- 새 엔드포인트에는 OpenAPI 주석을 추가한다.이 방식은 팀 규모가 커질수록 빛납니다. 프론트 팀이 frontend.md를, 백엔드 팀이 backend.md를 관리해도 루트 파일에서 충돌이 줄고, 규칙 변경이 리뷰하기 쉬워집니다.
6) @import 전략: '가져오되, 루트는 가볍게'
CLAUDE.md는 다른 파일을 @path/to/file 형태로 가져올 수 있습니다. 이 기능은 두 가지 목적에 맞춰 설계하면 좋습니다.
모듈화: 큰 규칙/가이드를 주제별 파일로 나누고, 루트에서 필요한 것만 끌어오기
재사용: 여러 프로젝트에서 공통으로 쓰는 규칙 세트를 공유하기
어떤 것을 import할까
@import는 "루트에 직접 쓰면 길어질 내용"을 뺄 때 유용합니다.
긴 워크플로 문서(예: 배포 절차, 릴리즈 체크리스트)
팀의 Git 규칙(브랜치/커밋/PR 템플릿)
보안 가이드(금지 패턴 모음)
반대로, 루트에 반드시 있어야 하는 것은 여전히 루트에 둡니다. 프로젝트 소개 2~3문장, 핵심 명령, 가장 치명적인 금지 규칙 같은 것들입니다.
import 설계 규칙(권장)
@import는 강력하지만, 무작정 늘리면 "어디에 뭐가 있는지"가 더 어려워집니다. 다음 원칙을 추천합니다.
루트에는 '목차'처럼 링크한다: 주제별 문서의 위치를 한눈에 보이게
파일 하나 = 주제 하나: 테스트 규칙 파일에 API 규칙이 섞이지 않게
깊이는 얕게: 재귀 import는 편하지만, 깊어질수록 디버깅이 어렵습니다
또한 import는 코드 블록/인라인 코드 안에서는 해석되지 않는다는 점을 염두에 두세요. 즉, @docs/rules.md를 "예시 코드 블록"에 넣어도 실제로 로딩되지 않습니다.
공유 vs 개인: 팀 파일에 '개인 파일'을 달아두는 패턴
팀이 공유하는 CLAUDE.md에, 각자 로컬에만 존재하는 파일을 import해 개인화할 수도 있습니다.
## 개인 선호(로컬)
- @~/.claude/my-project-overrides.md이렇게 하면 팀 파일은 그대로 커밋하면서도, 개인별 작업 방식(예: 선호 에디터, 출력 형식, 로컬 포트)을 따로 유지할 수 있습니다.
7) 추천 디렉터리 설계(프로젝트 규모별)
소규모(단일 앱) 추천
루트 CLAUDE.md 하나로 시작합니다. 60~120줄 정도로 충분합니다.
your-project/
CLAUDE.md
src/
tests/중규모(규칙이 늘기 시작) 추천
규칙은 .claude/rules/로 빼고, 루트는 "프로젝트 지도 + 명령 + 핵심 금지"만 유지합니다.
your-project/
CLAUDE.md
.claude/
rules/
testing.md
security.md
api-design.md모노레포(패키지별 스택 상이) 추천
루트는 공통 규약, 패키지 폴더는 스택/관례를 담습니다.
monorepo/
CLAUDE.md # 공통: 실행 방식, 공통 도구, Git/PR 규칙
packages/
web/
CLAUDE.md # 웹: 컴포넌트 규칙, 상태관리, UI 테스트
api/
CLAUDE.md # API: 라우팅, 인증, DB 접근 규칙
.claude/
rules/
security.md # 공통 보안 규칙(필요시 paths로 제한)이 구조에서 중요한 것은 "공통을 루트로 올리고, 예외는 아래로 내리는 것"입니다. 루트가 예외로 가득 차면, 모든 패키지에서 그 예외까지 매번 읽게 되어 토큰을 낭비합니다.
8) 바로 쓸 수 있는 프로젝트 CLAUDE.md 템플릿
아래 템플릿은 '지금 당장 커밋 가능한 수준'의 뼈대입니다. 프로젝트에 맞춰 대괄호만 채우고, 불필요한 문장은 과감히 삭제하세요.
# [프로젝트 이름]
[한 문단: 이 프로젝트가 무엇인지 + 핵심 스택/런타임]
## 빠른 지도(Where)
- `src/`:
- `tests/`:
- `docs/`:
## 핵심 명령(How to verify)
- Dev: `[명령]`
- Build: `[명령]`
- Test: `[명령]`
- Lint/Format: `[명령]`
- Typecheck: `[명령]`
## 작업 규칙(Workflow)
- 변경 전: 관련 파일을 먼저 탐색하고, 필요하면 계획을 제시한 뒤 수정한다.
- 변경 후: 위의 Build/Test/Typecheck를 실행해 결과를 확인한다.
- 커밋은 가능한 한 작은 단위로 나눈다.
## 금지/주의(Guardrails)
- 절대 수정 금지: `[예: generated/, migrations/, vendor/]`
- 비밀정보: `.env*` 파일 내용은 읽거나 출력하지 않는다.
- 의존성 추가: 새 패키지 추가는 먼저 요청한다.
## 심화 문서(필요할 때만)
- 아키텍처: @docs/architecture.md
- API 규칙: @docs/api-guidelines.md
- 테스트 전략: @docs/testing.md9) 유지보수 원칙: '규칙도 리팩터링 대상'
CLAUDE.md는 한 번 만들고 끝나지 않습니다. 오히려 잘 쓰는 팀은 규칙을 계속 다듬어서 반복 실수의 비용을 줄입니다.
권장 루틴은 단순합니다.
Claude가 같은 실수를 2번 하면, 그때 규칙으로 고정할지 판단합니다.
규칙이 200줄을 넘기기 시작하면,
.claude/rules/또는@import로 분해합니다.규칙이 서로 충돌하기 시작하면(예: 루트와 하위에서 서로 다른 지시), "어느 것이 진짜 표준인지"를 먼저 정하고 문장을 정리합니다.
규칙이 늘어나는 건 자연스러운 일입니다. 문제는 "늘어나는 것"이 아니라 "잡음이 되는 것"입니다. 이 챕터의 구조대로 계층과 모듈화를 잡아두면, 컨텍스트는 커져도 품질은 무너지지 않습니다.
다음 챕터에서는 이렇게 만들어둔 영속 지침을 세션 운영으로 연결합니다. /clear와 /compact, 세션 분리, 그리고 두 번 수정 규칙으로 컨텍스트를 항상 신선하게 유지하는 운영법을 다룹니다.
이 노트는 보도·비평·교육·연구 목적으로 작성되었습니다. 저작권 문의가 있으시면 에서 알려주세요.