[Claude Code] Sub-agents 사용하여 프론트엔드 바이브 코딩하기

Sub-agents로 만드는 프론트엔드 개발 자동화

분석 → 설계 → 구현 → 리뷰, 4개의 전문 에이전트로 개발 파이프라인을 자동화하는 방법

 
Claude Code의 Sub-agents 기능을 프론트엔드 개발에 적용해보고 있고, 여러 방법을 이용해보고 있다.
분석, 설계, 구현, 리뷰 에이전트 4개를 만들어서 사용하고 있고 반복 작업이 눈에 띄게 줄었고, 각 단계의 품질도 일관성 있게 올라갔다. 이 글은 그 과정을 정리한 실용 가이드다. 너무 많으면, 설계 + 구현을 묶어서 진행해도 된다. 하나의 컨택스트에서 공유하기 때문에 오히려 더 좋은 효과를 보여줄 때도 있다.
 
만약, 굳이 sub-agents 를 쓰지 않아도 되는 상황이면, rules, skills 만으로 해결하는 것을 추천한다.

목차

1. Sub-agents란 무엇인가
2. Rules, Skills, Commands와의 차이
3. Sub-agent 만드는 법
4. 프론트엔드 - 에이전트 파이프라인
5. 각 에이전트 실제 구현
6. 사용 방법과 팁
7. 한계와 주의사항

---

Sub-agents란 무엇인가

Sub-agent는 메인 대화와 완전히 분리된 자체 컨텍스트 윈도우에서 동작하는 전문화된 AI 어시스턴트다. 각자 고유한 시스템 프롬프트, 도구 권한, 독립적인 실행 환경을 갖는다.
Claude Code가 특정 작업을 만나면 해당 sub-agent에게 위임한다. Sub-agent는 독립적으로 작업을 수행하고 결과만 메인 대화로 돌려보낸다. 덕분에 메인 컨텍스트가 오염되지 않는다.

핵심 개념: Sub-agent는 수십 개의 파일을 뒤지고, 로그를 분석하고, 문서를 읽어도 그 내용이 메인 대화에 쌓이지 않는다. 깔끔한 요약만 돌아온다. 컨텍스트 보존이 핵심 가치다.

어떻게 해야 현재 프론트엔드 개발에서 유용하게 써볼 수 있을까

모든 개발이 그러하듯이 요구사항 분석, UI 설계, 코드 구현, 접근성/퍼포먼스, 리뷰 등 각각은 서로 다른 전문 지식을 요구한다. 하나의 에이전트가 모든 걸 하면 컨텍스트가 무거워지고, 이전 단계의 노이즈가 이후 단계에 영향을 준다. 전문 sub-agent로 나누면 각 단계가 깨끗한 슬레이트에서 시작하게끔 하고 프로젝트 자체에 Rules, Skills 를 지정하도록 합니다.

Rules, Skills, Commands와의 차이

Claude Code에는 여러 확장 방법이 있어서 처음엔 헷갈린다. 각각이 무엇인지, 언제 써야 하는지 정리했다.
여러 곳에서 Rules, Skills 는 설명했듯이 넘어가면 되고 여기서 핵심적인 것은 Sub-agents 이다.

CLAUDE.md	항상 로드되는 전역 컨텍스트	CLAUDE.md	프로젝트 전반 규칙, 기술 스택, 코딩 컨벤션
Rules	꼭 지켜야하는 원칙	.claude/rules/	디자인 시스템, 보안 요구사항, 필요한 규칙
Skills	재사용 가능한 지식 + 워크플로	.claude/skills/	반복되는 절차, 도메인 전문 지식, 자동 트리거 필요할 때
Commands	명시적으로 호출하는 단축 프롬프트	.claude/commands/	자주 쓰는 워크플로 시작점, /deploy 같은 슬래시 커맨드
Sub-agents	독립 컨텍스트에서 실행되는 전문가	.claude/agents/	자율적 다단계 작업, 컨텍스트 격리가 필요한 작업, 병렬 실행

한 문장 요약: CLAUDE.md는 항상 켜져 있는 배경 지식, Rules는 지켜야되는 법, Skills는 필요할때 사용하는 도메인 지식, Commands는 /슬래시 단축키, Sub-agents는 독립 사무실에서 일하다가 결과만 보고하는 전문 직원이다.

Sub-agent를 쓸 타이밍: Rules, Skills를 먼저 써보고, 작업이 5개 이상 파일을 건드리거나, 컨텍스트 오염이 문제가 되거나, 독립 실행이 필요할 때 Sub-agent로 업그레이드하라. "이게 skill이어야 할까, agent여야 할까?" 라는 고민이 생긴다면 답은 거의 항상 skill 먼저다.

Skills vs Sub-agents 구체적 차이

Skills는 레시피 카드다. 메인 에이전트가 그것을 읽고 직접 실행한다. Sub-agents는 전문 동료다. 메인 에이전트가 브리핑 메모를 건네면, 동료는 자기 사무실에서 일하고 결과물만 가져온다.
Skills Sub-agents

