[ Claude Code #3 ] CLAUDE.md 최적화 전략 – AI 에이전트를 위한 ‘프로젝트의 뇌’ 설계법

by

Claude Code를 사용하면서 “지시사항을 자꾸 무시한다”거나 “학습시킨 규칙을 어긴다”고 느낀 적이 있으신가요?

이는 AI 모델의 한계라기보다, 프로젝트의 가이드라인인 CLAUDE.md가 ‘명령어 예산(Instruction Budget)’을 초과하여 설계되었기 때문일 확률이 높습니다.

이번 포스팅에서는 CLAUDE.md를 단순한 설정 파일이 아니라, AI 에이전트가 프로젝트를 이해하고 판단하는 기준이 되는 ‘프로젝트의 뇌(Brain)’이자 ‘헌법(Constitution)’으로 구축하는 전략을 다룹니다.

특히 토큰 낭비를 최소화하면서도 복잡한 모노레포(Monorepo) 환경에서 에이전트를 완벽하게 통제할 수 있는 계층적 관리 전략과 실무 템플릿을 공개합니다.

CLAUDE.md

1. 명령어 예산(Instruction Budget)과 작동 원리

CLAUDE.md는 매 세션 시작 시 Claude Code의 컨텍스트 윈도우 최상단에 로드됩니다. 여기서 가장 중요한 개념은 ‘명령어 예산(Instruction Budget)’입니다.

최신 LLM은 한 번에 약 150~200개의 구체적인 지시사항만을 안정적으로 준수할 수 있습니다.

  • 시스템 소모: Claude Code의 기본 시스템 프롬프트가 이미 약 50개의 예산을 점유합니다.
  • 가용 예산: 결과적으로 우리가 CLAUDE.md에 쓸 수 있는 유효 예산은 100~150개 내외입니다.

파일이 너무 길어지면 Claude Code는 컨텍스트의 압박을 느껴 중요한 지침을 무시하거나(“Lost in the Middle” 현상), 매 요청마다 토큰을 낭비하여 비용을 급증시킵니다.

2. 효율적인 작성 규칙: 무엇을 적고, 무엇을 뺄 것인가?

CLAUDE.md는 에이전트가 코드를 통해 스스로 추론할 수 없는 핵심 맥락만 최소한으로 제공해야 합니다.

✅ 작성해야 할 것 (Do)

  • 독특한 아키텍처: 코드만 보고 알 수 없는 우리 팀만의 패턴이나 의사결정 방식.
  • 명확한 명령어: npm 대신 반드시 pnpm을 사용해야 하는 등의 패키지 매니저 강제.
  • 실수 방지(Anti-pattern): 에이전트가 과거에 자주 했던 실수나 프로젝트 내 금기 사항.
  • 검증 가이드: 에이전트가 “완료”라고 판단하기 위해 반드시 통과해야 할 하네스 실행 결과.

❌ 작성하지 말아야 할 것 (Don’t)

  • 모호한 원칙: “클린 코드를 작성하라”와 같이 누구나 아는 일반적인 이야기는 토큰 낭비입니다.
  • 린터 대용: 린터나 포매터가 자동으로 잡아낼 수 있는 규칙은 LLM에게 시키지 마세요.
  • 장황한 API 문서: 전체 문서는 별도 파일로 분리하고 경로(@docs/…)만 알려주세요.

3. 계층형 관리 전략: Root와 Submodule의 분리

모노레포나 멀티 모듈 프로젝트에서는 하나의 거대한 CLAUDE.md를 만드는 대신, 계층적 상속 구조를 활용해야 합니다. Claude Code는 파일을 수정할 때 해당 파일의 상위 디렉토리에 있는 모든 CLAUDE.md를 아래에서 위로(Bottom-up) 탐색하여 로드합니다.

[Root] 전역 헌법: 글로벌 거버넌스

프로젝트 루트의 CLAUDE.md는 프로젝트 전체의 ‘정체성’과 ‘공통 규칙’을 정의합니다.

  • 역할: 에이전트 페르소나 정의, 전역 보안 수칙, 커밋 컨벤션.

[Submodule] 현장 수칙: 모듈별 로컬 가이드

각 서비스 폴더(예: apps/frontend/, services/backend/)의 CLAUDE.md는 해당 모듈에만 적용되는 ‘기술적 디테일’을 담습니다. 에이전트가 해당 폴더에 진입할 때만 정보를 로드하므로 토큰을 아끼면서 정확도를 높입니다.

claude.md-for-root-submodule

4. 하네스 엔지니어링(Harness Engineering)의 적용

하네스 엔지니어링은 단순히 “잘해봐”라고 말하는 것이 아니라, AI가 잘할 수밖에 없는 환경(Harness)을 설계하는 것입니다. AI의 ‘확률적 답변’을 개발 프로세스의 ‘결정론적 결과’로 변환하는 핵심 전략입니다.

4.1 확률적 지시 vs 결정론적 강제 (Hooks 활용)

CLAUDE.md에 “린트 에러를 내지 마세요”라고 적는 것은 확률적 지시입니다. 반면, 하네스 엔지니어링은 이를 시스템 레벨에서 강제합니다.

  • Pre-computation Harness: Claude가 코드를 제출하기 전 반드시 실행해야 할 쉘 스크립트를 CLAUDE.md에 명시하세요.예시: “코드를 수정했다면 반드시 npm run lint와 npm run test를 실행하고, 실패 시 ‘Task incomplete’로 간주한다.”
  • Git Hooks 연동: 프로젝트의 .git/hooks와 CLAUDE.md의 지침을 동기화하여, Claude Code가 로컬에서 커밋을 시도할 때 하네스가 자동으로 작동하게 설계합니다.

4.2 경계 설정(Boundaries)과 샌드박스

에이전트가 접근해서는 안 될 영역을 명확히 하는 ‘가드레일’을 세워야 합니다.

  • File-level Guard: .claudeignore 파일을 활용해 민감한 설정값(.env)이나 대용량 바이너리 데이터에 Claude가 접근하여 토큰을 낭비하거나 보안 사고를 치지 않도록 물리적으로 차단합니다.
  • Read-only Zones: CLAUDE.md에 “Core 아키텍처 폴더(/src/core)는 수정하지 말고 참조만 할 것”과 같은 명시적 경계를 설정하여 에이전트의 활동 범위를 제한합니다.

5. 점진적 공개(Progressive Disclosure) 기법

모든 정보를 한꺼번에 Claude에게 먹이는 것은 ‘정보 과부하’와 ‘비용 효율성 저하’를 초래합니다. 필요한 정보만 제때 로드되도록 계층화하는 전략입니다.

5.1 계층적 로드 시스템 (Scoped Context)

Claude Code는 파일을 다룰 때 해당 파일의 상위 디렉토리를 탐색하며 모든 CLAUDE.md를 읽습니다. 이를 활용해 컨텍스트를 분산합니다.

  • Root Level: 전역 코딩 표준, 커밋 컨벤션, 프로젝트 개요 (모든 작업 시 공통 적용).
  • Folder Level: 특정 라이브러리(예: react-query) 사용법, 특정 도메인의 비즈니스 로직 제약 사항 (해당 폴더 작업 시에만 로드).
  • 장점: Claude가 현재 작업과 상관없는 백엔드 설정을 프론트엔드 작업 중에 읽지 않게 되어 ‘Lost in the Middle’ 현상을 방지합니다.

5.2 외부 참조 및 @imports 전략

CLAUDE.md 파일 자체를 가볍게 유지하기 위해 ‘포인터’ 개념을 도입합니다.

  • Documentation Linking: 장황한 API 스펙은 CLAUDE.md에 직접 쓰는 대신, @docs/api-spec.md와 같은 경로만 적어둡니다. Claude Code는 필요할 때 해당 경로를 직접 읽어올 수 있습니다.
  • MCP(Model Context Protocol) 서버 활용: 정적인 텍스트로 설명하기 힘든 복잡한 DB 스키마나 실시간 인프라 상태는 MCP 서버를 통해 ‘On-demand’로 호출하게 만듭니다. 이는 지시사항 예산을 단 하나도 쓰지 않으면서 방대한 정보를 제공하는 가장 세련된 방법입니다.

5.3 Agent/Skill 위임 (Modular Instructions)

모든 규칙을 준수하라고 강요하는 대신, 특정 상황에서만 활성화되는 ‘Skill’을 정의합니다.

  • 커스텀 명령어 정의: “새로운 API 엔드포인트를 만들 때는 반드시 sh scripts/generate-api.sh를 먼저 실행할 것”과 같이 복잡한 절차를 스크립트화하고, 이를 CLAUDE.md에서 ‘Skill’로 호출하도록 유도합니다.
  • 역할 분담: CLAUDE.md 상단에 “너는 현재 UI 최적화 전문가로 행동하며, 아키텍처 변경이 필요하면 Architect-Agent에게 질의하라”는 식의 위임 규칙을 설정하여 에이전트의 사고 범위를 좁히고 정확도를 높입니다.

💡 실전 CLAUDE.md 계층별 템플릿 예시

1) Root CLAUDE.md (전역 헌법)

