AI 에이전트 팀 만들기 — 역할·완료 조건·인수인계

AI 에이전트 팀은 여러 에이전트가 각자 역할을 맡아 일 하나를 끝까지 밀고 가는 구성입니다. 그런데 에이전트를 셋 만들었다고 해서 팀이 되지는 않습니다. 이 글은 무엇을 먼저 정해야 팀이 실제로 돌아가는지, 무엇을 근거로 맡기는 범위를 넓히는지를 순서대로 정리합니다. 에이전트 정의 파일의 문법은 커스텀 에이전트 정의 파일 작성법에, 서브에이전트의 기본 동작은 서브 에이전트로 작업 나누기에 있으므로 여기서는 반복하지 않습니다.

핵심 요약

• 팀보다 업무를 먼저 설계합니다. 첫 질문은 "에이전트를 몇 개 둘까"가 아니라 "무엇이 끝나면 끝인가"입니다.
• 완료 조건이 테스트로 확인할 수 없는 문장이면, 에이전트를 늘릴수록 각자 다른 "완료"를 들고 옵니다.
• 팀의 품질은 에이전트가 아니라 경계에서 결정됩니다. 인수인계서 서식과 검수 단계가 실제 팀의 실체입니다.
• 리뷰 자동화는 일부러 심은 결함으로 검출률을 재기 전까지 "통과"를 믿을 근거가 없습니다.
• 맡기는 범위는 기록을 근거로 한 계단씩 올리고, 병렬 실행은 측정 계획이 붙은 가설로 둡니다.

에이전트를 여러 개 만들면 왜 팀이 되지 않나

같은 요구를 세 에이전트에게 그냥 나눠 주면 흔히 이런 장면이 나옵니다. 셋이 서로 다른 해석으로 코드를 고치고, 리뷰를 맡은 에이전트는 셋 모두에 "문제없음"이라고 답합니다. 사람이 보면 세 변경이 서로 모순인데도 그렇습니다.

원인은 모델의 성능이 아니라 빠진 재료에 있습니다. 사람 팀이라면 암묵적으로 공유하는 것들 — 무엇이 완료인지, 누가 무엇에 손댈 수 있는지, 넘겨줄 때 무엇을 적어야 하는지 — 이 에이전트 사이에는 하나도 존재하지 않습니다. 각 에이전트는 자기가 받은 문장만 보고 시작하며, 앞선 에이전트가 무엇을 확인했고 무엇을 확인하지 못했는지 알 방법이 없습니다.

그래서 에이전트를 늘릴 때 같이 늘어나는 비용을 먼저 인정해야 합니다. 얻는 것은 역할별 컨텍스트 분리, 자기 검토의 맹점 회피, 대기 시간 동안의 병행입니다. 새로 생기는 것은 인수인계 비용, 조정 비용, 토큰 비용, 그리고 늘어난 산출물을 사람이 검수해야 하는 부담입니다. 뒤쪽 비용을 줄일 장치가 없으면 에이전트 수가 늘수록 팀은 느려집니다.

팀보다 업무를 먼저 설계한다는 것은 무엇인가

순서를 뒤집는다는 뜻입니다. 정의 파일을 먼저 쓰는 대신, 하려는 일을 업무 단위로 쪼개고 각 업무에 세 가지를 표시합니다.

이 표를 채우다 보면 역할이 저절로 드러납니다. "사람이 결정할 것" 칸에 몰린 업무가 많다면 아직 에이전트를 늘릴 단계가 아니라 사양을 더 써야 하는 단계입니다.

업무 분해 다음 순서는 완료 조건이고, 그다음이 실패하는 테스트입니다. 테스트를 먼저 만들어 두면 구현 에이전트에게 "무엇이 되면 끝인지"를 설명할 필요가 없어집니다. 빨간 테스트가 초록으로 바뀌는 것이 곧 완료 신호이기 때문입니다. 테스트 기대값을 구현 담당이 고치지 못하게 막는 것은 그래서 중요합니다.

완료 조건은 어떻게 써야 하나

완료 조건은 "테스트나 명령 결과로 확인할 수 있는 문장"이어야 합니다. 아래 대비가 기준입니다.

각 완료 조건에는 짧은 ID를 붙입니다. AC-1, AC-2 같은 식이면 충분합니다. ID를 붙이는 이유는 그 뒤로 인수인계서·리뷰 결과·테스트 이름이 전부 같은 단어로 말하게 하기 위해서입니다. 리뷰 에이전트가 "AC-3 관련 처리가 빠졌습니다"라고 답하면 사람은 그 한 줄만 보고 어디를 볼지 압니다. "몇 가지 개선점이 있습니다"라는 답은 그렇지 않습니다.

