200줄은 상한이 아니라 임계다 — CLAUDE.md의 4계층 Scope와 3덩어리 7단계

AI에게 팀의 일하는 방식을 알려주는 방법은 두 가지다. 매 대화마다 다시 설명하거나, 한 번 파일에 적어 두고 매 세션이 그것을 읽게 하거나. 앞은 사람마다 다른 결과가 나오고 뒤는 저장소에 커밋되어 리뷰 대상이 된다.

이 시리즈는 뒤쪽을 다룬다. 첫 편인 이 글은 규칙 파일 자체 — 어디에 두면 어디까지 적용되는지, 얼마나 길게 쓸 수 있는지, 무엇을 어떤 순서로 적는지 — 를 본다. 이어지는 편은 그 파일 주변에 붙는 .claude/ 구성물과, 세션이 길어질 때 컨텍스트를 관리하는 법을 다룬다.

이 글이 옮긴 원 자료의 작성 기준일은 2026-07-26이다. 파일 경로·명령 이름·임계값은 그 시점의 것이며 버전에 따라 바뀐다.

이 글의 예시 프로젝트·수치(고객사 수, 스택 조합, 금지 항목 목록 등)와 빈 템플릿의 내용은 원 자료의 실습 예제이며 특정 조직의 실제 운영 사례가 아니다. 개념·용어·판단 프레임 층위에서 읽어야 한다.

용어 정리

이 표는 시리즈 세 편이 공유하는 어휘 전량이다. 이어지는 두 편은 여기서 자기 글이 쓰는 행만 추려 다시 싣는다.

정보는 세 층에서 온다

AI가 한 번의 응답을 만들 때 참조하는 정보는 아래 세 층에서 온다. 위로 갈수록 오래 살아남고 넓게 적용되며, 아래로 갈수록 휘발성이 크고 상황에 특화된다.

핵심은 "항상 로드되는 것"과 "필요할 때만 로드되는 것"의 분리다.

네 행 중 위의 셋은 사람이 관리 주기를 정할 수 있고, 맨 아래 대화 이력만 가만히 둬도 저절로 자란다. 그래서 소비량이 가장 큰 항목이 곧 관리 우선순위 1순위가 된다.

CLAUDE.md가 중요한 이유 — 반복 설명을 끝내는 장치

정의와 비유

CLAUDE.md는 세션 시작 시 자동으로 읽히는 마크다운 메모리 파일이다. 내용이 시스템 프롬프트에 주입되어 그 세션의 모든 대화에 영향을 준다.

성격으로 보면 신입 사원 첫날 받는 팀 위키에 해당한다. 팀장이 "우리 팀은 이렇게 일해요"라고 정의한 규칙을, AI 직원이 매번 자동으로 읽는다.

효과는 즉각적이고 관찰 가능하다.

두 행의 차이는 AI의 능력이 아니라 AI가 아는 사실의 양이다. 위 행에서도 코드는 나오고, 다만 팀이 쓰지 않는 방식으로 나온다.

4가지 Scope와 우선순위

네 줄의 공유 범위가 조직 전체 → 팀 → 개인 → 개인의 한 프로젝트로 좁아지고, 우선순위 열도 최상위 → 중간 → 낮음 → 최하위로 같은 방향으로 내려간다. 넓게 공유되는 Scope일수록 등급이 높다.

동작 규칙 세 가지를 구분해야 한다.

• 모든 Scope의 CLAUDE.md는 override가 아니라 누적(accumulate) 방식으로 로드된다.
• 지시가 충돌하면 더 구체적인 Scope가 우선한다(서브디렉토리 > 프로젝트 > 전역).
• Enterprise Scope만 예외로, 항상 최우선이며 사용자가 무력화할 수 없다.

첫째와 둘째를 한 문장으로 붙이면 이렇게 된다 — 전역 규칙은 사라지지 않고 남아 있으며, 같은 항목을 두고 부딪힐 때만 구체적인 쪽이 이긴다.

