CLAUDE.md 설계 원칙 — 에이전트의 정체성을 한 파일에 담는 법

-

글로벌 vs 프로젝트 분리, 규칙 충돌 방지, 그리고 "금지 > 지시" 원칙

핵심 요약

  • CLAUDE.md는 에이전트의 정체성이자 행동 기준서다. 매 세션 시작 시 자동으로 로드되기 때문에 여기 적힌 것이 에이전트의 전부다
  • 글로벌(~/.claude/CLAUDE.md)에는 프로젝트를 관통하는 원칙을, 프로젝트 루트 CLAUDE.md에는 해당 프로젝트의 구체적 규칙을 넣어야 한다
  • 규칙이 15개를 넘으면 서로 충돌하기 시작한다. 모호한 지시 10개보다 명확한 금지 5개가 낫다

CLAUDE.md란 무엇인가

Claude Code로 에이전트를 세팅할 때 가장 먼저 만드는 파일이 CLAUDE.md입니다. 이 파일은 에이전트의 작동 지침서이자, 매 세션 시작 시 자동으로 읽히는 유일한 "헌법"입니다.

Claude Code는 세션이 시작될 때 다음 순서로 CLAUDE.md를 자동 로드합니다:

  1. ~/.claude/CLAUDE.md (글로벌)
  2. 프로젝트 루트의 CLAUDE.md

두 파일 모두 컨텍스트 윈도우에 올라갑니다. 즉, 에이전트가 첫 메시지를 받기도 전에 이 내용이 이미 처리된 상태입니다. 파일이 길수록 유효 컨텍스트가 줄고, 내용이 겹칠수록 토큰이 낭비됩니다.

본문

1. 글로벌 CLAUDE.md vs 프로젝트 CLAUDE.md — 무엇을 어디에 넣을 것인가

두 파일의 분리 기준은 명확합니다. "모든 프로젝트에서 동일한가?"면 글로벌, "이 프로젝트에서만 의미 있는가?"면 프로젝트.

글로벌에 넣어야 하는 것:

  • 프로젝트 온톨로지 — 전체 에이전트 목록, 역할, 상태, 관계. 에이전트가 "내가 전체 시스템에서 어디에 위치하는가"를 아는 것은 판단의 기준이 됩니다.
  • 사용자 성향/행동 규칙 — "반박 먼저 제시", "데이터 > 직감", "자율성 존중" 같은 대화 원칙. 모든 프로젝트에서 동일하게 적용되어야 합니다.
  • 에이전트 간 통신 규약 — 메시지 허브 URL, 엔드포인트, 페이로드 형식. 어떤 프로젝트에서든 다른 에이전트와 소통하는 방식은 같아야 합니다.

글로벌을 심링크로 공유하면 하나를 수정할 때 모든 프로젝트에 즉시 반영됩니다:

ln -s ~/.claude/CLAUDE.md /path/to/project/.claude/CLAUDE.md

프로젝트 CLAUDE.md에 넣어야 하는 것:

  • 프로젝트 목적 — "이 에이전트는 무엇을 하는가"의 한 줄 정의.
  • 기술 스택과 환경 — OS, 언어, 프레임워크, 빌드 명령어.
  • 워크플로와 파이프라인 — 작업 흐름, 게이트 조건, 분기 기준.
  • 파일 규칙 — 명명 규칙, 디렉토리 구조, 출력 형식.
  • 해당 프로젝트만의 금지 사항 — "출처 없는 수치 생성 금지"처럼 이 프로젝트에서만 의미 있는 제약.

2. 규칙 15개의 벽 — 왜 많으면 충돌하는가

규칙을 쓰다 보면 자연스럽게 늘어납니다. "이것도 지켜야 하고, 저것도 중요하고..." 문제는 규칙이 15개를 넘어가면 서로 모순되는 쌍이 반드시 생긴다는 점입니다.