# 프로젝트: MegaSaaS - 전역 거버넌스

## 🤖 에이전트 페르소나 (Agent Personas)
- **Arch-Agent**: 시스템 아키텍처 및 모듈 간 의존성 관리.
- **Impl-Agent**: "Harness-First" 원칙에 따라 테스트가 있을 때만 코드 작성.

## 🚨 전역 공통 수칙
- 모든 커밋은 Conventional Commits 표준을 따를 것.
- 새로운 모듈 추가 시 반드시 `docs/architecture/`를 업데이트할 것.
- 민감한 정보(.env)는 절대 수정하거나 읽지 말 것.

## 🏗 프로젝트 구조 인덱스
- `web-ui`: Vue.js 기반 클라이언트 앱
- `core`: Go 기반 API 서버
- `shared`: 공통 타입 및 유틸리티

2) Frontend Submodule CLAUDE.md (현장 수칙)

# 모듈: Frontend App (`web-ui`)

## 🛠 기술 스택 및 명령어
- **Stack:** Vue 3 (Composition API), Vite, Tailwind CSS, Pinia
- **Command:** `pnpm dev`, `pnpm build`, `pnpm test:unit`
- **Lint:** 수정 후 반드시 `pnpm lint --fix`를 실행하여 스타일을 맞출 것.

