AI 에이전트로 나만의 전문 개발팀 만들기

요구사항 분석부터 QA까지, 팀이 나눠 하던 일을 Claude Code 멀티 에이전트로 대체한 개발 파이프라인을 만든 이야기입니다.
이 워크플로우는 Claude Code 플러그인으로 패키징되어 어떤 프로젝트에서나 설치해 사용하실 수 있습니다.

해당 플러그인에 대해서는 아래 레포지토리를 통해 확인하실 수 있습니다.

GitHub - WooJJam/claude-taskforce: 요구사항 분석, 설계, TDD, 코드 리뷰 및 QA 전 과정을 Claude Code 멀티 에

 

Introduce

혼자 개발을 진행하면서 개인적으로 가장 아쉬웠던 것은 역할이 없다는 것이다. 회사에서 특정 서비스나 기능을 만들 때를 생각해보면 보통 이런 의사 결정을 거친다.

• 기획, 요구사항을 정리
• 어떻게 구현할지 설계하고 합의하는 과정
• 실제 구현 (TDD, DDD)
• 코드 리뷰어가 PR을 보고 피드백
• QA가 시나리오대로 검증

이 일련의 과정들은 번거로워 보여도, 사실 각 단계가 다음 단계의 품질을 끌어올리는 장치이다. 리뷰어가 있으니 코드를 막 작성하지 않고, QA가 있으니 고려하지 못한 엣지 케이스를 검증할 수 있는것이다. 여러 역할이 한 코드를 다른 관점에서 보기 때문에 품질이 올라간다.

 

그러다 이런 생각이 들었다.

"이 팀 단위 개발 방식을, AI를 이용해 나만의 개발팀으로 만들면 혼자 개발할 때도 코드 품질을 더 끌어올릴 수 있지 않을까?"

 

핵심은 역할 분리다. 일련의 과정을 하나의 에이전트에게 다 요청하면 요구사항을 정리하고, 구현을 한 뒤 자기가 짠 코드를 자기가 리뷰하는 형태가 된다. 사람이 자기 코드는 놓치기 쉬운 것처럼 AI도 구현의 맥락을 그대로 들고 리뷰를 진행하면 객관적으로 판단할 수 없다.

 

따라서 역할을 분리하고, 각 역할을 독립된 에이전트로 분리하자는 목표를 설정했다.

 

내가 만들고자 하는 워크플로우는 다음과 같다.

• 요구사항 -> 설계 -> 구현 -> 리뷰 -> QA를 하나의 명령으로 자동 진행
• 단, 설계 승인 없이는 구현으로 넘어가지 않게 막기
• 리뷰/QA에서 문제가 발생하면 다시 구현 단계로 돌아가 피드백을 반영하는 루프

---

Architecture

architecture

핵심은 역할별 에이전트 + 오케스트레이터 구조다.

`/task <요구사항>` 명령어 한 줄을 입력하면 오케스트레이터가 아래 6개 에이전트를 순서대로 실행한다.

/task 회원 단건 조회 API를 구현해줘

  [자동] Step 1. Researcher   요구사항 정리 + 코드베이스 조사
  [자동] Step 2. Planner      구현 계획 수립
  ─────────── 멈춤: APPROVED: <run-id> 대기 ───────────  ← 유일한 승인 지점
  [자동] Step 3. Implementer  TDD (Red → Green → Refactor)
  [자동] Step 4. Reviewer     코드 리뷰 (아키텍처/보안/품질)
  [자동] Step 5. QA           시나리오 기반 검증
  [자동] Step 6. Summarizer   최종 리포트 정리

---

📌 에이전트의 역할

• Researcher
  • 코드를 건드리지 않고 요구사항 정리
  • 관련 모듈, 기존 코드, 테스트 코드 및 아키텍처 제약, 수정 후보 파일 조사
• Planner
  • 조사 결과를 받아 구현 계획 작성
  • 수정 대상 파일, 구현 순서, 테스트 전략, 검증 명령, QA 시나리오, 리스크 파악
  • 구현 계획 작성 후 승인 요청