충돌이 발생하는 전형적인 패턴: - "사용자의 요청을 빠르게 처리하라" + "복잡한 요청은 인터뷰를 거쳐라" → 빠르게 처리해야 하는데 인터뷰를 해야 하는가? - "최소 컨텍스트로 작동하라" + "관련 파일을 충분히 읽어라" → 어디까지 읽어야 충분한가?

이런 충돌은 사람이 읽으면 맥락상 구분이 되지만, LLM은 두 규칙을 동등한 가중치로 처리합니다. 결과적으로 세션마다 다른 쪽을 따르는 불안정한 행동이 나옵니다.

해결책: 우선순위를 명시하거나, 규칙의 적용 범위를 한정합니다.

## 분기 기준
- 단순 (1~2단계): orchestrator가 직접 수행
- 복합 (3단계+): 인터뷰 → 리서치 → 컴파일 파이프라인
- 기준 애매하면 복합으로 분류 (과대평가 > 과소평가)

이렇게 쓰면 "빠르게"와 "인터뷰"가 충돌하지 않습니다. 단순이면 빠르게, 복합이면 인터뷰. 애매하면 복합. 판단 기준이 명확합니다.

규칙 충돌을 발견하는 가장 빠른 방법은 에이전트에게 직접 물어보는 것입니다: "이 CLAUDE.md에서 모순되는 규칙 쌍이 있는지 찾아줘". 사람이 놓친 충돌을 정확히 짚어냅니다.

3. "금지 > 지시" 원칙

이것이 CLAUDE.md 작성에서 가장 중요한 원칙입니다.

모호한 지시:

적절한 길이로 작성하세요.

명확한 금지:

500토큰을 초과하지 마세요.

지시는 해석의 여지가 있습니다. "적절한"이 무엇인지는 상황마다 다릅니다. 금지는 이진(binary)입니다. 넘었는가, 안 넘었는가.

실전에서 효과적이었던 금지 규칙의 패턴:

모호한 지시 명확한 금지
출처를 잘 명시하세요 출처 없는 수치 생성 절대 금지
사용자 관점을 존중하세요 "내 생각" 섹션에 AI 관점 생성 금지
간결하게 쓰세요 도구 출력 50줄 이상이면 원본 저장 금지
검증을 철저히 하세요 "probably fine" 같은 표현 사용 금지

금지가 지시보다 강력한 이유는, LLM이 "하지 마라"를 "해라"보다 일관되게 따르기 때문입니다. 긍정형 지시는 정도(degree)의 문제가 생기지만, 금지는 위반 여부만 판단하면 됩니다.

4. 실제 구조 설계 — 필수 섹션과 생략 가능한 섹션

프로젝트 CLAUDE.md에 반드시 들어가야 하는 섹션:

1. 프로젝트 목적 (2~3줄)
2. 개발 환경 (테이블)
3. 에이전트 역할 분리 (orchestrator / executor / quality)
4. 워크플로 파이프라인 (요청 흐름도)
5. 게이트 조건 (단계별 진입/종료 기준)
6. 파일/명명 규칙
7. 금지 사항 (절대 규칙)
8. 메모리/컨텍스트 관리 전략
9. 프로젝트 구조 (디렉토리 트리)

각 섹션의 역할:

  • 에이전트 역할 분리: orchestrator는 대화와 판단, executor는 실행, quality는 검증 전담으로 분리하면 역할 경계가 명확해집니다. "누가 이걸 해야 하는가"를 에이전트가 스스로 판단할 수 있습니다.
  • 게이트 조건: 각 단계의 진입 조건(Entry)과 종료 조건(Exit)을 명시합니다. "brainstorming 단계는 사용자 설계 승인이 나와야 종료된다"처럼 구체적으로 씁니다. 조건이 없으면 에이전트가 단계를 건너뜁니다.
  • 메모리/컨텍스트 관리 전략: 세션 간 지식을 어떻게 보존하는지 정의합니다. 3레이어 메모리(프로젝트 지식 / 행동 규칙 / 세션 복원)를 명시하면 에이전트가 불필요한 파일 탐색을 줄입니다.