위 표의 「우선순위」 열과 둘째 규칙의 「더 구체적인 Scope가 우선」은 서로 다른 층위를 말한다 — 이렇게 갈라 읽는 것은 이 글의 정리다. 표의 열은 Scope 자체의 등급이라 넓게 공유될수록 높고, 둘째 규칙은 지시가 실제로 부딪혔을 때의 적용 순서라 좁을수록 이긴다. 원 자료는 두 서술을 같은 절에 나란히 두되 하나로 묶지 않았다. 둘이 같은 방향을 가리키는 유일한 자리가 Enterprise다 — 등급도 최상위이고, 셋째 규칙에 따라 충돌에서도 항상 이기며 사용자가 무력화할 수 없다.

두 메모리 시스템의 분업

작성 주체가 다르다는 첫 행이 나머지를 결정한다. 사람이 쓰는 쪽은 미래형 명령이 되고, AI가 쌓는 쪽은 과거형 기록이 된다.

200줄 — 하드 리밋이 아니라 준수율 임계

200줄은 하드 리밋이 아니라 준수율(adherence) 임계다. 넘어가면 파일이 거부되는 게 아니라, AI가 앞쪽 규칙만 우선시하고 뒤쪽 규칙을 흘리기 시작한다.

이 표가 답하는 질문은 "몇 줄까지 되는가"가 아니라 **"몇 줄부터 규칙이 새기 시작하는가"**다. Anthropic 계열 가이드에서 언급되는 실용 상한은 "150~200 instruction budget" 이며, 규칙이 많아질수록 AI가 앞쪽만 본다는 경향이 근거다.

수치의 유효 조건. 200줄은 규칙 준수율의 임계이며 하드 리밋이 아니다 — 초과해도 파일은 정상 로드된다. 80~120줄은 실무 권장치이지 규격이 아니다. 원 자료가 이 둘을 인용 가능한 수치로 따로 묶으면서 각각에 붙여 둔 단서다.

같은 200줄을 이 카테고리의 다른 글은 「상한」이라 불렀다

이 카테고리의 되돌릴 수 있어야 권한을 넓힌다 편은 규약 파일의 분량 제한을 「200줄 안팎을 상한으로」 라고 적었다. 같은 숫자인데 부르는 이름이 다르다.

두 표현은 서로 다른 층위를 말한다 — 이렇게 가르는 것은 이 글의 정리다. 「상한」은 작성 원칙(실무 규범)이고 「준수율 임계」는 동작 성격(왜 그 값인가)이다. 앞의 글은 어떻게 쓸 것인가에서 그 숫자를 꺼냈고 이 글은 넘으면 무엇이 달라지는가에서 꺼냈다. 앞의 글도 원칙 표의 「이유」 칸에 「길수록 지시가 희석됨」 한 줄로 동작의 방향을 적어 뒀으니 두 글이 어긋나는 것은 아니다. 이 글의 원 자료는 그 희석을 절 하나에 임계값 표로 풀었고, 둘을 나란히 놓고 층위로 가른 것은 이 글이다.

실무에서 초점이 갈리는 지점은 하나다. 넘어도 에러는 나지 않고 뒤쪽 규칙이 조용히 흘려질 뿐이라서, 초과했다는 사실 자체를 모른 채 지나간다. 「상한」이라는 표현은 어디까지 쓸지를 정해 주고, 「준수율 임계」는 그 선을 넘었을 때 무엇이 조용히 달라지는지를 가리킨다.

/init은 초안이지 완성본이 아니다

claude /init은 기존 코드베이스를 분석해 CLAUDE.md 초안을 자동 생성한다. 그 초안에는 단서가 셋 붙는다.

• 팀 검토 필수 — 자동 생성물은 출발점이다.
• 개인 선호 표현을 조직 표준 표현으로 교체한다.
• 자동 감지가 놓친 팀 규칙(PR 프로세스, 브랜치 전략)을 수동으로 추가한다.

셋의 공통점은 도구가 읽을 수 있는 것이 코드뿐이라는 데 있다. 코드에 남지 않는 합의 — 누가 리뷰하는가, 어떤 브랜치 전략을 쓰는가 — 는 자동 생성물에 들어올 수 없다.

이렇게 코드에 남지 않는 합의를 파일로 옮기는 일을 팀 전체로 확장했을 때 무엇을 어떤 순서로 하고, 개인이 빨라진 것이 조직 지표로 전환되었는지를 무엇으로 증명하는지는 개인은 빨라졌는데 조직 지표는 안 움직인다 편에서 따로 다뤘다.

