들어가며

아무리 커다란 문제라도 작게 쪼개내어 하나씩 해결하다 보면 효과적으로 풀 수 있다. 사실 이 말은 개발 프로젝트에도 그대로 적용된다. 근데 문제는 “어떻게 쪼개냐”다. 감으로 나누다 보면 놓치는 게 생기고, 나중에 다시 설계하느라 더 오래 걸린다.

Claude Code 서브에이전트 ROADMAP 생성을 활용하면 이 문제를 구조적으로 해결할 수 있다. PRD 문서 하나만 잘 써두면, 에이전트가 알아서 로드맵까지 뽑아준다. 나는 development-planner라는 서브에이전트를 직접 만들어서 쓰고 있는데, 세팅 방법을 처음부터 공유해본다.

Claude Code development-planner 서브에이전트로 ROADMAP.md 자동 생성하는 코드 에디터 화면

development-planner 서브에이전트란?

Claude Code에서 서브에이전트는 .claude/agents/ 폴더 안에 마크다운 파일로 정의한다. 파일 하나가 곧 하나의 전문 에이전트다.

development-planner는 PRD 문서를 분석해서 개발팀이 실제로 쓸 수 있는 ROADMAP.md 파일을 만드는 전용 에이전트다. 내가 설정한 시스템 프롬프트는 이렇다.

당신은 최고의 프로젝트 매니저이자 기술 아키텍트입니다.
제공된 Product Requirements Document(PRD)를 면밀히 분석하여
개발팀이 실제로 사용할 수 있는 ROADMAP.md 파일을 생성해야 합니다.

짧아 보이지만, 이 역할 정의 하나가 결과물의 품질을 크게 바꾼다. “프로젝트 매니저이자 아키텍트”라는 컨텍스트를 주면 에이전트는 단순 나열이 아니라 우선순위와 의존성을 고려해서 로드맵을 짠다.

모델은 opus, 색상 태그는 red로 설정했다. 중요도가 높은 에이전트일수록 구분하기 쉽게 색상을 지정해두는 편이다.

Claude Code 서브에이전트 ROADMAP 생성: 실전 3단계

Step 1. 에이전트 파일 생성

.claude/agents/dev/development-planner.md 경로에 파일을 만든다. Claude Code에서 /agents 명령어를 치면 에이전트 목록이 뜨고, Create new agent를 선택하면 된다.

에이전트 설명란에는 아래처럼 작성했다.

Use this agent when you need to create, update, or maintain a ROADMAP.md
file in Korean. This includes initial roadmap creation, adding new
development phases, updating task statuses, and ensuring consistency
with project structure.

설명이 구체적일수록 Claude Code가 자동으로 적절한 상황에 에이전트를 추천해준다. 대충 쓰면 대충 쓰인다.

Step 2. PRD 문서 준비

에이전트에게 넘길 PRD 파일을 docs/PRD.md 경로에 미리 작성해둔다. PRD에는 최소한 아래 내용이 있어야 에이전트가 제대로 된 로드맵을 만든다.

프로젝트 목적과 배경
핵심 기능 목록
사용자 스토리 또는 요구사항
우선순위 기준

PRD가 부실하면 로드맵도 부실하게 나온다. 쓰레기를 넣으면 쓰레기가 나온다는 법칙은 AI에도 예외 없이 적용된다.

Step 3. 에이전트 호출로 ROADMAP.md 생성

Claude Code 채팅창에 아래처럼 입력한다.

@"development-planner (agent)"
@docs/PRD.md 문서를 분석해서 로드맵 파일을 생성해줘!
- 파일위치: docs/ROADMAP.md

@ 로 에이전트를 지정하고, @docs/PRD.md로 파일을 컨텍스트로 넘긴다. 에이전트는 PRD를 읽고 단계별 개발 계획, 마일스톤, 작업 항목이 담긴 ROADMAP.md를 자동으로 생성한다.

내 프로젝트 기준으로 보면, 10개 이상의 에이전트를 운영 중이다. starter-cleaner, ui-markup-specialist, code-reviewer, prd-generator, prd-validator 등 역할별로 나눠서 각자 맡은 일만 한다. 이렇게 역할을 분리해두면 에이전트끼리 간섭이 없고, 결과물의 일관성이 높아진다. 관련 내용은 Claude Code 서브에이전트 PRD 로드맵 자동화 가이드에서도 확인할 수 있다.

서브에이전트 분리의 핵심 원칙

하나의 에이전트에 모든 걸 몰아넣으면 안 된다. 내가 직접 부딪히며 배운 원칙은 세 가지다.

첫째, 에이전트 하나는 역할 하나. development-planner는 로드맵만 만든다. 코드 리뷰는 code-reviewer가 한다. 역할이 섞이면 결과물도 섞인다.

둘째, 모델은 역할에 맞게 선택. 판단이 필요한 아키텍처 작업에는 opus, 빠른 반복이 필요한 마크업 작업에는 sonnet을 쓴다. 무조건 좋은 모델이 정답이 아니다.

셋째, 에이전트 설명은 영어로 구체적으로. Claude Code 내부 라우팅이 영어 기반이라 설명이 영어일 때 자동 추천 정확도가 높다.

마무리

PRD 하나로 ROADMAP.md까지 자동으로 뽑아낼 수 있다. 처음 에이전트 세팅에 30분을 투자하면, 이후 프로젝트마다 로드맵 작성 시간을 아낄 수 있다. 큰 문제를 작게 쪼개는 건 사람이 하고, 쪼갠 걸 정리하는 건 에이전트가 한다. 이게 내가 생각하는 AI와의 협업 방식이다.

.claude/agents/ 폴더가 아직 비어있다면, 오늘 development-planner 하나부터 만들어봐.

Claude Code 서브에이전트로 ROADMAP.md 자동 생성하는 법development-planner 실전 세팅