빠져도 되는 것: - 일반적인 코딩 원칙 (에이전트가 이미 알고 있음) - 너무 상세한 도구 사용법 (스킬 파일로 분리) - 변경이 잦은 정보 (메모리 레이어로 이동)

5. 스킬 시스템과 CLAUDE.md의 분리

CLAUDE.md에 절차(step 1, step 2, step 3...)를 넣으면 매 세션마다 불필요하게 로드됩니다. 절차적 작업 지침은 스킬 파일로 분리하는 것이 맞습니다.

.claude/
└── skills/
    ├── research/SKILL.md      # 리서치 절차
    ├── compile/SKILL.md       # 소스 파일 작성 절차
    └── verify/SKILL.md        # 팩트체크 절차

CLAUDE.md에는 트리거 키워드와 스킬 경로만 남깁니다:

## Skill Trigger System
| Keyword | Skill | Path |
|---|---|---|
| 리서치, 조사, research | research | .claude/skills/research/SKILL.md |
| 검증, 팩트체크 | verify | .claude/skills/verify/SKILL.md |

이렇게 분리하면 CLAUDE.md에는 "무엇을"과 "왜"만 남고, 스킬에는 "어떻게"만 남습니다. 컨텍스트 효율이 높아지고, 스킬을 독립적으로 수정하거나 재사용할 수 있습니다.

6. 안티패턴 — 이렇게 쓰면 안 된다

안티패턴 1: 만능 CLAUDE.md

모든 지식, 모든 규칙, 모든 예시를 한 파일에 넣는 경우. 파일이 500줄을 넘으면 에이전트가 뒷부분을 경시하기 시작합니다. CLAUDE.md는 컨텍스트의 상단에 로드되지만, 분량이 과하면 이후 대화에서 밀려납니다.

안티패턴 2: 감정적 지시

정말 중요하니까 꼭 지켜주세요!!!

느낌표와 강조는 효과가 없습니다. "절대 금지" 같은 구조적 표현이 더 효과적입니다.

안티패턴 3: 충돌하는 규칙을 방치

"토큰을 아껴라"와 "파일을 충분히 읽어라"를 동시에 적어놓고 기준을 안 주는 경우. 에이전트는 세션마다 다른 선택을 합니다.

안티패턴 4: 스킬과 규칙의 혼동

절차적 작업 지침을 CLAUDE.md에 인라인으로 넣는 경우. 스킬 파일로 분리하면 CLAUDE.md는 가볍게 유지되고, 스킬은 필요할 때만 로드됩니다.

설계 시 주의할 점

  • 글로벌 CLAUDE.md 없이 시작하면 중복이 쌓입니다. 프로젝트마다 사용자 성향과 통신 규약을 반복 작성하게 되고, 하나를 수정하면 나머지를 수동으로 업데이트해야 합니다. 글로벌 파일을 심링크로 공유하면 이 문제가 사라집니다.

  • 규칙 수를 줄이는 것이 추가하는 것보다 어렵습니다. "이 규칙 없어도 되나?"를 판단하려면 에이전트가 규칙 없이 어떻게 행동하는지 관찰해야 합니다. 일부 규칙은 삭제해도 행동이 바뀌지 않습니다 — 에이전트가 이미 기본적으로 따르는 것이기 때문입니다. 그런 규칙은 삭제해도 됩니다.

  • 규칙 충돌은 에이전트에게 물어보면 발견됩니다. "이 CLAUDE.md에서 모순되는 규칙 쌍이 있는지 찾아줘"라고 하면 사람이 놓친 충돌을 정확히 짚어냅니다.

  • 변하는 정보를 CLAUDE.md에 넣지 마세요. API 키, 버전 번호, 현재 상태 같은 정보는 메모리 레이어(tasks/sessions/, docs/)로 이동시켜야 합니다. CLAUDE.md는 불변(stable) 정보만 담아야 합니다.