컨텍스트	메인 대화와 공유	완전 분리된 독립 윈도우
호출 방식	자동 감지 또는 명시적	자동 위임 또는 명시적 지명
도구 권한	메인 에이전트와 동일	개별 설정 가능 (더 제한 또는 확장)
병렬 실행	불가	가능 (여러 sub-agent 동시)
적합한 작업	유틸리티 함수, 반복 절차	복잡한 다단계 워크플로, 대규모 탐색

---

Sub-agent 만드는 법

Sub-agent는 YAML 프론트매터와 마크다운 본문으로 구성된 .md 파일 하나다. 이것만 알면 시작할 수 있다.

파일 위치

프로젝트에만 적용하려면 .claude/agents/에, 모든 프로젝트에서 쓰려면 ~/.claude/agents/(글로벌 사용자 디렉터리)에 놓는다. 같은 이름이 있으면 프로젝트 레벨이 우선한다.

기본 구조

---
name: frontend-analyst
description: 프론트엔드 요구사항을 분석하고 구조화된 스펙을 작성한다.
  컴포넌트 설계 요청, UI 요구사항 파악, 사용자 스토리 작성 시 사용하라.
tools: Read, Grep, Glob   # 필요한 도구만 허용 (생략 시 부모 상속)
---

# 역할 정의
당신은 시니어 프론트엔드 아키텍트다.
요구사항을 받아 구체적이고 실행 가능한 스펙을 만드는 것이 전문이다.

## 작업 절차
1. 기존 컴포넌트 구조를 파악하기 위해 프로젝트를 탐색한다
2. 요구사항을 사용자 스토리로 분해한다
3. 컴포넌트 계층 구조를 정의한다
4. 상태 관리 전략을 제안한다
5. 구조화된 스펙 문서를 반환한다

/agents 커맨드로 빠르게 생성

직접 파일을 쓰기 귀찮다면 Claude Code 내에서 /agents를 타이핑하면 인터랙티브하게 sub-agent를 만들 수 있다. Anthropic이 공식 권장하는 방법이기도 하다.

# Claude Code 대화창에서:
/agents

# 또는 직접 지시:
"frontend-reviewer라는 sub-agent를 만들어줘. 
 Read와 Grep 도구만 갖고, 접근성과 퍼포먼스 리뷰에 특화된 에이전트로."

주요 프론트매터 옵션

필드 설명 예시

name	에이전트 고유 식별자	frontend-analyst
description	언제 이 에이전트를 쓸지 설명. Claude가 자동 위임 결정에 사용	"UI 컴포넌트 설계 요청 시 사용"
tools	허용할 도구 목록. 생략 시 부모 대화의 도구 상속	Read, Grep, Glob
model	사용할 Claude 모델. 비용/품질 트레이드오프 조절	claude-haiku-4-5

description 작성 요령: description은 Claude가 이 에이전트를 언제 자동으로 호출할지 결정하는 라우팅 신호다. "무엇을 하는 에이전트인지"보다 "어떤 상황에서 호출해야 하는지"를 구체적인 키워드로 적어야 한다. 모호하게 쓰면 Claude가 라우팅에 실패한다.

---

프론트엔드 -에이전트 파이프라인

내가 실제로 운영하는 구조는 이렇다. 요청이 들어오면 분석 → (플랜, 개발, 검증) → 리뷰 순서로 각 전문 에이전트가 순차적으로 처리한다.

요구사항
   │
   ▼
[01 Analyst]  ── 요구사항 → 스펙
   │
   ▼
[02 Designer]  ── 스펙 → 설계 문서
   │
   ▼
[03 Implementer]  ── 설계 → 코드
   │
   ▼
[04 Reviewer]  ── 코드 → 리뷰 보고서

왜 이 구조인가

단일 에이전트로 "인증 폼 만들어줘"를 시키면, 요구사항 파악, 설계, 구현, 리뷰가 뒤섞여서 품질이 들쭉날쭉해진다. 단계를 나누면 각 전문가가 자기 역할에만 집중하므로 결과물이 일관성 있고, 디버깅도 단계별로 가능하다.

각 에이전트 실제 구현

에이전트를 구현시에는 /agents 를 이용해서 직접 create 하는 방법을 추천한다. (어느정도 정형화된 구조로 제작 해줌)

에이전트 구성 개요

에이전트 역할 허용 도구

frontend-analyst	요구사항 분석 → 컴포넌트 스펙	Read, Grep, Glob
frontend-designer	스펙 → 컴포넌트 설계 문서	Read, Grep
frontend-implementer	설계 → 실제 코드 작성	Read, Write, Edit, Bash
frontend-reviewer	접근성·성능·품질 리뷰	Read, Grep, Glob