## 🧪 UI 검증 규격
- 모든 컴포넌트는 `components/__tests__`에 단위 테스트를 포함해야 함.
- 새 컴포넌트 추가 시 반드시 Storybook 스토리를 생성할 것 (`/create-story` 스킬 활용).

## 🚨 프론트엔드 금기 사항
- 인라인 스타일링 금지. 반드시 Tailwind 클래스를 사용할 것.
- API 호출 시 전역 `axios` 인스턴스 대신 `src/api`의 래퍼 함수를 사용할 것.

3) Backend Submodule CLAUDE.md (현장 수칙)

# 모듈: Backend API Server (`core`)

## 🛠 기술 스택 및 명령어
- **Stack:** Go 1.22, Gin, Gorm (PostgreSQL)
- **Command:** `go test ./...`, `go build -o server`
- **Migration:** DB 스키마 변경 시 반드시 `/generate-migration` 스킬을 사용할 것.

## 🧪 로컬 검증 규격 (Validation)
- 모든 API 핸들러는 반드시 `_test.go` 파일을 가져야 함.
- 린트 체크: `golangci-lint run`

## 📖 모듈 전용 가이드
- 인증 로직 수정 시: `@docs/backend/AUTH_FLOW.md` 참고

에디터의 요약

훌륭한 CLAUDE.md 관리는 ‘무엇을 적을까’가 아니라 ‘어디에 적을까’의 문제입니다.

  1. Root에는 팀의 문화를 적고,
  2. Submodule에는 도구의 사용법과 로컬 기술 스택을 적으세요.
  3. 그리고 나머지는 Skill과 Agent로 위임하여 ‘명령어 예산’을 철저히 지키세요.

이렇게 설계된 계층 구조는 Claude Code가 수십 개의 모듈을 가진 대규모 프로젝트에서도 단 한 번의 오판 없이 시니어 개발자처럼 움직이게 만드는 마법의 지도가 됩니다.

🔗 참고 링크

더 깊이 있는 학습과 실전 활용을 위해 아래 리소스들을 참고해 보세요.

Leave a Comment

© 2026 Marketer • Built with GeneratePress
Privacy Policy Terms Contact