Claude Code의 서브 에이전트 설계: 책임 분할과 툴 권한 제한 방법

당사(合同会社ジョインクラス)에서는 Claude Code의 서브 에이전트를 17개 운영하며, launchd를 이용해 17개 이상의 잡을 무인으로 실행하고 있습니다. '경리', '출판', '아침 다이제스트' 등 사내 부서를 그대로 서브 에이전트로 구성했습니다.

처음부터 순조로웠던 것은 아닙니다. 이전에는 제가 모든 규칙을 CLAUDE.md에 계속 추가하다가, 1,000줄을 넘어서자 규칙들끼리 모순되어 지시와 반대되는 움직임을 보이게 되었습니다. 또 다른 실패는 AI가 임의로 git push --force를 실행하여 브랜치가 사라진 사고였습니다.

이 두 가지 실패로부터 배운 점은 다음과 같습니다.

• 책임(責務)은 서브 에이전트로 분리하고, (현재 200줄 이내로) CLAUDE.md는 간결하게 유지할 것.
• 툴 권한은 '그 책임에 필요한 최소한'으로 제한할 것.

본문에서는 실제로 작동하는 정의 파일과 스크립트를 사용하여, 당일 바로 따라 할 수 있는 절차를 소개합니다.

서브 에이전트는 .claude/agents/*.md에 위치하는 Markdown 파일입니다. 프런트매터(frontmatter)의 tools에서 사용할 툴을 제한할 수 있습니다. 아래는 당사에서 매일 아침 작동하는 '아침 다이제스트' 에이전트의 실제 예시(도입부)입니다.

---
name: ai-ceo-morning
description: 아침 다이제스트 에이전트. 모든 부서의 상태를 수집하여 CEO용 요약본을 생성한다.
...

핵심 포인트는 다음 3가지입니다.

• 부모 에이전트는 이 한 줄을 보고 위임 대상을 결정합니다. '무엇을 할지'에 더해 '어떤 담당인지'를 기재하면 잘못된 위임을 줄일 수 있습니다. description은 라우팅 판단 자료가 됩니다.
• '일단 생략'이 가장 위험합니다. tools를 생략하면 모든 툴이 상속됩니다.
• 본문은 역할/입력 파일/출력 포맷에 집중시키고, 회사 전체 규칙은 부모의 CLAUDE.md 쪽에 배치합니다.

당사에서 효과적이었던 분리 방식은 기능 단위나 부서 단위가 아니라, '어떤 파일(상태)에 기록할지'로 나누는 방법이었습니다.

쓰기 위치가 겹치는 에이전트가 2개 있을 경우, 같은 STATE.md를 서로 덮어쓰는 사고가 발생합니다. 반대로, 쓰기 위치가 유일하게 결정되어 있다면 병렬로 실행해도 충돌하지 않습니다.

판단에 어려움이 있다면 다음 순서로 확인합니다.

• 이 에이전트는 아무것도 쓸 필요가 없는가 → Read / Grep만 (집계/리뷰 계열)
• 쓰는 것이 자 부서의 Markdown만인가 → +Write / Edit
• 명령어 실행이 정말 필요한가 → +Bash (여기서 한 단계 신중하게)
• 외부 통신이 필요한가 → +WebFetch / WebSearch (영업 리서치 등 최소한으로)

경리(CFO) 에이전트에게 Bash를 부여하지 않은 것은 의도적입니다. 재무 데이터를 다루는 담당자가 임의의 명령어를 실행할 필요는 없습니다.

대화 세션이라면 에이전트 정의의 tools만으로 충분합니다. 다만, launchd에서 claude -p를 무인으로 구동하는 경우에는 호출 측에서도 --allowedTools로 제한하도록 하고 있습니다. 정의 파일을 누군가(또는 AI 자신)가 수정하더라도, 실행 시 상한선은 변하지 않기 때문입니다.

아래는 매주 작동하는 출판 부서 잡의 실제 예시(발췌)입니다.

source "/Users/kyoagun/workspace/one-ceo/.company/scripts/lib/claude-run.sh"
cd "$PROJECT_ROOT"
RESULT=$(claude_run dept-publishing --effort low -p "
...

이 작업은 보고서 작성만 하므로, Write/Edit 권한을 부여하지 않았습니다. 보고서의 쓰기는 셸 측(예: echo >> $LOG_FILE)에서 수행합니다. **'AI는 판단과 문서 생성, 파일에 대한 쓰기는 셸'**로 분리해 두면, 어느 부분이 무엇을 망가뜨렸는지 추적하기 쉽습니다.

서브 에이전트를 늘릴수록 다음으로 중요해지는 것은 비용입니다. 저희 회사는 모든 무인 실행(unattended execution)을 claude_run이라는 함수를 통해 통일했습니다.

claude_run() {
local label="$1"; shift
claude --output-format json \
...
}

• --max-budget-usd 3: 폭주하더라도 한 번의 상한선이 정해집니다.
• --output-format json: total_cost_usd의 실측값을 추출하여 라벨별로 cost-tracker.json에 기록합니다. 표준 출력에는 응답 텍스트만 반환되므로, 기존의 claude -p와 대체할 수 있습니다.

실제로 측정해 보니, 단순히 '2+2'를 질문하는 한 번의 호출에도 $0.27~$0.47이 소요되었습니다. 내역의 대부분은 캐시 생성에 사용된 약 41,000 토큰입니다. 이 중 저희 회사 파일(CLAUDE.md, 에이전트, 스킬)은 5,800 토큰밖에 되지 않았고, 나머지는 Claude Code 측의 고정 오버헤드였습니다. 즉, 서브 에이전트의 정의를 짧게 만든다고 크게 줄어들지 않으며, 효과적인 것은 호출 횟수를 줄이는 것입니다. 저희 회사의 결론은 '1 부문당 1 작업을 매일'이 아니라, '필요한 요일에만 --effort low로 하는 것'입니다.

• --bare: 인증 정보를 읽지 않기 때문에 무인 실행 시 Not logged in으로 실패합니다. 주석으로 남겨둡시다. - macOS의 cron은 전체 디스크 접근 문제로 작업이 모두 실패했습니다. launchd를 사용하세요.
• launchd 환경에서는 PATH가 최소한입니다. 스크립트 시작 부분에서 nvm이나 Homebrew의 경로를 export해 주세요.

에이전트는 계속 만들어 놓기만 하면 성능이 저하됩니다. 저희 회사는 매월 1회 다음 스크립트로 '30일 이상 STATE.md가 업데이트되지 않은 부문'을 감지하여 Slack으로 알림을 보냅니다.

AGENT_COUNT=$(ls "$AGENTS_DIR"/*.md 2>/dev/null | wc -l | tr -d '[:space:]')
Current_DATE=$(date +%s)
for state in "$DEPTS_DIR"/*/STATE.md; do
...