• Implementer
  • 승인된 계획대로 TDD로 구현코드 작성
• Reviewer
  • 아키텍처, 보안, 코드 품질 관점에서 리뷰
  • 이슈 발견시 CRITICAL, MAJOR, MINOR로 분류
• QA
  • 정상, 예외, 경계, 회귀 시나리오로 검증
  • 통과 및 실패를 표로 출력
• Summarizer
  • Implementer, Reviewer, QA 결과들을 모아 최종 리포트 작성

---

📌 기대효과

• 컨텍스트 격리
  • Reviewer가 "구현하느라 쌓인 컨텍스트"를 그대로 들고 있으면, 직접 작성한 코드를 객관적으로 보지 못함
  • 에이전트를 새로 실행하면 Reviewr는 결과물만 보고 판단 가능
• 토큰 절약
  • 한 대화에 모든 단계의 컨텍스트가 쌓이면 비대해짐
  • 각 에이전트에 그 단계에 필요한 구조화된 입력만 넘기면 토큰 절약 가능

---

From Idea to System

Claude Code의 두 가지 기능을 조합했다.

• Skill (`.claude/skills/<name>/skill.md`)
  • 각 에이전트의 역할 정의서
  • "너는 Reviewer고, 이슈를 이렇게 분리하고, 이런 형식으로 출력해"가 적힌 문서
• Command (`.claude/commands/task.md`)
  • 오케스트레이터 역할
  • Skill 들을 순서대로 호출하고, 단계 사이에 컨텍스트를 넘기고, 분기 처리

---

📌 승인 게이트

가장 중요한 장치다. Planner가 계획을 내놓으면 거기서 무조건 멈춘다.

계획이 완료되었습니다. (run-id: ai-run-2026-06-05-001)
검토 후 아래 형식으로 승인해 주세요:

APPROVED: ai-run-2026-06-05-001

그리고 규칙을 빡빡하게 잡았다.

• `APPROVED: ` 정확한 형식이 아니면 구현 시작 금지
• "ok", "진행해", "그렇게 해" 같은 모호한 표현은 승인되지 않음

AI는 규칙을 강제하지 않으면 바로 진행하려는 경향이 있다. 명시적 승인 형식을 강제해야 사람이 계획을 실제로 읽고 판단하는 한 박자가 생긴다. run-id는 이 작업 한 건을 추적하는 식별자 역할을 한다.

---

📌 피드백 루프 (Reviewr , QA)

리뷰어와 QA는 단순히 결과만 출력하지 않는다. 재구현 필요: YES / NO 를 반드시 명시한다.

 

• Reviewer가 CRITICAL이나 MAJOR 이슈를 발견
  • 재구현 필요: YES + 수정 지침
• QA 시나리오가 실패
  • 재구현 필요: YES + 실패 항목별 수정 지침

이처럼 재구현이 필요하다면 다시 구현 단계로 돌아갈 때는 전체 재구현이 아니라 수정 지침에 해당하는 범위만 고친다. 그리고 무한 루프를 막기 위해 재실행은 리뷰/QA당 최대 1회로 제한했다.

---

📌 단계 간 컨텍스트 전달

에이전트를 분리할 경우 다음 에이전트는 이전 단계를 모르게 된다. 따라서 반드시 명시적으로 그 결과를 다음 단계로 넘겨주어야 한다.

• Planner에게 → Researcher의 조사 결과 전문
• Implementer에게 → 승인된 계획 전문
• Reviewer에게 → 구현 결과 + 계획의 구현 목표
• QA에게 → 계획의 QA 시나리오 + 구현 결과

이게 가능하려면 각 에이전트의 출력이 다음 에이전트가 그대로 파싱할 수 있는 구조화된 형식이어야 한다. 그래서 Planner 출력 형식을 7개 섹션(구현 목표, 수정 대상, 구현 순서, 테스트 전략, 검증 명령, QA 시나리오, 리스크)으로 고정했다. 사람이 보기 좋으라고가 아니라, 다음 에이전트가 입력으로 받기 위해서다.

---

