13개 에이전트로 소프트웨어를 배포한다는 것
"이거 Claude한테 물어보니까..."로 시작하는 경험담이 이제 팀 전체 워크플로우 이야기가 됐습니다. dev.to에 올라온 실전 사례를 보면, 한 개발자가 tmux 13개 패널에 Claude Code 에이전트를 각각 띄워놓고 실제 프로덕트를 매일 배포하고 있습니다. 이건 실험이 아닙니다. 이게 그 팀의 실제 운영 방식입니다.
아침 9시에 버그가 접수되고 오후 3시에 배포가 나갑니다. 그 사이에 다른 피처 4개가 병렬로 진행됩니다. 13개 에이전트가 빠른 게 아니라, 13개 에이전트가 동시에 움직이는 겁니다. 멀티 에이전트의 핵심 가치는 속도가 아니라 병렬성입니다.
에이전트가 망하는 이유: 경계 없이는 카오스
실전 사례에서 가장 인상적인 부분은 에이전트 구성입니다. 조율(super, pm, owner), 엔지니어링(eng1, eng2, arch), 품질(qa1, qa2), 운영(ops, shipper), 성장(growth, pmm, pmm2)으로 역할이 명확히 분리됩니다. 그리고 각 에이전트마다 CLAUDE.md가 있습니다.
여기서 핵심 키워드는 경계(boundary) 입니다. eng2는 이슈를 닫을 수 없습니다. qa1은 코드를 작성하지 않습니다. pmm은 앱 소스에 절대 손대지 않습니다. 이 경계가 없으면 에이전트들은 "도움"을 줍니다—건드릴 필요 없던 코드를 리팩터링하고, 검증 안 된 이슈를 닫고, 자신이 판단할 자격이 없는 아키텍처 결정을 내립니다.
3개 에이전트일 때는 느슨한 공유 프롬프트로도 됩니다. 13개에서는 명확한 역할과 프로토콜이 조율과 카오스의 차이를 만듭니다. 팀원들에게 AI-First 마인드를 심어줄 때도 마찬가지입니다—"뭐든 해줘" 방식이 아니라, 역할을 정의하고 경계를 설정하는 것이 멀티 에이전트의 시작점입니다.
CLAUDE.md: 지시가 아니라 신호 설계
AI로 이거 어떻게 하면 좋을까요? CLAUDE.md 작성 방식이 에이전트 행동의 품질을 결정합니다. dev.to의 CLAUDE.md 모범 사례 글이 이 문제를 정확히 짚습니다.
저자는 직접 실험합니다. pytest 실행 규칙을 산문 단락에 넣었더니 에이전트가 무시했습니다. ## Testing 헤더 아래 코드 블록으로 옮겼더니 그대로 따랐습니다. 지시 내용은 같았습니다. 신호 강도가 달랐습니다.
7가지 핵심 규칙을 정리하면:
- 이유를 함께 써라 — "force push 금지"보다 "force push 금지 — 공유 히스토리 덮어쓰기, 복구 불가"가 낫습니다. 이유가 있으면 에이전트는 규칙을 일반화합니다. 명시하지 않은 유사 상황에도 올바른 판단을 내립니다.
- 헤더 계층은 3단계까지 — h5까지 내려가면 어떤 레벨이 지배하는지 에이전트가 혼란스러워합니다.
- 명령어는 반드시 코드 블록 — 문장 안의 명령어는 설명입니다. 백틱 안의 명령어는 실행 지시입니다.
- 표준 섹션명 사용 —
## Quality Assurance Verification Process대신## Testing. 에이전트는 수백만 개의 README로 학습했습니다. 익숙한 이름이 신호이고, 창의적인 이름은 노이즈입니다. - 실행 가능한 지시만 — "모범 사례를 따르세요"는 지시가 아닙니다. 지금 당장 에이전트가 행동할 수 없다면 소원이지 지시가 아닙니다.
- 파일명을 서술적으로 —
docs/guide.md대신docs/api-authentication.md. 파일명이 에이전트의 첫 번째 필터입니다. - 헤더 구조로 앵커 포인트 생성 — 에이전트는 산문을 파싱하지 않습니다. 헤더를 목차처럼 스캔합니다.
컨텍스트 엔지니어링: 프롬프트보다 근본적인 문제
"AI가 생성해준 걸 기반으로 우리가 다듬으면..."이라는 접근이 작동하려면, AI가 올바른 맥락을 갖고 있어야 합니다. Collin Wilkins의 컨텍스트 엔지니어링 글이 이 문제를 구조적으로 분석합니다.
화요일엔 완벽한 코드가 나왔는데 목요일엔 3달 전에 버린 프레임워크 패턴으로 코드를 생성합니다. 같은 모델, 같은 코드베이스, 같은 개발자인데요. 이 차이를 설명하는 변수는 AI가 실제로 볼 수 있었던 것입니다.
컨텍스트는 4개 레이어입니다:
| 레이어 | 내용 | 지속성 |
|---|---|---|
| 프로젝트 구조 | 폴더명, 파일 네이밍, 결정 위치 | 영구 |
| 지시 파일 | CLAUDE.md, Cursor rules | 영구 |
| 파일 레벨 문서 | 주석, 타입 어노테이션 | 영구 |
| 세션 컨텍스트 | 현재 세션 대화, 읽은 파일 | 일회성 |
대부분의 개발자는 레이어 4에만 집중합니다. 좋은 프롬프트를 씁니다. 그런데 레이어 4는 세션이 끝나면 사라집니다. CLAUDE.md 한 시간 투자는 모든 미래 세션에 복리로 적립됩니다. 한 시간 동안 더 나은 프롬프트를 작성하면 딱 한 번 적립됩니다.
또 하나 중요한 것—프라이머시 문제입니다. 모델은 컨텍스트 윈도우의 앞과 뒤를 중간보다 훨씬 잘 기억합니다. CLAUDE.md의 300번째 줄에 있는 중요한 규칙은 아무리 잘 써도 기능적으로 보이지 않습니다. 네이밍 컨벤션, 절대 건드리면 안 되는 것—이건 파일 맨 위에 있어야 합니다.
AI 생성 코드 검증: "그럴듯함"과 "배포 가능함" 사이
"AI로 리뷰 받아보니까 이런 게 나오더라고요"—그런데 AI가 생성한 코드를 AI가 리뷰한다고 끝이 아닙니다. dev.to의 레드팀 체크리스트 글이 이 갭을 실전적으로 다룹니다.
AI 생성 코드는 그럴듯하고 틀릴 수 있습니다. AI 출력을 아직 같이 일해보지 않은 주니어 개발자의 코드처럼 다루라는 조언—빠르고 도움이 되지만, 일관된 리뷰 프로토콜이 필요합니다.
12개 실패 모드 중 현장에서 가장 자주 보이는 것들:
- 스펙 드리프트: AI는 요청한 것에 인접한 것을 잘 만듭니다. 요청한 것 그 자체를 만들었는지 한 문장으로 검증하세요.
- 조용한 에러 처리:
try/catch: pass나 이유 없는null반환. 개발 중엔 크게 실패하게 만드세요. - 테스트 환상: 자기 자신을 호출해서 단언하는 동어반복 테스트. 코드를 의도적으로 깨뜨렸을 때 테스트가 실패하는지 확인하세요.
- 관찰 가능성 공백: 네트워크 호출이 있으면 타임아웃 + 재시도 정책 + 로깅이 세트입니다. AI는 이걸 빠뜨립니다.
- 보안 지뢰: 문자열 연결 SQL, 로그에 찍히는 토큰, 느슨해진 인증—AI는 "일단 동작하게" 만들다가 이런 걸 넣습니다.
이거 자동화하면 우리가 더 중요한 일에 집중할 수 있습니다. PR 템플릿에 이 체크리스트를 박아두세요. 5~10분짜리 리뷰가 프로덕션 장애를 막습니다.
실제로 안 풀리는 것들
멀티 에이전트 운영에서 잘 안 풀리는 문제들도 솔직하게 공유됩니다. 13개 에이전트가 동시에 같은 API 계정을 쓰면 레이트 리밋에 동시에 걸립니다. QA가 검증 단계를 바운스 백하면 20분짜리 사이클이 5분이어야 할 일에 생깁니다. 컨텍스트 윈도우가 65%를 넘으면 에이전트가 자기가 무엇을 하고 있었는지 잃어버립니다. 에이전트가 같은 실패 명령을 루프로 재시도하다 멈추기도 합니다.
이 마찰들이 불편하지만 부하를 지탱합니다. QA 프로토콜을 생략할 때마다 프로덕션에서 뭔가 터졌다는 게 실전 경험입니다. 컨텍스트 관리 프로토콜이 없으면 에이전트가 방향을 잃습니다. 마찰은 제거 대상이 아니라 설계의 일부입니다.
팀에 적용할 수 있는 것들
기획 단계부터 AI를 끼면 훨씬 효율적입니다—그런데 그 AI가 제대로 된 컨텍스트를 갖고 있어야 합니다. 지금 당장 팀에 적용할 수 있는 순서는 이렇습니다.
이번 주: CLAUDE.md를 산문에서 구조화된 마크다운으로 바꾸세요. 헤더, 코드 블록, 이유 포함. 팀 전체가 같은 지시를 따르는 에이전트를 경험하게 됩니다.
이번 달: 컨텍스트 레이어를 감사하세요. 영구 레이어(프로젝트 구조, 지시 파일, 문서)에 뭐가 있는지 확인하고, 세션마다 반복 설명하는 것들을 레이어 1~3으로 올리세요.
다음 분기: 역할 분리를 실험하세요. 2~3개 에이전트부터 시작해서 명확한 경계를 설정합니다. 경계가 없는 에이전트는 "도움"이라는 이름으로 예측 불가능하게 행동합니다.
멀티 에이전트 시스템의 병목은 AI 성능이 아닙니다. 컨텍스트 설계, 역할 정의, 검증 프로토콜—이 세 가지가 에이전트 플릿을 카오스에서 조율로 바꾸는 인프라입니다. 그리고 이건 AI의 문제가 아니라 팀 리드의 설계 문제입니다.