마무리

CLAUDE.md는 에이전트의 정체성입니다. 매 세션 자동으로 로드되기 때문에, 여기에 적힌 것이 에이전트의 판단 기준이 됩니다.

잘 설계된 CLAUDE.md는 규칙이 적습니다. 글로벌과 프로젝트를 분리하고, 모호한 지시 대신 명확한 금지를 쓰고, 절차는 스킬로 빼고, 변하는 정보는 메모리로 이동시키면 CLAUDE.md에 남는 것은 정말 핵심만입니다.

"이 파일을 읽으면 에이전트가 자기 역할을 완전히 이해하는가?" — 이 질문에 "예"라고 답할 수 있으면 CLAUDE.md는 완성입니다.

댓글

댓글 쓰기

이 블로그의 인기 게시물

"LLM 핵심 학습 (1/6) — 기본: 토큰화·임베딩·어텐션·위치 인코딩"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/6 파인튜닝 → 트랜스포머 한 블록의 데이터 흐름을 문자열 → 토큰 → 임베딩 → 어텐션 → 출력 표현 까지 손으로 풀어 본다. 이번 편이 끝나면 "왜 \(\sqrt{d_k}\)로 나누는가", "RoPE는 무엇을 회전시키는가", "한국어가 영어보다 토큰이 많은 까닭은 무엇인가"가 한 줄로 설명될 수 있다. 0. 학습 목표 이 편을 마치면 다음을 직접 할 수 있다. BPE 토크나이저 가 어휘를 어떻게 학습하고 새 문자열을 어떻게 자르는지 종이 위에서 시뮬레이션한다. 임베딩 행렬 의 모양과 초기화, weight tying의 의미를 한 줄로 설명한다. Scaled Dot-Product Attention 의 식을 차원 단위로 추적하고 PyTorch 30줄로 재현한다. Multi-Head Attention 이 한 헤드와 비교해 무엇이 다른지, 헤드 수가 늘면 어디가 비싸지는지 답한다. Sinusoidal·RoPE·ALiBi 세 위치 인코딩의 식과 외삽 성질을 구분한다. 컨텍스트 확장이 왜 \(O(N^2)\)인지, "Lost in the Middle"이 왜 발생하는지 설명한다. 1. 핵심 요약 트랜스포머의 입력은 문자열 이 아니라 정수 ID 시퀀스 다. 토크나이저가 문자열 → ID로 자른다. 임베딩은 정수 ID를 \(d\)차원 벡터로 lookup하는 학습 가능한 테이블이다. Self-Attention은 \(\text{softmax}(QK^\top / \sqrt{d_k}) V\) 한 줄이 핵심이고, 멀티헤드는 같은 연산을 여러 부분 공간에서 병렬화한 것이다. 위치 정보는 임베딩에 직접 더하거나(Sinusoidal), Q·K에 회전을 가하거나(RoPE), 어텐션 스코어에 거리 패널티를 더해서(ALiBi) 주입한다. 컨텍스트 길이 \(N\)에 대해 표준 어텐션은 \(O(N^2)\) 비용을 갖고, 긴 컨텍스트에서는 중간 위...
Read more »

"LLM 핵심 학습 (2/6) — 파인튜닝: LoRA·QLoRA·증류·Adapter"

