들어가며
솔직히 처음 Claude Code에 서브에이전트를 도입했을 때, 나는 이렇게 생각했다. “큰 작업 하나 던지면 알아서 하겠지.” 근데 현실은 달랐다. 작업이 커질수록 에이전트가 문제를 제대로 쪼개지 못했다. 비효율적인 순서로 처리하는 경우도 생겼다. Claude Code 서브에이전트 PRD 로드맵 자동화를 제대로 쓰려면, 처음 세팅을 잘 잡는 게 핵심이다.
이 글에서는 내가 직접 부딪히며 발견한 두 가지 문제를 정리했다. PRD → ROADMAP.md 자동 생성 흐름도 실제 코드와 함께 소개한다.
서브에이전트에게 큰 작업을 던지면 생기는 2가지 문제
서브에이전트는 강력하지만, 무작정 큰 덩어리를 위임하면 아래 두 가지 문제가 반복된다.
첫째, 문제 분해 실패. 복잡한 요구사항을 받으면 에이전트가 태스크를 잘게 나누지 못한다. 뭉뚱그려 처리하려 하고, 결과물이 대충 나오거나 중간에 맥락을 잃는다.
둘째, 비효율적인 실행 순서. 의존성을 무시하고 작업을 병렬로 돌린다. 선행 작업이 끝나기 전에 후속 작업을 시작하기도 한다. 나중에 고치는 시간이 더 든다.
결국 핵심은 “잘 정의된 컨텍스트를 먼저 만들어주는 것”이다. 그 역할을 하는 게 바로 PRD(Product Requirements Document)다.
PRD란 뭔가요? 왜 먼저 만들어야 할까
PRD(제품 요구사항 정의서)는 “무엇을, 왜 만드는지”를 명확히 적은 문서다. 개발·디자인·사업 팀이 같은 방향을 바라볼 수 있도록 돕는다. 일종의 나침반 역할이다.
서브에이전트에게 PRD를 먼저 제공하면, 에이전트는 목적·범위·우선순위를 명확히 이해한다. 그 결과 훨씬 정교한 결과물이 나온다. 반대로 PRD 없이 막연한 지시만 주면, 앞서 말한 두 가지 문제가 그대로 터진다.
참고: PRD 작성 기준은 Atlassian의 제품 요구사항 문서 가이드에 잘 정리되어 있다.
실전: 서브에이전트로 ROADMAP.md 자동 생성하기
Step 1. 서브에이전트 프롬프트 정의
.claude/agents/development-planner.md 파일에 아래 시스템 프롬프트를 작성한다.
당신은 최고의 프로젝트 매니저이자 기술 아키텍트입니다.
제공된 Product Requirements Document(PRD)를 면밀히 분석하여
개발팀이 실제로 사용할 수 있는 ROADMAP.md 파일을 생성해야 합니다.
이 한 줄의 역할 정의가 결과 품질에 큰 차이를 만든다. “프로젝트 매니저이자 아키텍트”라는 컨텍스트를 주면 달라진다. 단순 나열이 아니라, 우선순위와 의존성을 고려한 로드맵이 나온다.
Step 2. PRD 기반으로 ROADMAP.md 생성
에이전트에게 아래처럼 지시한다.
@agent-development-planner
@docs/PRD.md 문서를 분석해서 로드맵 파일을 생성해줘!
파일위치: docs/ROADMAP.md
결과물이 마음에 들지 않으면, 에이전트 프롬프트 자체를 수정하는 게 효율적이다. 매번 지시를 바꾸는 건 비효율적이다. 에이전트 정의를 한 번 잘 잡아두면 그다음은 훨씬 편해진다.
Step 3. 테스트 강화 옵션 추가
API 연동이나 비즈니스 로직처럼 검증이 중요한 작업이 있다면 어떻게 해야 할까. 에이전트 프롬프트에 아래 조건을 추가하면 된다.
@.claude/agents/development-planner.md 서브에이전트를 수정해주세요.
수정사항:
- API 연동·비즈니스 로직 구현 작업은 테스트를 꼼꼼히 수행할 수 있도록 작성
- 구현 후 반드시 테스트를 수행할 것
- 테스트 시 Playwright MCP를 사용
단계별로 생각해주세요.
Step 4. 변경사항을 ROADMAP.md에도 반영
에이전트 프롬프트를 수정했다면, 로드맵 파일에도 변경 내용을 동기화해야 한다.
@agent-development-planner
조금 전에 수정한 사항을 @docs/ROADMAP.md 파일에도 적용해주세요!
이 흐름이 익숙해지면 구조가 잡힌다. PRD 하나만 잘 써도 로드맵·테스트 계획까지 자동으로 정렬된다. 내부 링크로 관련 글도 참고해봐: Claude Code MCP 서버 연동 실전 가이드
마무리
서브에이전트는 잘 정의된 구조 위에서 진가를 발휘한다. 큰 작업을 던지기 전에 PRD로 컨텍스트를 먼저 잡아라. 에이전트 프롬프트를 명확하게 설계하면 삽질이 눈에 띄게 줄어든다. 처음 세팅에 시간을 조금 더 쓰면, 나중에 수정 비용을 아낄 수 있다.
Claude Code를 쓰고 있다면, 오늘 당장 .claude/agents/ 폴더 하나 만들어보는 것부터 시작해봐.