Claude Code 서브에이전트 워크플로: PM과 기획, 개발, QA로 나눠 쓰는 내 방식

요즘 Claude Code로 작업할 때는 PM, 기획, 개발, 검증 역할을 나눠서 쓰고 있다.

나는 PM에게 요청하고 필요한 역할에 일을 넘기도록 정해뒀는데, 이번에는 채팅 SDK에 작성한 역할 정의와 작업 규칙을 중심으로 어떤 순서로 작업하고 결과를 받도록 했는지 정리해봤다.

이전에는 이 구성을 에이전트 팀이라고 표현했지만 공식 Agent Teams와 혼동될 수 있어 서브에이전트 워크플로로 제목과 설명을 정리했다. 아래 내용은 내가 작성한 역할과 작업 규칙에 관한 것이고, 실행 로그로 모든 위임이 이대로 동작하는지 검증한 기록은 아니다.

역할별 커스텀 에이전트 구성

채팅 SDK에는 PM을 포함해 9개의 커스텀 에이전트를 두고 있다.

PM 아래에는 기획팀장과 개발팀장이 있고, 각 팀장이 담당 업무를 관리하도록 역할을 정했다. 구성도의 연결선은 지시와 보고에 관한 책임을 나타내며, 실제 실행에서 리더가 하위 에이전트를 직접 호출했는지까지 보여주는 것은 아니다.

기획팀은 이름만 보면 기획서만 만드는 팀 같지만 개발 전 영향 분석과 개발 후 QA까지 담당하고, 개발팀은 마크업과 화면 동작, 채팅 엔진 연동으로 나눴다. HTML과 스타일을 만드는 일, DOM 이벤트를 연결하는 일, Sendbird를 다루는 일을 구분해 둔 셈이다.

여기서 팀장과 팀원은 내가 정한 업무 책임 구조다. 역할 파일에 적어둔 지침과 실제 호출 방식은 구분해서 봐야 한다.

PM 아래 기획 에이전트과 개발 에이전트의 역할 구성

01-role-structure.ko.drawio

0.01MB

PM 아래 기획팀과 개발팀의 역할 구성

기획팀은 이름만 보면 기획서만 만드는 팀 같지만, 개발 전 영향 분석과 개발 후 QA까지 담당한다.

개발팀은 마크업, 화면 동작, 채팅 엔진 연동으로 나눴다. HTML과 스타일을 만드는 일, DOM 이벤트를 연결하는 일, Sendbird를 다루는 일을 구분해 둔 셈이다.

여기서 그림의 팀장과 팀원은 내가 정한 업무 책임 구조다. 아래 내용은 저장소에 작성한 작업 규칙을 설명한 것이고, 실행 로그로 모든 위임이 이대로 동작하는지 검증한 기록은 아니다.

설정을 파일로 나눠 관리하기

내 설정은 크게 네 군데로 나뉜다.

