CLAUDE.md로 AI 에이전트 조직 만드는 법

Orchestrator 패턴과 권한 설정 완전 해설

Claude Code란 무엇인가

이 책을 읽고 있는 분들 대부분은 GitHub Copilot이나 Cursor 같은 AI 코딩 도구를 사용해본 경험이 있을 것이다. Claude Code는 그것들과 근본적으로 다른 도구다.

GitHub Copilot이나 Cursor는 에디터에 통합된 "코드 자동완성 도구"의 연장선상에 있다. 코드를 작성하는 도중에 다음 줄을 제안해준다. 편리하지만, 어디까지나 에디터 안에서 완결된다.

Claude Code는 다르다. 터미널에서 동작하며, 파일 읽기·쓰기, 커맨드 실행, Git 조작 등 개발자가 터미널에서 하는 일의 거의 모든 것을 대신할 수 있다. 코드 자동완성이 아니라, 개발 프로세스 전체를 위임할 수 있는 도구다.

그리고 이 책의 맥락에서 가장 중요한 것은, CLAUDE.md라는 파일을 통해 AI의 행동·역할·제약을 세밀하게 정의할 수 있다는 점이다. 이를 통해 Claude Code는 "똑똑한 코드 자동완성"에서 "설정 가능한 AI 에이전트"로 변한다.

플랜 선택 — 왜 Max 플랜인가

Claude Code를 사용하려면 Anthropic의 플랜에 가입해야 한다. 2026년 3월 시점의 선택지는 다음과 같다.

필자는 Max 5x（$100/월）에서 시작해서, 이용량에 따라 Max 20x（$200/월）로 전환하고 있다.

AI 에이전트 경영을 하려면 Max 플랜은 필수다. 이유는 세 가지다.

장시간 세션: 에이전트에게 스프린트 전체를 위임하면 1세션이 수십 분에 이르는 경우가 있다. Pro 플랜에서는 이용 제한에 걸린다

큰 컨텍스트: 6개 프로덕트의 상태 관리 파일, 에이전트 정의 파일, 코드베이스를 동시에 다루려면 충분한 컨텍스트 윈도우가 필요하다

빈번한 이용: 하루에 복수의 부문 에이전트를 가동하기 때문에 사용량이 많다

월 $100~200은 저렴하지 않다. 하지만 1장에서 언급했듯, "6개 부문의 부하를 월 15만~30만 원에 고용할 수 있다"고 생각하면 투자 대비 효과는 매우 높다.

셋업 순서

1. Claude Code 설치

# npm으로 글로벌 설치
npm install -g @anthropic-ai/claude-code

# 설치 확인
claude --version

2. 인증

# 초회 실행 시 인증 플로우가 시작된다
claude

# 브라우저가 열리고 Anthropic 계정으로 로그인
# Max 플랜에 가입된 계정으로 로그인한다

3. 프로젝트 디렉토리 초기화

# 프로젝트의 루트 디렉토리로 이동
cd ~/workspace/your-project

# Claude Code 실행
claude

# 초회 실행 시, CLAUDE.md가 존재하지 않으면
# 기본 설정으로 동작한다

여기까지는 일반적인 Claude Code 셋업이다. 여기서부터 AI 에이전트 경영을 위한 설정에 들어간다.

CLAUDE.md 작성법 — Orchestrator로서 정의하기

CLAUDE.md는 Claude Code가 프로젝트에서 실행될 때마다 가장 먼저 읽어들이는 설정 파일이다. 프로젝트 루트에 배치한다.

일반적인 사용법에서는 코딩 규약이나 프로젝트 고유의 지시를 쓰는 정도다. 하지만 AI 에이전트 경영에서는, CLAUDE.md에 Orchestrator(총괄자)로서의 역할을 정의한다. 이것이 단순한 도구 활용과 조직 설계의 갈림길이 된다.

CLAUDE.md의 기본 구조

필자가 실제로 사용하고 있는 CLAUDE.md의 구조를, 핵심을 추려 해설한다.

# AI-CEO Framework -- CEO-Suite Orchestrator

> 당신은 AI-CEO Framework의 「CEO-Suite Orchestrator」입니다.
> CEO의 경영 판단을 지원하고, 6개 부문의 AI 에이전트를 통괄합니다.

## 당신의 역할

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

1. CEO 커맨드 접수와 실행
2. 부문 간 조정
3. 승인 관리
4. 프로덕트 횡단 관리

## Thin Orchestrator의 원칙
- 컨텍스트 사용률을 10~15%로 유지한다
- 파일 내용을 자신의 컨텍스트에 읽어들이지 않고, 파일 경로만 전달한다
- 복잡한 태스크는 반드시 서브 에이전트에 위임한다
- 자신이 실작업을 수행하지 않는다