-
이미지
← 1/6 기본 📚 시리즈 목차 3/6 디코딩과 생성 → 사전학습된 LLM을 내 데이터 에 적응시키는 방법을 비용·메모리·일반화 관점에서 정리한다. Full FT의 한계 → Adapter → LoRA → QLoRA → Distillation 순으로 같은 그림을 점점 확대해 본다. 0. 학습 목표 Full fine-tuning의 메모리 병목을 옵티마이저 상태·그래디언트·가중치·활성화 의 4분할로 설명한다. Adapter(Houlsby 2019)와 LoRA(Hu 2021)의 식 차이를 한 줄로 적는다. LoRA의 \(A, B\) 행렬이 왜 저랭크 이고, rank \(r\) 선택이 무엇을 결정하는지 답한다. QLoRA(Dettmers 2023)의 NF4·double-quant·paged optimizer를 분리해서 설명한다. Catastrophic Forgetting을 분포 시프트 관점에서 정의하고 완화 기법을 두 개 이상 든다. Hinton 2015의 Knowledge Distillation 식을 손으로 유도한다. 1. 핵심 요약 Full FT는 메모리/디스크/시간 모두 비싸다. 7B 모델 full FT는 V100 8장 + A100 1장으로도 큰 부담이다. PEFT(파라미터 효율 파인튜닝) 일가족은 극히 일부 파라미터만 학습 해 같은 효과를 얻는다. LoRA: \(\Delta W = BA\) (rank \(r \ll \min(d_{\text{in}}, d_{\text{out}})\))로 가중치 업데이트를 저랭크 분해. QLoRA: 베이스 모델을 4-bit(NF4)로 양자화한 채 LoRA만 풀-정밀(BF16)으로 학습. Catastrophic Forgetting: 새 분포에 적응하느라 이전 능력이 무너지는 현상. PEFT 자체가 부분 완화책. Distillation: 큰 교사 모델의 soft target 을 학습 신호로 써서 작은 학생 모델 을 만든다. 2. 직관: 왜 사전학습만으로는 부족한가 사전학습은 일반...
Read more »

"ML 기초 학습 (1/9) — 머신러닝과 sklearn: 학습의 좌표계"

-
이미지
(시리즈 시작) 📚 시리즈 목차 2/9 이웃 알고리즘 → 이 시리즈는 신경망과 로컬 LLM으로 가기 전에 손에 익혀 둬야 할 머신러닝 기초 9편이다. 1편은 모든 ML 코드가 공유하는 공통 문법 을 잡는 데 쓴다. sklearn은 그 문법을 가장 일관되게 보여주는 도구다. 이번 편이 끝나면 어떤 모델을 만나도 fit → predict → score → 평가 흐름이 같다는 것이 손에 잡힌다. 0. 학습 목표 이 편을 마치면 다음을 할 수 있어야 한다. 지도학습·비지도학습·강화학습을 한 문장씩 구분해 설명한다. sklearn의 estimator 인터페이스 ( fit , predict , score , transform )를 코드 한 화면 안에서 쓸 수 있다. train/validation/test 분할을 왜 하는지, 어디서 데이터 누수가 생기는지 식과 그림으로 설명한다. 분류·회귀의 핵심 평가 지표(accuracy, precision, recall, F1, MSE, R²)를 정의에서 직접 계산할 수 있다. k-fold 교차검증 을 코드 한 줄로 돌리고, 결과의 평균과 표준편차를 함께 보고할 수 있다. Pipeline 으로 전처리와 모델을 묶어 데이터 누수를 구조적으로 막는 방법을 설명한다. 1. 핵심 요약 머신러닝은 데이터에서 함수 \(f: X \to Y\)를 찾는 작업 이다. 어떤 모델이든 이 본질은 같다. sklearn은 모든 모델을 같은 인터페이스( fit , predict , score )로 통일해, 모델을 바꿀 때 한 줄만 바꾸면 되게 한다. train/val/test 세 분할이 표준이다. 검증으로 하이퍼파라미터를 고르고, 테스트는 마지막에 한 번만 본다. 데이터 누수 (test 정보가 train에 새는 현상)는 ML 입문자가 가장 자주 만드는 실수이며, Pipeline + cross_val_score 조합으로 구조적으로 막을 수 있다. 평가 지표는 문제 유형 (분류/회귀) 과 클래스 불균형...
Read more »