Reviewer와 Designer는 파일을 수정할 권한이 없다. 의도적인 설계다. 리뷰어가 실수로 코드를 바꾸는 일이 없다.

사용 방법과 팁

자동 위임 vs 명시적 호출

두 가지 방식이 있다. Claude가 알아서 적절한 에이전트를 선택하는 자동 위임과, 직접 에이전트를 지명하는 명시적 호출이다.

# 특정 에이전트 지명
"frontend-analyst 에이전트를 사용해서 이 요구사항을 분석해줘:
 사용자가 제품을 장바구니에 담고 체크아웃까지 진행하는 플로우"

# 순차 파이프라인 요청
"다음 순서로 처리해줘:
 1. frontend-analyst로 이 요구사항 분석
 2. frontend-designer로 컴포넌트 설계
 3. frontend-implementer로 구현
 4. frontend-reviewer로 리뷰"

파이프라인을 Command로 묶기

4단계를 매번 타이핑하기 귀찮다면 Command로 묶으면 된다. .claude/commands/fe-pipeline.md를 만들어두면 /fe-pipeline으로 전체 파이프라인을 시작할 수 있다.
.claude/commands/fe-pipeline.md

프론트엔드 개발 파이프라인을 실행하라.

사용자의 요구사항에 대해 다음 순서로 처리하라:
1. frontend-analyst 에이전트: 요구사항 분석 및 스펙 작성
2. frontend-designer 에이전트: 컴포넌트 설계
3. frontend-implementer 에이전트: 코드 구현
4. frontend-reviewer 에이전트: 품질 리뷰

각 단계가 완료되면 결과를 확인하고 다음 단계로 진행하라.
사용자 승인이 필요하면 중간에 멈추고 기다려라.

각 에이전트에게 컨텍스트 잘 전달하기

Sub-agent는 메인 대화 내용을 모른다. 오직 Agent 툴의 프롬프트 문자열만 받는다. 따라서 이전 단계의 결과를 다음 에이전트에게 전달할 때는 명시적으로 포함시켜야 한다.

# 좋은 예: 이전 단계 결과를 명시적으로 전달
"frontend-implementer 에이전트를 사용해서 구현해줘.
 다음은 frontend-analyst가 작성한 스펙이다:

 [스펙 내용 붙여넣기]

 이 스펙을 기반으로 TypeScript + React 컴포넌트를 작성하라."

# 나쁜 예: 컨텍스트 없이 위임
"방금 분석한 걸 바탕으로 구현해줘"
# → sub-agent는 "방금 분석"이 무엇인지 모른다

모델별 에이전트 배분

단순한 탐색·검색 작업은 빠른 모델로, 복잡한 구현은 강력한 모델로 배분하면 비용과 속도를 모두 잡을 수 있다.
Opus 가 가장 좋은 것은 안다! 하지만, 토큰이 너무 빨라 없어진다...

# 빠른 탐색에는 Haiku
---
name: frontend-analyst
model: claude-haiku-4-5   # 빠른 파일 탐색, 저렴
---

# 복잡한 구현에는 Sonnet, Opus
---
name: frontend-implementer
model: claude-sonnet-4-6  # 복잡한 코드 작성
---

한계와 주의사항

Sub-agents가 다른 sub-agents를 생성할 수 없다

중요한 제약이다. Sub-agent는 다른 sub-agent를 spawn할 수 없다. 무한 중첩을 방지하는 설계다. 오케스트레이션은 항상 메인 에이전트가 담당한다.

각 호출마다 컨텍스트가 초기화된다

Sub-agent는 이전 호출의 기억이 없다. 매번 새로운 인스턴스로 시작한다. 따라서 "지난번에 네가 분석한 것처럼..." 같은 지시는 통하지 않는다. 필요한 컨텍스트는 프롬프트에 명시적으로 포함해야 한다.

언제 sub-agent 대신 다른 것을 쓸까

작업이 단순하고, 컨텍스트 격리가 필요 없고, 파일을 5개 미만 건드린다면 Skill이 낫다. 단순한 슬래시 커맨드라면 Command면 충분하다. 설정이 복잡해지면 그만큼 유지보수 비용도 따라온다.
 
처음엔 4개 에이전트 설정이 번거롭게 느껴졌다. 하지만 한 번 만들어두면 비슷한 컴포넌트 개발 작업마다 같은 품질의 결과물이 나오는 경험은 강력하다. 특히 Reviewer 에이전트가 접근성 이슈를 빠짐없이 잡아주는 게 가장 체감이 컸다.
시작은 간단하게. 하나의 에이전트부터 만들어보고, 반복적으로 쓰는 워크플로가 생기면 파이프라인으로 엮어라. 복잡성은 필요할 때 추가하면 된다.
 
중요한 것은 이러한 기능이 AI Tools 에 제공되기 시작했고 이러한 기능들을 알고 있어야 우리가 원하는 AX 를 진행할 때 활용할 수 있는 인싸이트가 되지 않을까 한다.