CLAUDE.md 자동화 기반 만들기

Thin Orchestrator AI 자동화 기반 설계와 권한 제어 실전

CLAUDE.md는 "AI에게 보내는 영구 지시서"

CLAUDE.md는 Claude Code가 세션 시작 시 자동으로 읽어 들이는 마크다운 파일이다. 프로젝트 루트에 두기만 하면, 매번 같은 프롬프트를 손으로 입력하지 않아도 AI가 "자신이 누구이고, 무엇을 해야 하는지"를 이해한 상태로 시작한다.

수작업하던 시절, 저자는 매일 아침 이런 프롬프트를 입력하고 있었다.

당신은 AI-CEO 프레임워크의 오케스트레이터입니다.
9개의 부서를 관리합니다.
부서는 개발, 마케팅, 영업, 경리, CS, 법무, 세무, 컨설팅, HR입니다.
각 부서의 상태는 .company/departments/ 에 있습니다.
승인 대기 항목은 .company/approval-queue.md 에 있습니다.
（...이하 50줄 정도 계속됨）

이것을 매일 입력하는 것은 낭비다. CLAUDE.md에 작성해두면, 한 번 쓰는 것만으로 영구적으로 유효해진다.

프로젝트 루트/
├── CLAUDE.md ← 이것. 세션 시작 시 자동 읽기
├── .claude/
│ ├── agents/ ← 에이전트 정의 (후술)
│ ├── skills/ ← 스킬 정의 (제5장)
│ └── settings.local.json ← Hooks·MCP 설정 (제4장·제6장)
└── .company/ ← 회사 데이터
├── STATE.md
├── departments/
└── ...

CLAUDE.md는 3곳에 배치할 수 있다. 읽기 순서와 용도를 파악해두자.

자동화 맥락에서는 프로젝트 루트의 CLAUDE.md가 가장 중요하다. 여기에 오케스트레이터 정의를 작성한다.

Thin Orchestrator 패턴

문제점: CLAUDE.md가 비대해진다

CLAUDE.md에 모든 지시를 작성하려 하면, 금세 수백 줄, 수천 줄로 불어난다. 9개 부서분의 에이전트 정의, 모든 명령어의 실행 흐름, 권한 설정, 브랜드 가이드라인... 전부 넣으면 Claude Code의 컨텍스트 윈도우에 부담이 된다.

저자도 처음에는 모든 것을 CLAUDE.md에 채워 넣었다. 결과적으로 파일이 1000줄을 넘어섰고, Claude Code의 응답 속도가 떨어지더니 지시 일부가 무시되기 시작했다.

해결책: '얇은 사령탑' 패턴

Thin Orchestrator 패턴은 CLAUDE.md를 200줄 이내로 유지하고, 세부 내용은 외부 파일로 분리하는 설계다.

CLAUDE.md (200줄 이내)
├── 자신이 누구인가 (5줄)
├── 참조 파일 목록 (20줄)
├── 명령어 목록 (30줄)
├── 명령어 실행 규칙 (50줄)
├── 권한 제어 규칙 (20줄)
├── 오류 발생 시 동작 (10줄)
└── 서브 에이전트 위임 방법 (15줄)

세부 내용은 모두 외부 파일에
├── .claude/agents/*.md ← 각 부서 에이전트 정의
├── .company/steering/*.md ← 브랜드·기술·권한 상세
└── .company/STATE.md ← 현재 경영 상태

핵심은, CLAUDE.md에는 파일의 내용을 쓰지 않고, 파일 경로만 쓴다는 것이다.

구현 예시: CLAUDE.md 전체 구조

아래는 저자가 실제로 사용하는 CLAUDE.md의 구조다 (실제 코드에서 발췌·간략화).

# AI-CEO Framework — CEO-Suite Orchestrator

> 당신은 AI-CEO Framework의 'CEO-Suite Orchestrator'입니다.
> CEO의 경영 판단을 지원하고, 9개 부서의 AI 에이전트를 총괄합니다.

## 당신의 역할

당신은 CEO와 직접 대화하는 유일한 인터페이스입니다.

1. **CEO 명령어 접수 및 실행** — 명령어를 해석하고, 적절한 부서에 위임
2. **부서 간 조정** — 의존 관계 해소
3. **승인 관리** — draft 산출물을 CEO에게 보고

## Thin Orchestrator 원칙

- 컨텍스트 사용률을 10~15%로 유지한다
- 파일 내용을 자신의 컨텍스트에 읽어 들이지 않고, 파일 경로만 전달한다
- 복잡한 태스크는 반드시 .claude/agents/ 의 서브 에이전트에 위임한다
- 스스로 실작업 (코딩, 문서 작성 등)을 수행하지 않는다

## 회사 정보 참조처

- 비전·미션: `.company/VISION.md`
- 현재 경영 상태: `.company/STATE.md`
- 권한·임계값 설정: `.company/steering/permissions.md`
- 승인 대기 큐: `.company/approval-queue.md`
- 부서별 상태: `.company/departments/`

여기서 중요한 것은 "스스로 실작업을 수행하지 않는다"는 원칙이다. 오케스트레이터는 지시를 내리는 것뿐. 실제 작업은 서브 에이전트에 위임한다.

이로써 CLAUDE.md의 컨텍스트 소비를 최소화하면서, 필요할 때 필요한 파일만 읽어 들이는 효율적인 운용이 가능해진다.

권한 레벨 제어 구현

왜 권한 제어가 필요한가

AI에게 모든 것을 맡기면 돌이킬 수 없는 일이 생긴다. 프로덕션 데이터베이스 삭제, 고객에게 잘못된 이메일 발송, 잘못된 청구서 발행...

저자의 환경에서는 3단계의 권한 레벨을 정의하고 있다.