CLAUDE.md 작성법 — 3덩어리 × 7단계

구조 개관

7단계를 3개 의미 덩어리로 묶는다. Miller's Law(7±2)를 적용해 인지 부담을 절반으로 줄이는 구성이다.

세 덩어리가 각각 "여기가 어디인가 / 어떻게 일하는가 / 무엇으로 일하는가"에 대응한다. 원 자료가 이 구성에 붙인 근거는 "Miller's Law(7±2)를 적용해 인지 부담을 절반으로 줄이는 구성이다" 한 줄이고, 3-3-1이라는 배분 자체에 따로 이유를 달지는 않았다. 마지막 덩어리만 단계가 하나인 것을 성격 차이로 읽는 것은 이 글의 정리다.

작성 순서 — 왜 NEVER부터인가

추천 순서는 NEVER → 개요 → Cheatsheet다. 이 3개만으로 30분 안에 초안이 나오고, 다음 날 AI의 동작이 눈에 띄게 달라진다.

작성 순서가 번호 순서와 다르다는 것이 요점이다. 문서의 목차는 1→7이지만 손대는 순서는 6→1→7이며, 기준은 합의 비용이 낮고 효과가 빠른 것이다.

단계별 목적과 체크포인트

일곱 행 중 넷의 체크포인트에 세는 단위가 들어 있다 — 1 개요의 1줄, 2 구조의 5~7줄, 6 NEVER의 5~7개, 7 Cheatsheet의 4분류다. 나머지 셋(스택·코딩 규칙·워크플로우)은 수량 대신 빠뜨리면 안 되는 항목의 이름을 나열한다(메이저 버전·패키지 관리 도구·배포 환경 / 명명 규칙·들여쓰기·필수 패턴 / dev·test·build·deploy·migration). 어느 쪽이든 다 썼는지를 읽어서 판단하지 않고 대조해서 판단하게 만든다는 점은 같다 — 이렇게 갈라 보는 것은 이 글의 정리이며, 원 자료는 이 표 다음 문장을 곧바로 "작성 공식 두 가지를 기억하면 된다"로 이어갈 뿐 표 자체를 요약하지 않는다.

5~7개의 유효 조건. NEVER 항목의 적정 수가 5~7개인 이유는 많으면 핵심이 묻히기 때문이다. 지킬 수 있는 최대치가 아니라 읽히는 최대치라는 뜻이다.

작성 공식 두 가지를 기억하면 된다.

• 단계 1 공식: "이 프로젝트는 [대상]이 [목적]을 위해 [동작]한다. [주요 기술]. [운영 규모/맥락]."
• 단계 4 공식: 팀에서 가장 자주 나오는 코드리뷰 코멘트 3~5개를 그대로 규칙으로 옮긴다.

단계 4 공식이 특히 실용적이다. 새로 규칙을 발명하지 않고, 이미 사람이 사람에게 반복하고 있는 지적을 파일로 승격시키는 것이기 때문이다.

나쁜 예 vs 좋은 예 — 차이는 항상 "구체성"

일곱 행의 나쁜 예는 세 갈래로 갈린다. 첫째는 판정할 수 없는 말이다. 단계 4의 "클린 코드를 작성하라"는 틀린 말이 아니라 판정할 수 없는 말이다 — 반박할 수 없고, 동시에 지켰는지 확인할 수도 없다. 원 자료가 "측정 불가"라고 못 박은 것도 이 항목이다. 단계 6의 "잘 테스트하고 배포하기"도 같은 자리에 선다. "잘"이 어디까지 가야 충족되는지가 문장 안에 없기 때문이다. 둘째는 판정은 되는데 내용이 비어 있는 말이다. 단계 1의 "이 프로젝트는 웹앱입니다"는 참이지만 읽고 나서 아는 것이 늘지 않고, 단계 2의 "src/ — 소스코드"는 폴더 이름을 다시 한 번 풀어 쓴 것에 가깝다. 단계 3의 "Python, FastAPI 사용"과 단계 5의 "npm으로 실행"에는 버전과 정확한 커맨드가 빠져 있다. 셋째는 단계 7처럼 아예 섹션이 없는 경우다. 셋을 같은 결로 묶어 읽는 것은 이 글의 정리이며, 묶는 근거는 결과가 하나로 모인다는 데 있다 — 무엇을 지켜야 하는지를 AI가 스스로 정하게 된다.