• CLAUDE.md: 프로젝트 구조와 빌드 방법, 코드 작성 규칙
• AGENTS.md: 공통 판단 기준과 책임 경계, 작업 순서
• .claude/agents/*.md: 각 에이전트의 역할과 도구, 모델 설정
• PROMPT.md: 지금 진행할 한 가지 작업

채팅 SDK의 CLAUDE.md에서는 @./AGENTS.md로 공통 지침을 연결해 뒀다.

에이전트 파일에는 “너는 개발자야”라는 역할 이름뿐 아니라 무엇을 맡고 어디까지 수정하며 누구에게 결과를 넘길지도 적었다. 예를 들면 마크업 담당은 HTML과 SCSS를, 프론트엔드 담당은 DOM과 이벤트, 상태 연동을 맡고, QA는 검증 결과를 보고하며 수정은 개발 역할에서 하도록 나눴다.

현재 SDK 파일에서는 PM에 Opus, 팀장과 실무 에이전트에 Sonnet 계열 모델을 지정해 뒀다. 이건 내 설정 예시이고 모델 이름이나 도구 이름은 사용하는 Claude Code 버전에 맞춰 확인하면 된다.

기능 하나를 요청했을 때의 흐름

이 프로젝트의 PM 역할에 작업을 맡길 때는 이런 식으로 요청하도록 정했다.

PROMPT.md에 적은 작업을 pm-agent로 처리해줘.
기존 동작에 미치는 영향을 먼저 확인하고,
구현 후에는 검증 결과까지 정리해줘.

역할 지침에 적어둔 흐름은 PM이 목표와 범위를 정리하고 기획팀장이 개발 전에 영향을 확인하는 순서다.

새 기능이나 큰 변경이면 pdca-planner가 Plan과 Design 문서를 작성하고 architecture-agent가 구조와 영향을 분석하며, 작은 수정은 문서 작성 단계를 건너뛰도록 했다.

이 결과를 PM이 받아 개발팀장에게 넘기고, 개발팀장은 담당 파일과 완료 기준, 선행 작업을 적은 작업 카드로 일을 나누도록 정했다.

구현이 끝나면 개발팀장이 PM에게 보고하고 PM이 기획팀장에게 사후 검증을 요청하도록 했으며, QA에서는 타입과 린트, 빌드뿐 아니라 공개 API와 구조 규칙도 확인하게 했다.

개발 역할에서 작업을 끝냈다고 말하는 것과 검증이 통과했다는 보고를 구분해 둔 것이다.

02-request-workflow.ko.drawio

0.01MB

같이 해도 되는 일과 순서가 필요한 일을 구분한다

역할을 나눴다고 전부 동시에 실행하도록 하지는 않았다.

같은 컴포넌트의 HTML 구조와 DOM 이벤트를 바꿀 때는 마크업이 먼저 끝나야 해서 프론트엔드 담당이 확정된 구조를 읽고 이벤트를 연결하도록 했고, 서로 의존하지 않는 스타일 작업과 채팅 이벤트 작업은 병렬로 처리할 수 있는 경우로 구분해 뒀다.

이건 두 작업이 독립적인 경우의 설계 예시다. 실제 작업에서는 개발팀장이 의존 관계를 확인하고 순서를 정하도록 해뒀으며, 이 글에서 해당 규칙대로 병렬 실행됐는지까지 검증한 것은 아니다.

마크업과 채팅 엔진 작업이 독립적일 때 병렬 진행 후 화면 로직 연결

03-implementation-dependencies.ko.drawio

0.01MB

마크업과 채팅 엔진 작업이 독립적일 때 병렬 진행 후 화면 로직 연결

이 그림은 두 작업이 독립적인 경우의 예시다. 실제 작업에서는 개발팀장 에이전트에 의존 관계를 확인하고 순서를 정하도록 해뒀다.

QA에서 문제가 나오면 어디로 돌아가나

QA 이후의 처리 기준도 미리 나눠뒀다. 타입 오류나 린트 오류, 빌드 실패처럼 수정 범위가 명확한 문제는 사용자에게 매번 다시 묻기보다 개발 역할에서 수정하고 재검증하도록 정했다.

구성도에는 기획팀장에서 개발팀장으로 재작업이 전달되는 흐름을 표시했지만, 이 선이 두 역할 사이의 실제 직접 메시지나 호출을 입증하는 것은 아니다.

재작업은 최대 3회로 제한하고 그 안에 해결되지 않으면 PM에게 올리도록 했으며, 공개 API 계약이나 구조 규칙을 건드리는 문제와 예상하지 못한 사이드이펙트는 PM이 영향 범위와 선택지를 정리해서 나에게 묻도록 했다.

SDK는 외부 서비스와 연결되어 있어서 내부 코드만 보고 바꾸면 곤란한 부분이 있다. 그래서 오류를 고치는 일과 기존 약속을 바꾸는 결정의 경계를 적어뒀다.

일반 코드 오류의 재작업과 구조와 계약 문제의 사용자 확인 분기

04-qa-rework.ko.drawio

0.01MB

프로젝트마다 역할과 작업 절차는 다르게 둔다

이 구성을 모든 프로젝트에 그대로 복사해서 쓰는 건 아니다.

이력서 사이트의 로컬 설정은 콘텐츠와 기획 및 조사, 디자인, 개발, 검증의 5개 그룹으로 나뉜다. 자기소개서 첨삭은 콘텐츠 편집에서 관점 검토와 데이터 일관성 확인으로 이어지게 하고, 화면 구현은 UX와 디자인, 개발, 검증을 거치도록 구분해 뒀다.

이력서에는 채용 담당자와 개발팀 리더 관점, 날짜와 경력 정보의 일관성처럼 코드와는 다른 검토가 필요해서다. 모든 요청에 모든 역할을 투입하지 않고 작업 종류에 맞게 고르는 방식이다.

내가 요청할 때 적어두는 것

역할 이름보다 작업 범위와 완료 기준을 구체적으로 적는 데 신경 쓰고 있다. 작업 요청은 아래처럼 쓸 수 있다. (설명을 위한 예시)

목표: 새 메시지 수신 시 하이라이트 표시
범위: 메시지 아이템 스타일과 렌더링 로직
기존 동작: 사용자가 이전 메시지를 읽는 중이면 강제 스크롤 금지
완료 기준: 하이라이트 표시와 해제, 기존 스크롤 동작 확인
보고: 변경 파일, 실행한 검증, 미확인 항목

작은 버그나 단순 수정은 직접 요청하고 여러 영역에 걸치는 기능은 PM에게 맡긴다. 매번 모든 역할을 거칠 필요는 없어서 이렇게 구분해뒀다.

내가 정해둔 규칙은 누가 무엇을 맡고 어떤 결과를 넘기며, 어디서 내 확인을 받을지에 관한 것이다. 지금도 프로젝트에 맞게 조금씩 바꾸며 쓰고 있으니 비슷하게 구성해보고 싶다면 PM과 개발, 검증부터 나누고 필요한 역할을 추가해봐도 좋을 것 같다.

이후 이 구성을 참고해 공통 절차를 분리한 claude-subagent-workflow를 만들었다. 이 글의 SDK 설정과 완전히 같은 구성은 아니고, 현재 플러그인은 메인 세션이 PM을 맡아 /subagent으로 호출하는 방식이다. 설치와 사용법은 별도 글에 정리했다.

참고

.claude/agents/의 커스텀 서브에이전트 정의와 Claude Code의 별도 Agent Teams 기능은 구분해야 한다. 공식 Agent Teams에서도 이 역할 정의를 팀원에게 적용할 수 있어 해당 폴더가 있다는 것만으로 실행 방식을 단정할 수는 없다.

SDK에는 Agent Teams 활성화 설정도 있지만 설정 파일만으로 모든 작업이 그 방식으로 실행됐다고 말할 수는 없으며, 이 글은 역할 정의와 작업 규칙을 설명한 기록이다. 기능과 버전별 동작은 서브에이전트 공식 문서와 Agent Teams 공식 문서에서 확인할 수 있다.