사양 판단이 필요한 지점은 에이전트에게 결정시키지 않습니다. 예를 들어 규칙을 바꿨을 때 이미 만들어진 기존 항목을 건드릴지는 제품 판단이므로, 사람이 정해 사양서에 적고 그 문장을 완료 조건으로 옮깁니다. 이 구분을 하지 않으면 에이전트는 가장 그럴듯한 쪽을 골라 조용히 진행합니다.

역할 세 가지의 책무는 어디까지인가

구현·리뷰·테스트 세 역할이면 대부분의 작업이 돌아갑니다. 중요한 것은 개수가 아니라 각 역할의 입력·출력·금지·권한이 겹치지 않는지입니다.

책무표를 다 쓴 뒤에는 한 가지만 확인하면 됩니다. 두 역할이 같은 파일을 고칠 수 있는 곳이 있는가. 있다면 파일 소유권을 정하거나 조정 규칙을 적어 둡니다. 도구 권한을 역할에 맞게 좁히는 문법은 퍼미션 설정 최적화에 정리돼 있습니다.

배분을 맡은 메인 세션은 구현하지 않는 편이 낫습니다. 오케스트레이터가 직접 코드를 고치기 시작하면 역할 분리가 무너지고, 메인 세션의 컨텍스트가 작업 세부로 가득 차 배분 판단 자체가 흐려집니다.

에이전트 사이 인수인계서에는 무엇이 들어가야 하나

인수인계서는 에이전트 사이 경계에 놓이는 유일한 문서입니다. 여덟 항목이면 충분합니다.

# 인수인계서

- 작업 ID / 역할:
- 목적 한 줄:
- 완료 조건 상태: AC-1 통과 / AC-2 미확인 / AC-3 실패
- 변경 파일: (경로와 변경 줄 수)
- 검증 결과: (실행한 명령과 출력 원문 그대로)
- 확인하지 못한 것: (범위와 이유)
- 내린 결정과 가정:
- 다음 담당에게 요청:

가장 중요한 칸은 "확인하지 못한 것"입니다. 이 칸이 없으면 에이전트는 확인하지 못한 것을 문제없는 것으로 요약해 넘깁니다. 그다음이 "검증 결과"인데, 여기에는 요약 문장이 아니라 명령 출력 원문만 넣게 합니다. "테스트를 실행했고 모두 통과했습니다"는 확인이 아니라 주장입니다.

필수 항목이 비어 있으면 작업을 끝내지 못하게 막을 수도 있습니다. 종료 시점에 검사를 거는 방법은 Stop 훅과 SubagentStop 훅에 있습니다. 이런 경계 설계를 팀 전체가 같은 기준으로 하게 만드는 과정은 에이전트 팀 운영 교육에서 다룹니다.

한 세션에 끝나지 않는 작업은 어떻게 이어 가나

에이전트 팀이 맡는 일은 대개 한 번의 세션으로 끝나지 않습니다. 이어 가는 근거를 에이전트의 기억에 두면 세션이 끊길 때마다 처음부터 다시 시작합니다. 파일에 남은 것만 믿는다는 원칙을 세우고, 계획서와 진행 로그 두 파일로 상태를 들고 갑니다.

계획서에는 단계마다 완료 조건 ID와 그 단계를 확인할 명령을 붙입니다. 진행 로그에는 단계별 상태와 마지막 검증 결과만 남깁니다.

## 진행 로그

| 단계 | 상태 | 마지막 검증 | 비고 |
|---|---|---|---|
| 1. 도메인 로직 | 완료 | test 12 passed | AC-1, AC-2 통과 |
| 2. 저장소 반영 | 진행 | 미실행 | 파일 소유 확인 필요 |
| 3. 경계 테스트 | 대기 | — | AC-3 미작성 |

세션을 새로 시작한 뒤 사양서·계획서·진행 로그·마지막 인수인계서 네 개만 다시 읽히면 이어집니다. 실제로 한 번 세션을 끊고 재개해 보면 서식에서 빠진 항목이 바로 드러납니다. 재개가 어긋난 지점을 서식에 항목으로 추가하는 것이 유지 방법입니다.

장시간 실행에서 자주 생기는 두 가지 어긋남도 계획서에 미리 적어 둡니다. 하나는 계획에 없던 "좋은 개선"이 끼어드는 것이고, 다른 하나는 같은 실패를 계속 재시도하는 것입니다. 재시도 상한과 사람을 부르는 조건을 숫자로 적어 두면 둘 다 막힙니다. 세션 자체를 다루는 방법은 세션 관리에 있습니다.

리뷰가 통과했다는 말을 믿을 수 있나

리뷰를 자동화하면 가장 먼저 생기는 질문입니다. 리뷰 에이전트가 "문제없음"이라고 했을 때, 그것이 결함이 없다는 뜻인지 결함을 못 찾았다는 뜻인지 구분할 방법이 필요합니다.

