Claude Code로 멀티에이전트 시스템 만들기 - system-agents-template
Claude Code 세션 여러 개를 독립적인 에이전트로 운영하면서, 서로 채팅으로 소통하고 작업을 분담하는 시스템을 만들었습니다.
템플릿을 오픈소스로 공개했으니, 관심 있으시면 가져다 쓰셔도 됩니다.
왜 만들었나
Claude Code 하나로도 충분히 강력하지만, 규모가 커지면 역할을 나눠야 합니다. 프론트엔드 담당, 백엔드 담당, 인프라 담당 — 사람 팀처럼 AI 에이전트도 역할을 분리하면 훨씬 효율적입니다.
문제는 여러 에이전트가 동시에 같은 파일을 수정하면 충돌이 난다는 것입니다. 그래서 턴제(turn-based) 방식을 선택했습니다.
전체 구조
1
2
3
4
5
6
7
8
system-agents/
├── agents/ ← 에이전트별 역할 정의
├── chatrooms/ ← 파일 기반 비동기 메시징
├── tasks/
│ └── board.yaml ← 작업 보드 (봇만 수정 가능)
├── bot/
│ └── turn-bot.py ← 턴 관리 봇
└── skills/ ← 에이전트 공통 스킬
핵심은 에이전트는 채팅만 하고, 작업 보드는 봇만 수정한다는 것입니다. 이렇게 하면 충돌이 원천적으로 방지됩니다.
턴제 운영 방식
에이전트들은 병렬이 아니라 라운드 단위로 순차 실행됩니다.
1
2
3
4
5
6
7
8
9
=== Round N ===
[Phase 1: Bot] board.yaml 업데이트 (이전 라운드 메시지 반영)
[Phase 2: Plan] 각 에이전트 → 메시지 확인 + 작업 선점(claim)
[Phase 3: Bot] board.yaml 업데이트 (선점 반영)
[Phase 4: Execute] 각 에이전트 → 실제 작업 수행 + 결과 보고
[Phase 5: Bot] board.yaml 업데이트 (결과 반영)
=== Round N+1 ===
계획(Plan)과 실행(Execute)이 분리되어 있어서, 에이전트가 무작정 작업에 들어가지 않고 먼저 상황을 파악한 뒤 움직입니다.
메시지 타입
에이전트 간 소통은 파일 기반 채팅으로 이루어집니다. 일반 대화와 작업 명령을 구분하기 위해 메시지 타입을 나눴습니다.
| 타입 | 용도 |
|---|---|
message | 일반 대화 |
task-create | 새 작업 요청 |
task-claim | 작업 선점 |
task-update | 상태 변경 |
task-done | 작업 완료 보고 |
turn-end | 턴 종료 |
실전 예시: Hetzner 클라우드 배포
실제로 이 시스템을 사용해서 개인 웹사이트 서비스를 Hetzner 클라우드에 배포했습니다.
봇이 task-create 메시지를 처리하고, 에이전트들이 작업을 선점(claim)하는 과정
Peter 에이전트가 Hetzner 서버 생성(CAX21)을 완료하고, Ezra에게 서버 정보를 전달한 뒤 턴을 종료
Ezra 에이전트가 /check-mentions로 Peter의 답장을 감지하고, 채팅룸 메시지를 확인하는 장면
Peter가 전달한 서버 IP, 스펙, ARM 주의사항을 Ezra가 확인하고 다음 작업(Helm 배포)을 준비
이 과정을 타임랩스로 녹화해서 영상으로도 만들었습니다.
타임랩스 녹화에는 직접 만든 lightest-timelapse를 사용했습니다.
시작하는 법
1. 스킬 설치
1
cp -r skills/* ~/.claude/skills/
2. 에이전트 생성
1
cp -r agents/_example agents/MyAgent
role.md에 역할을, CLAUDE.md에 행동 규칙을 정의합니다.
3. 라운드 실행
1
2
3
4
5
6
7
8
9
# 봇 실행
python bot/turn-bot.py
# 각 에이전트 세션
cd agents/AgentA && claude
cd agents/AgentB && claude
# 다시 봇 실행
python bot/turn-bot.py
설계 원칙
- 역할 분리 — 에이전트마다 명확한 책임
- 턴제 소통 — Plan → Execute → Report 사이클
- 간접 변경 — board.yaml은 채팅 메시지를 통해서만 변경
- 충돌 방지 — 에이전트는 append-only, 봇만 보드 수정
- 독립 실행 — 각 에이전트는 다른 에이전트에 의존하지 않음
마무리
AI 에이전트 하나만으로도 많은 일을 할 수 있지만, 여러 에이전트가 체계적으로 협업하면 훨씬 복잡한 작업도 해낼 수 있습니다.
템플릿은 MIT 라이선스로 자유롭게 사용 가능합니다. 도움이 되셨다면 GitHub 스타 부탁드립니다!