Claude Code 에이전트 구조화: CLAUDE.md 패턴 & .claude/ 가이드

에이전트 디렉터리 구조

설정은 ~/Documents/ 아래에 각 에이전트별로 별도의 디렉터리를 생성하는 것을 포함합니다. 예시에는 다섯 개의 에이전트가 표시됩니다: 기획자(집행 기능, 라우팅, 책임), 콘텐츠(콘텐츠 파이프라인), 유튜브(YouTube 제작), 생활(개인 영역), 그리고 제어 센터(대시보드, 데이터베이스, API).

각 에이전트는 다음 템플릿 구조를 따릅니다:

에이전트-이름/
├── CLAUDE.md # 정체성 + 미션 + 능력
├── .claude/
│   ├── rules/ # 자동 로드 컨텍스트 (항상 활성화)
│   └── skills/ # 주문형 워크플로우
├── inbox/ # 다른 에이전트로부터의 입력
├── outputs/ # 생성된 출력물
└── archive/ # 아카이브 없이는 삭제되지 않음

규칙 대 스킬 구분

.claude/rules/ 파일은 모든 세션 시작 시 자동으로 로드됩니다. Claude는 이를 컨텍스트 창의 일부로 읽습니다. 여기에는 에이전트가 항상 알아야 할 것들 — 범위, 비즈니스 컨텍스트, 행동 방식 — 을 넣습니다.

.claude/skills/ 파일은 주문형입니다. /skill-name으로 호출할 때만 로드됩니다. 여기에는 다단계 프로세스, 템플릿, 구조화된 루틴과 같은 특정 워크플로우를 넣습니다.

규칙 파일은 세션 시작 시 컨텍스트 창에 로드되어 유지됩니다. Claude Code는 프롬프트 캐싱을 사용하여 반복된 콘텐츠가 매 턴마다 전체 가격으로 청구되지 않도록 하지만, 큰 규칙 파일은 여전히 컨텍스트 압력을 증가시키고 응답 저하를 유발할 수 있습니다. 스킬의 경우, 기본적으로 이름과 설명만 컨텍스트에 상주하며; 전체 워크플로우는 호출 시나 Claude가 관련성이 있다고 판단할 때 주문형으로 로드됩니다.

경험적 법칙

규칙 (항상 활성화): 범위 경계, 비즈니스 컨텍스트, 라우팅 로직, 명명 규칙 — 모든 결정에 영향을 미치는 것들
스킬 (주문형): 단계별 워크플로우, 템플릿, 일괄 작업. 가끔 수행하는 것들 (참고: 스킬 설명은 항상 컨텍스트에 있어 Claude가 사용 가능한 것을 알 수 있음; 전체 내용만 주문형)

CLAUDE.md 내용

CLAUDE.md 파일은 120줄 이하로 유지되며 다음을 포함합니다:

정체성 (2-3줄): 이 에이전트가 누구이며 무엇을 하는지
현재 단계 (2-3줄): 지금 무엇을 작업 중인지
핵심 능력 (10-15줄): 어떤 스킬이 사용 가능한지, 무엇을 할 수 있는지
주요 위치 (10-15줄): 참조해야 할 파일 경로
구축된 내용 (10-20줄): 완료된 작업의 역사
다음 단계 (5-10줄): 즉각적인 우선순위
원칙 (5-10줄): 행동 가이드라인

규칙 구조 예시

기획 에이전트의 경우, .claude/rules/ 디렉터리는 로드 순서를 제어하는 번호가 매겨진 파일을 포함합니다:

.claude/rules/
├── 01-business-context.md # 수익 모델, 포지셔닝, 목표 고객
├── 02-agent-ecosystem.md # 모든 에이전트, 그들의 미션, 연결 방식
├── 03-roadmap.md # 현재 단계, 마일스톤, 종료 기준
├── 04-content-architecture.md # 콘텐츠 채널, 기둥, 워크플로우
├── 05-daily-routine.md # 일정, 아이디어 필터링, 방해 방지 규칙
├── 07-godin-strategy.md # 마케팅 원칙, 마일스톤 추적
├── 08-control-center.md # CLI 도구 참조, DB 스키마
├── 98-end-of-session.md # 의식: 로드맵 업데이트, 지식 포착
└── 99-content-capture.md # 모든 세션에서 콘텐츠 신호 자동 추출