Claude Code 에이전트 시스템 - 혼자서 개발팀 만드는 법

솔직히 말하면, Claude Code를 처음 쓸 때는 그냥 "똑똑한 터미널"이었다. 질문하면 답하고, 코드 짜달라면 짜주고. 근데 에이전트 시스템을 세팅하고 나서는 느낌이 완전히 달라졌거든. 혼자 코딩하는데 팀이 있는 것 같다? 비유가 좀 오글거리긴 한데, 진짜 그렇더라.

에이전트가 뭔데?

Claude Code에서 에이전트는 특정 역할을 가진 AI 분신이다. ~/.claude/agents/ 디렉토리에 설정 파일을 만들어두면, Claude Code가 필요할 때 그 에이전트를 소환해서 작업을 위임하거든.

일반 Claude Code 사용과 뭐가 다르냐고? 핵심은 역할 분리야. "너는 설계만 해", "너는 코드만 짜", "너는 테스트만 돌려" — 이렇게 나눠놓으면 각자의 역할에 집중하니까 결과물의 질이 확 올라간다. 사람 팀이랑 같은 원리지.

내가 운용하는 10명의 에이전트

3개월 동안 다듬은 결과, 지금 내 에이전트 구성은 이렇다.

orchestrator (지휘자) — 사용자 요청을 받아서 적절한 에이전트에게 분배함. 코드를 직접 쓰진 않고 라우팅만 한다. 3개 이상 파일이 수정되거나 2개 이상 모듈에 걸치면 얘가 자동으로 개입하게 해놨거든.

architect (설계자) — 인터페이스 설계, 기술 결정, 구조 잡기를 담당. Opus 모델을 쓰고 있는데, 설계 판단은 비싸더라도 좋은 모델이 맡아야 하더라. 여기서 실수하면 나중에 전부 엎어야 하니까.

coder (구현자) — UI가 아닌 모든 코드 구현. 비즈니스 로직, API, CLI, 스크립트. Sonnet 모델로 돌림. 비용 대비 효율이 제일 좋더라고.

ui-engineer (UI 담당) — 프론트엔드 전담. React, HTML/CSS, Electron UI. coder랑 분리한 이유가 있는데, UI 코드는 컨텍스트가 완전히 다르잖아. 스타일, 접근성, 반응형 — 이런 걸 coder한테 시키면 어중간하게 나오거든.

tester (테스터) — 버그 재현, 테스트 코드 작성, 벤치마크 측정. 수동 테스트 요구는 절대 안 하고 자동화 테스트만 만든다.

reviewer (리뷰어) — 코드 수정 없이 읽기만 함. 불필요한 코드, 네이밍, 잠재 버그를 찾아내는데 — 코드를 "못 고치게" 해놓는 게 포인트야. 리뷰어가 직접 고치면 리뷰가 아니라 추가 작업이 되니까.

나머지 guardian(보안), infra(빌드/배포), doc-writer(문서), planner(작업 분해)까지 합치면 총 10명이다.

에이전트 셋팅 방법

~/.claude/agents/ 디렉토리 안에 에이전트별로 AGENT.md 파일을 만들면 된다. 파일 앞부분에 이런 설정을 적어놓는다.

이름, 설명, 모델(opus/sonnet/haiku 중 선택), 사용 가능한 도구 목록, 타임아웃. 그 아래에 "너는 이런 역할이고 이렇게 행동해라"라는 시스템 프롬프트를 적으면 끝이거든.

근데 여기서 진짜 중요한 게 모델 배분이야.

모델 배분 — 돈 아끼면서 퀄리티 올리는 법

내가 처음에 한 실수가 전부 Opus로 돌린 거다. 당연히 퀄리티는 좋은데, 비용이 장난 아니더라고. 한 달 쓰고 청구서 보고 좀 놀랐지...

지금은 이렇게 나눠놓았다.

Opus (비싼 모델): orchestrator, architect, guardian — 판단이 중요한 역할만.

Sonnet (중간 모델): coder, ui-engineer, tester, reviewer, infra, planner — 실행력 위주.