"절대 금지"가 효과적인 이유는 명확하다. AI는 "주의하세요"를 선택 사항으로 해석하지만, "절대 금지"는 불가능한 행동으로 처리한다.

빈 템플릿 — 덩어리 1(정체성)

# [프로젝트명]

[한 문단: 이 프로젝트는 [대상]이 [목적]을 위해 [동작]한다.
[주요 기술 1줄]. [운영 규모/맥락 (있으면)].]

## 폴더 구조
[폴더명]/    # [설명]
[폴더명]/    # [설명]
[폴더명]/    # [설명]
[폴더명]/    # [설명]
[폴더명]/    # [설명]

## 기술 스택
- **언어**: [언어 + 버전]
- **프레임워크**: [프레임워크 + 버전]
- **DB**: [DB명]
- **패키지 관리**: [pip/poetry/pnpm/yarn/npm]

빈 템플릿 — 덩어리 2(규칙)

아래 템플릿 안의 중첩 코드블록은 표기 충돌을 피하려고 ~~~로 적었다. 실제 파일에서는 백틱 3개를 쓴다.

## 코딩 규칙
- 명명: [snake_case/camelCase/PascalCase 등]
- 들여쓰기: [2칸/4칸/탭]
- [기타 팀 규칙 — 구체적으로]

## 워크플로우
~~~bash
# 개발
[dev 커맨드]
# 테스트
[test 커맨드]
# 빌드
[build 커맨드]
~~~

## 금지 사항 (NEVER)
- 절대 금지: [하지 말아야 할 것 1]
- 절대 금지: [하지 말아야 할 것 2]
- 절대 금지: [하지 말아야 할 것 3]
- 절대 금지: [하지 말아야 할 것 4]
- 절대 금지: [하지 말아야 할 것 5]

빈 템플릿 — 덩어리 3(실용 도구)

## 자주 쓰는 명령어

### 개발
~~~bash
[자주 쓰는 커맨드 1]
[자주 쓰는 커맨드 2]
~~~

### DB
~~~bash
[DB 관련 커맨드]
~~~

### 배포
~~~bash
[배포 스크립트 경로]
~~~

### 트러블슈팅
~~~bash
[초기화/재설치 커맨드]
~~~

모듈화 — @import로 200줄을 지키는 법

본문이 길어지면 상세를 별도 파일로 빼고 참조만 남긴다.

## 상세 규칙 참조
@.claude/rules/api-design.md
@.claude/rules/security-policy.md
@.claude/rules/database-conventions.md

앞의 세 행 중 셋째만 성격이 다르다. 재귀 한계와 순환 참조는 도구가 알아서 막아 주는 안전장치이고, 파일 부재는 안전장치처럼 보이지만 실제로는 위험 요인이다. 경로에 오타가 나도 에러가 나지 않으므로 규칙 파일 하나가 통째로 빠진 채 세션이 정상적으로 굴러간다. 넷째 행(경로 형식)은 이 대비의 바깥에 있다 — 막아 주는 것도 위험한 것도 아니라 어떤 표기가 통하는지를 알려 주는 지원 범위다.

.claude/rules/ 하위 .md는 자동 발견되어 본문 뒤에 붙는다. 순서 제어가 안 되므로, 중요도가 높은 규칙은 @import로 위치를 명시하는 편이 낫다.

다음 편으로

이 글은 규칙 파일 한 장을 다뤘다. 어디에 두면 어디까지 적용되는지(4 Scope), 얼마나 길게 쓸 수 있는지(200줄 준수율 임계), 무엇을 어떤 순서로 적는지(3덩어리 7단계)까지다.

세 주제를 관통하는 것은 하나다. 분량 제한은 저장 공간의 문제가 아니라 주의력 배분의 문제다. 파일이 길어져서 문제가 되는 게 아니라, 길어지면 뒤쪽이 읽히지 않아서 문제가 된다. @import 모듈화도 총량을 줄이는 기법이 아니라 상시 로드되는 양만 줄이는 기법이다.

이어지는 다음 편은 이 파일 옆에 서는 .claude/ 디렉터리의 여덟 구성물과, 지시 한 줄을 제대로 쓰는 프롬프트 7패턴을 본다.