Claude 블로그 되짚어보기 #66 — CLAUDE.md, AI 시대 코드베이스의 헌법 (2025)

panicdev·2026년 4월 27일
AIAnthropicClaudeClaudeMdCodebaseContextLLMclaudecode블로그리뷰

원문 정보

글의 요지

CLAUDE.md — Claude Code의 영구 컨텍스트 파일. 매 대화마다 자동 포함되는 "프로젝트 설명서". 아키텍처, 컨벤션, 명령어, 표준을 매번 재설명할 필요 없음.

CLAUDE.md의 본질

"CLAUDE.md files turn Claude Code from a general-purpose assistant into a tool configured specifically for your codebase."

번역: CLAUDE.md는 Claude Code를 "범용 어시스턴트" 에서 "이 코드베이스 전용 도구" 로 변환.

본문 예시

# Project Context
When working with this codebase, prioritize 
readability over cleverness. Ask clarifying 
questions before making architectural changes.

## About This Project
FastAPI REST API for user authentication and profiles.
Uses SQLAlchemy for database operations and Pydantic 
for validation.

## Key Directories
- `app/models/` - database models
- `app/api/` - route handlers
- `app/core/` - configuration and utilities

## Standards
- Type hints required on all functions
- pytest for testing (fixtures in `tests/conftest.py`)
- PEP 8 with 100 character lines