도입부 선언이 중요하다. "당신은 CEO-Suite Orchestrator입니다"라고 명시함으로써, Claude Code는 "자신은 도구가 아니라 조직의 총괄자로서 행동해야 한다"고 이해한다. 이 한 줄이 일반적인 AI 코딩 보조와 AI 에이전트 조직의 분기점이다.

회사 정보 참조처를 정의한다

## 회사 정보 참조처

- 비전·미션: `.company/VISION.md`
- 현재 경영 상태: `.company/STATE.md`
- 분기 로드맵: `.company/ROADMAP.md`
- CEO 의사결정 로그: `.company/decisions/` (해당 월 파일)
- 권한·임계값 설정: `.company/steering/permissions.md`
- 승인 대기 큐: `.company/approval-queue.md`
- 브랜드·기술 규약: `.company/steering/`
- 프로덕트별 상태: `.company/products/`
- 부문별 상태: `.company/departments/`

여기서 "파일 경로"만 열거하는 것이 핵심이다. 파일 내용은 여기에 쓰지 않는다. Thin Orchestrator 원칙에 따라, 필요할 때 에이전트가 스스로 읽으러 간다. 노션(Notion) 링크나 구글 드라이브(Google Drive) URL 대신 로컬 파일 경로를 사용하는 이유도 여기에 있다 — 에이전트가 직접 파일을 읽고 쓸 수 있어야 하기 때문이다.

커맨드 체계를 정의한다

## CEO 커맨드 일람

### 일상 운용
- `/ai-ceo:morning` -- 아침 다이제스트 생성
- `/ai-ceo:status` -- 현재 전체 상태

### 승인 조작
- `/ai-ceo:approve <id>` -- 승인
- `/ai-ceo:reject <id> "이유"` -- 반려

### 부문 커맨드
- `/ai-ceo:dev:sprint` -- 스프린트 계획·실행
- `/ai-ceo:dev:hotfix "설명"` -- 긴급 버그 수정
- `/ai-ceo:mkt:campaign "개요"` -- 마케팅 캠페인
- `/ai-ceo:mkt:content-plan` -- 월간 콘텐츠 캘린더
...

커맨드를 정의해두면 CEO는 장황하게 자연어로 지시를 쓸 필요가 없어진다.

/ai-ceo:dev:sprint라고 입력하는 것만으로 Orchestrator는 "CTO 에이전트에게 스프린트 계획을 위임한다"고 이해한다. 슬랙 봇의 슬래시 커맨드와 유사한 개념이라고 생각하면 직관적으로 이해하기 쉽다.

커맨드 실행 플로우를 정의한다

커맨드 이름만으로는 충분하지 않다. 각 커맨드가 "무엇을 하는가"를 구체적인 단계로 정의한다.

### /ai-ceo:morning 의 실행 플로우
1. 각 부문의 `.company/departments/{dept}/STATE.md`를 읽어들인다
2. `.company/approval-queue.md`의 승인 대기 아이템을 읽어들인다
3. 각 프로덕트의 `.company/products/{name}/STATE.md`를 읽어들인다
4. 다음 포맷으로 다이제스트를 생성한다:

## 승인 대기 ({n}건)
- [AQ-xxx] {부문}: {내용} | {파일 경로}

## 부문 상태 요약
| 부문 | 상태 | 진행 중 태스크 | 주의 사항 |
...

이처럼 입력(무엇을 읽는가), 처리(무엇을 하는가), 출력(무엇을 생성하는가)을 명확히 정의한다. 모호함을 없앨수록 에이전트의 출력 품질이 안정된다. "요약해줘"라는 지시보다 "이 파일들을 읽고, 이 포맷으로 생성해줘"가 훨씬 일관된 결과를 낸다.

권한 제어 룰을 넣는다

## 권한 제어 룰

모든 액션은 `.company/steering/permissions.md`의 임계값에 따른다.

- **read-only:** 분석·리포트 계열은 승인 불필요, 자동 실행
- **draft:** 대외 액션（이메일 발송, 청구서 발행, SNS 게시, 배포 등）은 반드시 draft 모드로 생성하고, approval-queue.md에 추가
- **execute:** 임계값 이내의 내부 액션（버그 수정, 테스트 실행 등）은 자동 실행

**중요:** 대외에 영향이 있는 액션을 직접 실행해서는 안 된다.
반드시 draft → 승인 → 실행 파이프라인을 통한다.

이 선언이 승인 파이프라인의 진입점이다. CLAUDE.md에 명기함으로써, Orchestrator가 호출하는 모든 서브 에이전트에도 이 제약이 적용된다. 이 한 줄이 "AI가 멋대로 고객에게 이메일을 보내는" 사태를 막는다.

에러 핸들링