'쓰기 위치에서 책임을 분리하는' 설계를 해두면, 업데이트 날짜만 보는 것으로 해당 에이전트가 작동하고 있는지 알 수 있습니다. 이것 역시 분할 기준을 통일해 두는 장점입니다.

더불어, 각 에이전트의 tools를 일람하는 원라인(one-liner)도 준비해두면 권한 점검이 몇 초 만에 끝납니다.

# 각 에이전트에 부여된 툴을 목록으로 표시
for f in .claude/agents/*.md; do
printf '%-28s ' "$(basename "$f" .md)"
...

Bash를 가진 에이전트 목록을 보면서, '이 담당에 정말 필요한가'를 매달 재검토하고 있습니다.

• .claude/agents/의 모든 파일에 tools가 명시되어 있는지 확인합니다 (생략은 전 권한). - 책임을 '쓰기 위치'로 분리하고, 쓰기 위치가 겹치지 않는지 표로 만들어봅니다.
• 무인 실행 시에는 --allowedTools와 --max-budget-usd를 호출 측에서 반드시 지정합니다. - 상태 파일의 업데이트 날짜로 에이전트가 살아있는지 감시합니다.

저희 회사는 한때 10개 사업부를 동시에 운영했고, 그중 9개 사업부의 매출은 제로였습니다. 거기서 3개 사업부로 줄일 수 있었던 것은 AI 운영 자체가 거의 손댈 필요가 없었기 때문입니다. 서브 에이전트 설계는 사소하지만 경영 시간을 만들어내는 토대가 됩니다.

서브 에이전트 간의 연계 패턴, 병렬 실행, 부모-자식 간의 컨텍스트 전달 등은 도서 『Claude Code 멀티에이전트 개발』에서 체계적으로 설명하고 있습니다.