요즘 깃허브에서 가장 눈에 띄는 멀티 에이전트 저장소는 역할을 많이 모아 둔 쪽입니다. 프런트엔드 개발자부터 커뮤니티 운영자까지 전문 역할 에이전트를 묶어 둔 agency-agents는 11월 7일 확인 기준 별이 16만 6천 개를 넘었습니다. 저희가 11월 4일 공개한 AI DEV DIRECTOR는 반대 방향의 멀티 에이전트입니다. 역할은 셋뿐이고, 대신 서로 다른 회사의 AI가 서로의 일을 검사합니다. AI 코드 리뷰를 사람이 아니라 구조에 맡긴 셈입니다. 공개 소식은 지난 글에서 전했으니, 이번에는 실제로 설치해서 첫 미션을 돌리고 결과 화면을 읽는 데까지 한 단계씩 따라가 보겠습니다.
준비물: 로그인된 AI 코딩 도구 두 개
AI DEV DIRECTOR는 API 키를 쓰지 않습니다. 이미 로그인해 둔 Claude Code, OpenAI Codex, Google Antigravity 가운데 최소 두 개의 구독 세션을 그대로 빌려 씁니다. 그래서 첫 관문은 프로그램 설치가 아니라 이 도구들을 내 컴퓨터에 깔고 로그인해 두는 일입니다. 나머지 준비물은 윈도우 10이나 11, Python 3.9 이상, Git입니다.
세 도구가 처음이라면 저희가 정리해 둔 AI 에이전트 완전기초 따라하기부터 보시는 게 빠릅니다. 1편은 클로드 코드, 2편은 Codex, 3편은 안티그래비티로, 설치부터 첫 부탁까지 복사해서 쓰는 문장과 함께 담았습니다. 세 편 가운데 두 편을 끝내면 준비가 된 것입니다.
설치하고 테스트부터 돌려 보기
저장소를 받은 폴더에서 pip install -r requirements.txt로 필요한 부품을 깐 뒤 python -m pytest -q를 돌립니다. 테스트는 604개이고 실제 AI를 부르지 않는 가짜 도구로 돌아서 약 25분 걸립니다.
11월 4일 기준 593개가 통과하고 3개가 실패하는데, 이 3개는 README에 이유를 적어 둔 알려진 차이입니다. 빈 폴더도 자동으로 준비하도록 바뀐 뒤 옛 화면 테스트 두 개가 맞지 않게 됐고, 나머지 하나는 제외 목록 시험 자료가 어긋난 것입니다. 안전장치와 미션 쪽 테스트는 모두 통과합니다. 11월 8일 v3.1.8에서 운영체제별 분기 테스트 8개가 더해졌고, 윈도우에서 모두 통과했습니다.
첫 미션을 시키는 세 가지 방법
가장 쉬운 길은 콘솔입니다. start-companion.ps1을 실행하고(macOS/Linux는 v3.1.8부터 start-companion.sh, 미검증) 브라우저에서 127.0.0.1:8081을 열면 세 AI가 무대처럼 보이는 화면이 뜹니다. 아래 입력창에 하고 싶은 일을 한 줄로 쓰면 그게 미션이 됩니다. 명령줄을 쓰신다면 세 가지가 있습니다.
run: 작업 하나를 한 번만 돌립니다. "src/calc.py에 add를 만들고 테스트를 추가해"처럼 작은 일에 맞습니다.mission: 큰 목표를 HEAD가 단계로 쪼개고, 단계마다 테스트와 리뷰 결과를 보고 다시 계획합니다.do: 미션과 결과 반영을 한 번에 합니다.--profile quick처럼 빠르게, 보통, 깊게 중에서 고를 수 있습니다.
처음이라면 run으로 함수 하나를 시켜 보고, 결과가 원본에 어떻게 들어오는지 본 뒤 mission으로 넘어가시길 권합니다.
미션 한 바퀴는 이렇게 돕니다
HEAD가 목표를 작업 명세로 바꿉니다. 고쳐도 되는 경로, 파일 수, 바꿀 수 있는 줄 수가 여기에 적힙니다. BUILDER는 그 안에서만 파일을 통째로 써서 제출하고, Scope Guard가 명세를 벗어났는지 먼저 봅니다.
통과하면 원본과 떨어진 격리 작업본에서 빌드와 테스트가 돌고, 다른 회사 모델인 REVIEWER가 처음 보는 눈으로 검수합니다. 마지막에 HEAD가 통과, 실패, 수정 지시 중 하나를 고릅니다. 이 AI 코드 리뷰 단계에서 응답이 없거나 깨지면 통과가 아니라 실패로 처리됩니다.
결과 화면 읽는 법
내부 기록이 없는 시연용 계산기 프로젝트에 "calc 패키지에 multiply와 divide를 추가하고, 0으로 나누면 ValueError를 내라"는 미션을 준 뒤의 화면입니다. 위쪽 미션 칸을 보면 최대 6단계 가운데 1단계로 끝났고, 테스트 5개가 모두 통과해 원본에 적용됐습니다.
아래쪽은 그날 시연 인스턴스의 AI별 작업량입니다. 호출 6번 가운데 실패가 1번 있었고, BUILDER 칸에는 Antigravity 1번, Claude 1번이 찍혀 있습니다. 한 도구가 막히면 다음 도구가 이어받는 장애 조치가 이렇게 기록으로 남습니다. 검수는 Codex가 맡아, 만든 쪽과 검사한 쪽이 다른 회사로 유지됐습니다. 멀티 에이전트에서 눈여겨볼 것은 에이전트 수보다, 누가 누구를 검사했는지가 이렇게 남는지입니다.
막혔을 때 먼저 볼 것
큰 변경은 파일 전체를 주고받는 방식이라 AI 도구의 출력 한도에 걸릴 수 있습니다. 이때는 한 번 압축해서 다시 시도하고, 그래도 안 되면 다른 도구로 넘어갑니다. 구독 한도가 끝난 경우도 같은 순서로 넘어갑니다.
넘어가다 HEAD와 REVIEWER가 같은 회사 도구로 몰리면 결과에 "독립성 낮음" 표시가 붙습니다. 계획·판정과 AI 코드 리뷰를 같은 회사가 맡은 셈이니, 그 표시가 보이면 결과를 한 번 더 직접 확인하세요. 작업본이 쌓였다면 clean-worktrees에 --dry-run을 붙여 무엇이 지워질지 먼저 봅니다. 멈추고 싶을 때는 채팅에 "멈춰"라고 쓰거나 작업 정지 버튼을 누르면 돌던 도구가 바로 끊깁니다.
자주 묻는 질문
API 키가 필요한가요? 아니요. 코드가 환경 변수에서 API 키를 모두 지운 뒤 도구를 부르기 때문에, 키가 있어도 쓰이지 않습니다. 각 도구의 구독은 갖고 계셔야 합니다.
도구가 두 개뿐이어도 되나요? 됩니다. 로그인된 도구가 최소 두 개면 돌아가고, 만든 쪽과 다른 회사 도구가 검수를 맡도록 역할을 콘솔에서 바꿀 수 있습니다.
필요한 것은 AI DEV DIRECTOR 소개 페이지에, 소스 전체는 GitHub 저장소에 있습니다.