방법은 간단합니다. 일부러 결함을 심은 변경을 만들어 리뷰에 넣고, 몇 건을 잡는지 셉니다. 심는 결함은 성격이 다른 세 종류 정도가 좋습니다. 경계 조건 오류 하나, 중복 실행 시 부작용 하나, 그리고 테스트 기대값을 슬쩍 바꾼 변경 하나입니다. 마지막 유형은 특히 중요한데, 구현 담당이 막히면 실제로 자주 시도하는 우회이기 때문입니다.

결과는 표로 남깁니다.

놓친 원인은 입력 부족·지시 부족·모델 한계 중 하나로 분류합니다. 대부분은 앞의 두 가지이고, 리뷰 지시문을 길게 쓰기 전에 리뷰가 받는 입력(완료 조건표, 인수인계서, 변경 내역)이 실제로 전달되고 있는지부터 확인하는 편이 빠릅니다. 이 기록이 있어야 리뷰 구성을 바꿨을 때 나아졌는지 비교할 수 있습니다.

검수는 세 단으로 두는 것이 기본입니다. 기계 판정(테스트·타입·린트), AI 리뷰(완료 조건 대비 변경 내역), 사람 최종 판정(사양 판단·범위·위험). 앞 단계가 통과했다고 뒤 단계를 건너뛰지 않습니다.

자율도는 어떤 근거로 올리나

맡기는 범위를 한 번에 넓히면 되돌릴 수 없는 사고가 납니다. 반대로 계속 좁혀 두면 팀을 만든 이유가 사라집니다. 계단을 만들고 기록을 근거로 한 단계씩 올립니다.

승급 조건은 셀 수 있는 형태로 적습니다. "직전 단계에서 연속 다섯 건이 사람 수정 없이 검수를 통과했다"처럼 씁니다. 강등 조건도 같은 표에 적습니다. 범위 밖 변경 한 건, 되돌리기가 필요했던 사고 한 건이면 한 단계 내립니다. 조건 없이 올라간 자율도는 사고가 났을 때 되돌릴 기준도 없습니다.

병렬로 돌리면 정말 빨라지나

"에이전트를 병렬로 돌리면 몇 배 빨라진다"는 말은 같은 과제를 같은 기준으로 비교하지 않으면 근거가 없습니다. 병렬은 기본값이 아니라 가설로 두고, 가설에는 측정 계획을 붙입니다.

먼저 순차 최소 구성(구현 하나, 리뷰 하나, 사람 판정)으로 한 바퀴 돌리고 아래 항목을 기록합니다. 리드타임, 사람 개입 횟수와 이유, 재작업 왕복 수, 리뷰 지적 수와 그중 채택된 수, 심은 결함 검출 여부, 토큰 사용량. 이 기록이 없으면 비교 대상이 없습니다.

병렬로 나눌지 말지는 세 가지 질문으로 판단합니다. 업무 사이에 의존이 있는가, 파일 소유가 겹치는가, 검수자가 동시에 몇 건을 볼 수 있는가. 셋 중 하나라도 걸리면 병렬로 나눈 만큼 조정 비용이 늘어 전체 리드타임은 그대로이거나 늘어납니다. 특히 세 번째는 자주 빠뜨리는데, 산출물이 두 배가 되어도 검수하는 사람이 한 명이면 병목은 그대로입니다. 세션을 물리적으로 나누는 방법 자체는 서브 에이전트로 작업 나누기에 있습니다.

팀이 이상하게 돌 때 어디부터 보나

증상마다 비어 있는 층이 다릅니다. 먼저 볼 곳을 정해 두면 원인 추적이 빨라집니다.

이 증상들은 대개 조용히 나타납니다. 오류 메시지도 없고 보고서에는 "완료"라고 적혀 있으니, 몇 주가 지난 뒤에야 산출물을 다시 열어 보고 알게 됩니다. 증상별로 실제 장면과 고친 방법을 유형별로 모은 글은 에이전트 팀이 조용히 망가지는 패턴입니다.

정리

• 순서는 업무 분해 → 완료 조건 → 실패하는 테스트 → 역할 정의입니다. 정의 파일을 쓰는 일은 마지막입니다.
• 완료 조건에 ID를 붙여 인수인계서·리뷰·테스트가 같은 단어로 말하게 합니다.
• 인수인계서의 "확인하지 못한 것"과 "검증 결과 원문" 두 칸이 팀의 품질을 좌우합니다.
• 리뷰의 신뢰도는 심은 결함 검출 기록으로만 확인할 수 있습니다.
• 자율도와 병렬화는 기록을 근거로 움직입니다. 측정하지 않은 효과는 가설로 표시해 둡니다.

이어서 볼 글은 커스텀 에이전트 정의 파일 작성법, 퍼미션 설정 최적화, 하네스 엔지니어링 예시입니다. 팀 단위로 역할과 검수 기준을 한 번에 맞춰야 한다면 에이전트 팀 운영 교육을 참고하세요.