📌 최종 결과

"회원 단건 조회 API"로 실제로 테스트 해보았다.

 

• Researcher가 기존 회원가입 코드(`UserController`, `UserService`, `ApiResponse` 래퍼, 에러 코드 체계)를 조사
• Planner가 `GET /api/users/{id}` 계획 수립 → 승인
• Implementer가 TDD로 단위/통합 테스트 9개 작성하고 통과
• Reviewer가 리뷰 (보안 이슈 1건을 MAJOR로 처리)
• QA가 시나리오 검증 (정상, 없는 ID, id = 0, 음수 ID)
• Summarizer가 최종 리포트 출력

응답 형식도 성공/실패를 `ApiResponse` 하나로 통일하고, 에러 코드를 `USER-001`(유저 없음), `USER-002`(중복 이메일), `COMMON-001`(검증 실패)처럼 `도메인명 + 인덱스` 체계로 잡았다.

 

이 시스템에서 개인적으로 가장 마음에 드는 부분은 작업이 끝나고 결과지를 남기도록 한 것이다. Summarizer가 마지막에 작업 한 건의 결과지를 남긴다. 변경 파일, TDD 사이클, 리뷰 이슈, QA 결과, 완료 체크리스트가 한 장에 정리된다. 사람 팀에서 작업 끝나고 쓰는 PR 디스크립션, 작업 요약과 같은 역할이다.

 

이러한 최종 결과지가 남으니 나중에 결과지를 통해 변경 사항은 작업내용을 추적할 수 있다. PR 본문에 그대로 붙여도 된다. 어떤걸 바꿨고, 어떻게 검증했나가 기록으로 강제되는 것이 혼자 개발할 때 가장 빠지기 쉬운 부분을 시스템이 메워준다.

---

Wrapping Up

만들고 나서 느낀 점을 정리해보면

• 좋았던 점
  • "이거 만들어줘" 한 줄이 아니라, 계획을 한 번 읽고 승인하는 흐름이 생기니 결과물의 방향이 어긋나는 일이 확 줄었다.
  • 리뷰어/QA가 따로 도니까, 셀프 리뷰의 함정(자기 코드를 너무 관대하게 보는 것)에서 벗어났다.
  • 최종 리포트가 남으니 "뭘 바꿨고 어떻게 검증했는지"가 기록으로 남는다.
• 아쉬운 점
  • 아직 작은 기능 단위에서만 검증했다. 여러 파일에 걸친 큰 기능에서 컨텍스트 전달이 잘 버틸지는 더 봐야 한다.
  • 재실행 1회 제한이 때론 부족할 수 있다. 이건 돌려보면서 조정할 부분
  • 에이전트 역할 정의서(스킬)를 더 다듬으면 품질이 올라간다. 결국 이 시스템의 품질 = 스킬 문서의 품질이다.

 

팀이 있어야만 팀처럼 개발할 수 있는 건 아니다. 역할을 나눈 AI 에이전트들과 그걸 엮는 워크플로우만 있으면, 혼자서도 나만의 개발팀을 가질 수 있다. 이 시스템의 본질은 화려한 자동화도 간편한 시스템도 아니다. 나만의 개발팀을 가지기 위해서 직접 개발 워크플로우를 설계한 것에 있다.

 

각 에이전트의 역할이 무엇인지, 개발자의 승인은 언제?, 피드백 루프는 어떤식으로? 무엇을 다음 단계로 넘길지 이 전체 의사결정을 내 손으로 직접 정의하였다. 도구가 정해진 흐름을 따르는 게 아니라 내가 생각하는 이상적인 개발 방식을 시스템으로 만든 것이다.

 

그러니 자기만의 워크플로우를 만들고 싶다거나 자신만의 이상적인 방식이 있다면 거창한 도구부터 찾지 말고 어떤식으로 정의하고 설계할 수 있을지를 생각해보길 권한다. 그 역할과 흐름을 에이전트로 옮기고, 사이사이에 승인, 피드백이라는 안전장치를 끼우면 그게 곧 나만의 개발팀 워크플로우가 된다.