Haiku (저렴한 모델): doc-writer — 문서 작성은 가벼운 모델로 충분하더라.

이렇게 하니까 비용은 거의 1/3로 줄었는데 체감 퀄리티는 크게 안 떨어졌다. 솔직히 coder한테 Opus 쓰나 Sonnet 쓰나 코드 품질 차이가 미미함. 근데 architect한테 Haiku 쓰면? 설계가 얕아지는 게 바로 느껴져.

파이프라인 — 진짜 팀처럼 돌아가게

에이전트를 만든 것만으로는 부족하고, 이들이 협업하는 흐름을 짜야 한다.

내가 쓰는 기본 파이프라인은 이거다.

"새 기능 추가해줘" → orchestrator가 받음 → planner가 작업 분해 → architect가 설계 → coder/ui-engineer가 구현 → tester가 테스트 → reviewer가 최종 리뷰.

이걸 커스텀 스킬로 만들어놓으면 /new-feature 한 번으로 전체 파이프라인이 돌아가거든. /bugfix, /refactor, /security-audit 이런 것도 만들어놨고. 참고로 각 스킬은 상황에 맞게 파이프라인 순서가 다르다. 버그 수정은 tester가 먼저 재현하고 architect가 원인 분석하는 순서라서 새 기능 흐름과 다름.

병렬 실행 — 속도의 핵심

에이전트 시스템의 진가는 병렬 처리에서 나온다.

서로 다른 파일을 건드리는 작업이면 에이전트 여러 명이 동시에 움직일 수 있어. 예를 들어 coder가 백엔드 API 짜는 동안 ui-engineer가 프론트 컴포넌트 만드는 거지. 같은 파일을 건드리면 순차 실행으로 전환되고.

내가 JCA라는 프로젝트에서 Phase 30개를 2주 만에 끝냈는데, 이 병렬 실행 없었으면 한 달은 걸렸을 거다. Agent Mode, Plan Mode, Memory 시스템, RAG, Git 연동, 웹 터미널 — 이걸 전부 순차적으로 했으면 미쳤겠지.

실패에서 배운 것들

에이전트 시스템 운용하면서 뼈 아픈 실패도 있었다.

"완료했습니다" 사기. 에이전트가 코드 작성하고 "완료됐습니다" 보고하는데, 실제로 실행 안 해본 경우가 있었거든. 특히 보안 분석 도구 프로젝트에서 이게 반복돼서, 결국 "완료 보고 시 테스트 결과 증거 필수" 규칙을 넣었다. 증거 없는 완료 보고는 미완료 취급. 이거 넣고 나서 확 나아졌어.

진입점 동기화 누락. 코드는 수정했는데 문서 업데이트를 빼먹는 경우. CLAUDE.md, MEMORY.md 등 5개 파일을 전부 업데이트해야 하는 규칙인데, 하나 빠뜨리면 다음 세션에서 옛날 정보로 작업하게 되니까 재앙이야. "5개 전부 업데이트 안 하면 작업 종료 금지" — 이 규칙 하나가 얼마나 삽질을 줄여줬는지 모른다.

에이전트 시스템, 누구에게 추천하나?

솔직히 프로젝트 하나에 파일 5개 정도면 에이전트 시스템까지는 필요 없다. 그냥 Claude Code 기본으로 충분해.

근데 프로젝트가 3개 이상이거나, 하나의 프로젝트가 Phase 5개 이상 넘어가면? 에이전트 없이는 컨텍스트 관리가 지옥이 되더라. 나처럼 프로젝트 10개를 동시에 굴려야 하는 상황이면 에이전트 시스템은 선택이 아니라 생존이야.

셋팅하는 데 처음엔 한 2시간 걸렸는데, 한 번 잡아놓으면 모든 프로젝트에서 재사용 가능하거든. 글로벌 에이전트로 만들어놓으면 새 프로젝트 시작할 때도 바로 쓸 수 있고. 투자 대비 리턴이 지금까지 Claude Code에서 한 셋팅 중에 제일 높았다.

다음 편에서는 메모리 시스템 — AI가 세션을 넘어서 나를 기억하게 만드는 방법을 다룰 예정이다.