## Common Commands
\`\`\`bash
uvicorn app.main:app --reload  # dev server
pytest tests/ -v               # run tests
\`\`\`

## Notes
All routes use `/api/v1` prefix. JWT tokens expire 
after 24 hours.

핵심 사용 패턴

1) /init 명령으로 시작

  • Claude Code가 자동으로 프로젝트 분석
  • 초기 CLAUDE.md 생성
  • 사용자가 수정·확장

2) # 키로 점진적 추가

  • 반복하는 지시 발견 시
  • 즉시 CLAUDE.md에 추가
  • 시간이 지나며 정착

3) 다루는 영역:

  • 프로젝트 컨텍스트: 무엇, 왜
  • 주요 디렉토리: 코드 구조
  • 표준: 컨벤션, 스타일
  • 공통 명령: 빌드, 테스트, lint
  • 주의 사항: gotchas

작동 방식 — System Reminder

HumanLayer 블로그가 발견한 디테일 — Claude Code가 system reminder 로 CLAUDE.md 주입:

<system-reminder>
IMPORTANT: this context may or may not be relevant 
to your tasks. You should not respond to this 
context unless it is highly relevant to your task.
</system-reminder>

이 디자인의 의미:

  • Claude가 자율 판단 — 작업과 관련 있을 때만 사용
  • 모든 지시 강제 X
  • 관련 없으면 무시

함의:

  • CLAUDE.md에 너무 많은 지시 = 자주 무시됨
  • Universally applicable 한 내용만
  • "Less is more"

베스트 프랙티스

1) 200줄 이하 권장 (TurboDocx, Anthropic 공식):

  • "이 줄 빼면 Claude가 실수할까?" → No → 삭제
  • 매 줄이 context window 소비

2) Linter 작업은 Claude에게 맡기지 마라 (HumanLayer):

  • 결정론적 도구 (Prettier, ESLint) 사용
  • LLM은 "훨씬 비싸고 느림"
  • Code style은 hook + linter

3) Progressive Disclosure:

  • CLAUDE.md = 모든 정보 X
  • "여기서 더 찾아봐" 가이드
  • 관련 reference 파일에 링크

4) WHY, WHAT, HOW (HumanLayer):

  • WHAT: 기술 스택, 프로젝트 구조
  • WHY: 프로젝트 목적
  • HOW: 작업 방식 (bun vs node, 테스트 방법)

5) Shrivu Shankar의 13KB 한도:

  • "각 도구는 30%+ 엔지니어가 쓰는 것만"
  • "Ad space" 처럼 토큰 예산 할당
  • 도구 문서 짧게 못 쓰면 "준비 안 된 거"

2026년에 다시 읽으며 — 내가 본 것

1. "Less is More"의 운영 통찰

이 글의 가장 중요한 메시지 — CLAUDE.md는 짧을수록 좋다.

직관에 반함:

  • "많이 알려줄수록 좋겠지?"
  • "모든 컨벤션 명시"
  • "각 디렉토리 설명"

실제:

  • 너무 많으면 Claude가 무시
  • Context window 소비
  • 신호 흐려짐

이게 AI 컨텍스트 디자인의 일반 원칙 이다 — 양 X, 신호 밀도.

비교 — 인간 온보딩:

  • 첫날에 50페이지 매뉴얼 → 안 읽음
  • 1페이지 핵심 + "여기서 더 찾아" → 효과적

CLAUDE.md도 같다. 첫날의 1페이지 같은 자세.

2. "13KB 한도, Ad Space 비유"의 운영 디테일

Shrivu Shankar의 인용 가장 흥미롭다 — 회사 monorepo CLAUDE.md를 광고 공간처럼 관리:

"We've even started allocating effectively a max token count for each internal tool's documentation, almost like selling 'ad space' to teams."

"If you can't explain your tool concisely, it's not ready for the CLAUDE.md."

이게 enterprise 차원의 거버넌스다:

  • CLAUDE.md = 한정 자원
  • 각 도구는 "광고 공간" 경쟁
  • 30%+ 엔지니어가 쓰는 도구만
  • 간결하게 못 쓰면 = 도구가 미성숙

이 사고방식이 AI 컨텍스트를 자원으로 관리하는 진지함의 시그널이다. 단순 "문서" 가 아니라 "제품".

3. "Self-Updating CLAUDE.md"의 메타 패턴

TurboDocx 인용:

"When Claude gets something wrong... tell Claude to add the correction to CLAUDE.md itself."

이게 self-improving system 패턴이다:

1. Claude가 실수
2. 사용자가 수정 + "CLAUDE.md에 추가해"
3. Claude가 자기가 사용할 파일 업데이트
4. 다음에 같은 실수 안 함

이 피드백 루프의 의미:

  • CLAUDE.md = 정적 문서 X
  • Living document — 사용하면서 진화
  • AI가 자기 컨텍스트 자기가 쓰기

같은 패턴 — Brex의 사례 (#53 글):

  • "디렉토리별 CLAUDE.md"
  • 자동 문서화 CI/CD
  • Claude가 변경 시 문서 업데이트

이 자기 갱신 시스템이 AI 도구의 진정한 학습 메커니즘이다.

4. "Constitution"이라는 비유

Shrivu Shankar의 표현:

"This file is the agent's 'constitution,' its primary source of truth for how your specific repository works."

이 비유가 정확하다:

ConstitutionCLAUDE.md
국가의 핵심 법프로젝트의 핵심 규칙
다른 법의 해석 기준다른 코드의 해석 기준
변경 어려움신중하게 변경
모든 것의 토대모든 결정의 토대

이 비유의 함의 — CLAUDE.md는 일반 문서가 아니다. 진지한 거버넌스 자원.

이 인식 차이:

  • "또 하나의 README" (가벼움)
  • "프로젝트 헌법" (진지함)

후자가 "AI가 진짜 회사 인프라" 가 됐을 때의 자세다.

5. "Linter 일을 Claude에 시키지 마라"의 깊은 통찰

HumanLayer의 가르침:

"Never send an LLM to do a linter's job. LLMs are comparably expensive and incredibly slow compared to traditional linters and formatters."

이 통찰이 깊다:

LLM의 자리:

  • 의도 이해
  • 디자인 결정
  • 복잡 추론
  • 자연어 생성

결정론적 도구의 자리:

  • 스타일 강제 (Prettier)
  • 린팅 (ESLint, Pylint)
  • 포맷팅
  • 타입 체크

섞으면 안 되는 이유:

  • LLM은 비결정적 → 같은 입력, 다른 출력
  • LLM은 비쌈 → 토큰당 비용
  • LLM은 느림 → 초당 토큰 한도

이게 AI 시대 도구 디자인의 원칙이다 — "각 도구를 자기 자리에". AI에게 모든 것 시키면 비효율 + 비결정성.

좋은 시스템:

  • AI = 결정·추론
  • 결정론적 도구 = 검증·강제
  • Hooks로 통합

6. "13KB → 25KB 성장 예상"의 시그널

Shrivu가 언급:

"Our monorepo's CLAUDE.md is strictly maintained and currently sits at 13KB (I could easily see it growing to 25KB)."

이 수치가 흥미롭다:

  • 작은 프로젝트: 1-2KB
  • 중간 프로젝트: 5-10KB
  • 거대 monorepo: 13-25KB

25KB ≈ 6,000-7,000 토큰. 매 세션에 항상 로드.

이 비용이 의미하는 것:

  • Context 200K = 25KB CLAUDE.md + 175K 작업 공간
  • 컨텍스트의 약 12%가 CLAUDE.md

이게 "의식적 투자" 가 됐다. 12%를 CLAUDE.md에 투자하면, 나머지 88%가 더 효율적.

비유:

  • 도구함 정리 시간 = 13KB
  • 그 후 작업 효율 = 88%

7. "/init + #" 간단한 도입 워크플로

본문이 보여주는 도입 패턴이 우아하다:

1단계: /init

  • Claude Code가 프로젝트 자동 분석
  • 기본 CLAUDE.md 생성
  • 사용자가 검토

2단계: 사용

  • 평소처럼 Claude Code 사용
  • 반복 지시 발견 시 → # 키
  • 자동으로 CLAUDE.md 추가

3단계: 자연 진화

  • 1-2주 사용하면 자기 팀 패턴 반영
  • 매뉴얼 수정 거의 불필요

이 "organic 진화" 패턴이 개발자 친화성의 핵심이다. "먼저 완벽한 문서 작성" 강요 X. 사용하면서 진화.

이게 "developer experience" 의 좋은 예다. 마찰 0으로 시작, 점진적 가치 추가.

마무리

이 글은 "설정 파일 가이드" 같지만, 실제로는 AI 시대 코드 거버넌스의 새 원칙이다.

  • CLAUDE.md = Constitution: 진지한 거버넌스 자원
  • Less is More: 200줄 이하 권장
  • System Reminder 동작: 관련 없으면 무시
  • Self-Updating: Claude가 자기 컨텍스트 갱신
  • Linter는 Linter에게: 도구마다 자리
  • 13KB Ad Space: 토큰 예산 의식적 관리
  • /init + # 워크플로: organic 진화

2025년 11월 시점은 "CLAUDE.md를 어떻게 쓸지" 의 베스트 프랙티스가 정착한 시기다. 1년간의 community 실험이 표준화. Anthropic이 그 표준을 공식 글로 정리.

흥미로운 건 "CLAUDE.md를 어떻게 쓰지 말아야 할지" 가 더 중요한 메시지라는 점이다:

  • 너무 많이 쓰지 마라
  • Code style은 linter에게
  • 모든 것을 강제하지 마라
  • 정적 문서로 다루지 마라

이 "안 할 것" 원칙이 "AI 시대 거버넌스 성숙도" 의 시그널이다. 초기엔 "AI에게 모든 것 알려줘야" 라는 강박. 성숙기엔 "필요한 것만, 자율성을 신뢰". CLAUDE.md 관리가 그 변화를 압축한다.

profile
panicdev
이전 포스트

Claude 블로그 되짚어보기 #65 — Thinking Partner, "Keep Thinking" 캠페인의 시작 (2025)

다음 포스트

Claude 블로그 되짚어보기 #67 — Agentic Coding 전환의 이익, 4-8개월을 2주로 (2025)

0개의 댓글