나의 엔지니어링 워크플로우를 복제하는 자율 에이전트 팀 구축하기

저는 에이전트 기반 AI (agentic AI)와 밀접하게 작업해 왔으며, 수많은 반복 과정을 거친 끝에 작업을 읽는 것부터 검토 가능한 브랜치를 푸시하는 것까지 제가 실제로 일하는 방식을 복제할 수 있는 작은 에이전트 팀을 구축했습니다.

이 포스트에서는 네 명의 특화된 에이전트와 이들을 엔드 투 엔드 (end to end)로 조율하는 하나의 기술에 대해 살펴보겠습니다.

멘탈 모델 (The Mental Model)

제가 작업을 맡을 때, 저의 워크플로우는 다음과 같습니다.

에이전트 팀은 이를 정확히 반영합니다:

/ship <task 또는 Jira key>
      └─ clarifier     — 작업이 충분히 구체적인가?
      └─ planner       — 코드베이스 탐색, 구현 계획 작성
...

핵심 통찰: 각 에이전트는 하나의 작업과 고정된 출력 계약 (output contract)을 가집니다. 자유 형식의 채팅은 없습니다. 에이전트는 구조화된 토큰 (PLAN_WRITTEN, REVIEW_RESULT, TEST_RESULT)을 방출하며, 오케스트레이터 (orchestrator)는 이를 파싱하여 다음 단계를 라우팅합니다. 이 방식은 더 저렴하고 빠르며, AI의 환각 (hallucination)을 방지합니다.

플래너 (Planner)

코드를 작성하기 전에, 우리는 코드베이스를 탐색합니다. 이미 존재하는 것이 무엇인지 찾고, 의존성 (dependencies)을 확인하며, 차단 요소 (blockers)를 찾아냅니다. 플래너 에이전트도 동일한 작업을 수행합니다.

플래너는 작업 설명이나 Jira key를 읽고, 코드베이스를 탐색한 다음, 상세한 구현 계획을 출력합니다. 여기에는 생성/수정할 파일 경로, 체크박스 단계, 그리고 정확한 코드 변경 사항이 포함됩니다. 상세한 계획은 다음 하위 에이전트들의 추측을 제거합니다.

---
name: planner
description: "Planner 에이전트는 작업 설명과 코드베이스 디렉토리를 전달받아 관련 파일을 탐색하고, writing-plans 형식으로 상세한 구현 계획을 작성합니다."
...

Implementer (구현자)

Implementer 에이전트는 계획을 읽고, 새로운 브랜치를 생성하며, 모든 작업을 순서대로 실행하고, 다음 단계로 넘어가기 전에 각 청크(chunk)를 커밋합니다. 두 가지 모드가 있습니다:

Normal mode (일반 모드) — 계획을 단계별로 따릅니다. 테스트 실패 또는 빌드 오류가 발생하면 즉시 중단합니다. 절대 추측하지 않습니다.

Blocker-fix mode (차단 요소 수정 모드) — REVIEW_BLOCKERS가 전달되었을 때 활성화됩니다. 원래의 계획을 무시합니다. 나열된 문제점들만 수정하고, 테스트를 다시 실행하며, fix(review): resolve review blockers라는 메시지와 함께 커밋합니다.

이 이중 모드가 리뷰-재시도(review-retry) 루프를 작동하게 만드는 핵심입니다.

---
name: implementer
description: Implementer 에이전트는 구현 계획을 읽고 작업을 하나씩 실행하며, 각 청크를 현재 브랜치에 커밋합니다.
...

Reviewer (검토자)

Reviewer 에이전트는 브랜치를 기본 베이스(default base)와 비교하고 모든 발견 사항을 분류합니다:

Blocker (차단 요소) — 정확성 버그, 보안 문제, 데이터 손실 위험, nil 역참조(nil dereference), API 계약 위반.

Nit (사소한 사항) — 명명 규칙 불일치, 중복 코드, 관찰 가능성(observability) 공백, 패턴 이탈.

Signal bar (신호 바) - 신뢰도가 ~80% 미만인 발견 사항은 제외됩니다. 이는 불필요한 리뷰를 줄여줍니다.

모든 버그 발견 사항은 Implementer 에이전트에게 다시 전달됩니다.

---
name: reviewer
description: Reviewer 에이전트는 기본 베이스 브랜치와 브랜치를 비교(diff)하고 구조화된 Blocker/Nit 발견 사항을 출력합니다. Blocker는 파이프라인을 중단시킵니다.
...

Tester (테스터)

마지막은 테스터 (Tester) 에이전트입니다. 이 에이전트는 모든 테스트 파일을 테스트함으로써 변경 사항이 코드를 깨뜨리지 않는지 마지막으로 확인합니다. 제 작업은 Golang과 매우 밀접하게 연관되어 있기 때문에, 이 테스터 에이전트는 Golang 언어에만 집중합니다.

---
name: tester
description: Tester agent runs go vet, go test -race -short, and golangci-lint (if .golangci.yml present). Returns PASS or FAIL with compact summary.
...

Ship Skills (Ship 기술)

이 모든 에이전트들은 스스로 실행되지 않습니다. 이 에이전트들을 워크플로우 (Workflow)로 오케스트레이션 (Orchestrate)할 기술이 여전히 필요합니다.

/ship <task or Jira key>

Pipeline:
...

Design Decisions (설계 결정 사항)

에이전트들은 산문 (Prose)이 아닌 구조화된 토큰 (Structured tokens) (PLAN_WRITTEN:, REVIEW_RESULT:, BLOCKED:)을 출력합니다. 산문은 오케스트레이터가 의도를 추출하기 위해 두 번째 LLM 호출을 실행하도록 강제하며, 이는 지연 시간 (Latency)을 추가하고, 비용을 증가시키며, 환각 (Hallucination)된 라우팅으로 인한 새로운 실패 지점을 만듭니다. 구조화된 토큰을 사용하면 오케스트레이터가 단순한 문자열 매칭을 통해 분기할 수 있습니다: 결정론적(Deterministic)이며, 추론이 필요 없고, 잘못된 라우팅이 발생하지 않습니다.
80% 신뢰도 임계값 (Confidence threshold) — 가장 중요한 품질 레버 (Quality lever)입니다. 거짓 양성 (False positives)은 엔지니어가 리뷰어를 무시하도록 만들며, 노이즈가 많은 출력은 수정되는 대신 건너뛰어지게 됩니다.
서로 다른 에이전트는 서로 다른 비용/역량 간의 트레이드오프 (Tradeoffs)를 가집니다. 플래너 (Planner)는 깊은 추론 (Deep reasoning)이 필요합니다 (Opus). 리뷰어 (Reviewer)는 정밀함이 필요합니다 (Sonnet). 테스터 (Tester)는 단순히 명령어를 실행합니다 (Haiku). 잘못된 모델 할당은 예산을 낭비하거나 발견 사항을 놓치게 만듭니다.
리뷰-재시도 (Review-retry)는 2회로 제한됩니다. 제한 없는 루프는 API 크레딧에 대한 서비스 거부 공격 (Denial-of-wallet attack)과 같습니다.

만약 당신이 똑같은 "탐색(explore) → 계획(plan) → 구현(implement) → 리뷰(review) → 테스트(test)" 루프를 열 번째 반복하고 있는 자신을 발견했다면, 그럴 필요가 없습니다. 그 루프는 자동화 가능합니다. 당신은 그저 그것을 기록하기만 하면 됩니다.