Claude Code로 만드는 「병렬 루프 에이전트」 실전! 핸즈온 가이드

안녕하세요. 주로 X에서 AI 주도 개발(AI-driven development)을 발신하고 있는 쿠마이 유(Kumai Yu)입니다!

AI 스타트업에서 CEO 겸 CTO를 맡고 있습니다.

저희 회사에서는 약 10개월 분량의 수탁 개발을 2주 만에, 자사 프로덕트는 「개발~릴리스」를 5일 만에 끝낼 수 있게 되었습니다. 이를 뒷받침하는 것은 **Claude Code로 구축한 「병렬 루프 에이전트 (Parallel Loop Agent)」**입니다. 개요는 아래 슬라이드에 적혀 있으니 함께 확인해 주세요.

자, 이 기사는 소개가 아니라, 빈 디렉토리에서 병렬 루프 에이전트를 직접 구축해 보는 핸즈온(Hands-on) 입니다. STEP 0부터 진행하면, 마지막에는 「자율적으로 작동하며 비용도 가벼운 개발 에이전트」가 손에 남게 됩니다.

이 기사에 대하여

• Claude Code의 **스킬(Skill) × 서브 에이전트(Sub-agent)**를 통해, 개발을 병렬(Parallel) × 루프(Loop) × TDD로 자율 주행시키는 메커니즘을 제로 베이스에서 만듭니다. - 기술 스택은 종속되지 않습니다. 필자는 React/Next.js를 많이 사용하지만, 다른 언어에서도 사용할 수 있도록 설계했습니다.
• 정보를 정확하게 기재하려고 주의를 기울였으나, 예상과 다른 점이 있다면 꼭 댓글로 알려주세요.

원천 소스는 Anthropic의 Nicholas Carlini 씨가 발표한 「병렬 Claude 팀으로 C 컴파일러를 구축한 실험」입니다. 16체의 에이전트를 병렬로 실행하여, 약 2,000 세션·2주 만에 거의 자율적으로 10만 행 규모의 C 컴파일러(Linux 6.9를 x86/ARM에서 구동)를 작성해 냈습니다.

다만 이 실험은 각 에이전트를 Docker로 격리하는 대규모 구성이며, 오케스트레이션(Orchestration)도 사용하지 않는 프로토타입입니다.

이 기사에서는 그것을 그대로 복제하는 것이 아니라, 거기서 얻은 4가지 교훈을 Docker가 필요 없는·1개 세션 내의 서브 에이전트로 재현합니다.

• 무한 루프로 멈추지 않게 한다
• 테스트 주도(Test-driven)로 「완료」를 정의한다
• 병렬화한다
• 출력을 최소화하여 컨텍스트(Context)를 보호한다

2026년의 Claude Code에는 여러 확장 포인트가 있습니다. 혼동하면 설계가 무너지므로, 먼저 4가지를 구분하겠습니다.

확장 포인트	역할	언제 컨텍스트에 포함되는가	사용처
CLAUDE.md	규약·규칙 정의	매번 (기동 시 반드시)	플로우의 골격과 정지 포인트
스킬 (Skill)	방법·절차 (지식)	필요할 때만 (동적 로드)	템플릿·스크립트 동봉
서브 에이전트	실행 (병렬·격리)	부모 에이전트에는 포함되지 않음 (독자 컨텍스트)	무거운 작업의 대행
슬래시 명령어	명시적 트리거	호출했을 때만	반드시 통과해야 하는 관문

효과가 나타나는 부분은 오른쪽 두 열입니다. 매번 컨텍스트에 포함되는 것은 CLAUDE.md뿐이며, 나머지는 필요할 때만 포함됩니다.

이 부분이 비용 설계의 핵심입니다. 매번 통째로 포함되는 CLAUDE.md나 프롬프트는 양이 늘어날수록 "컨텍스트 과금"이 불어납니다. 중간 규모의 CLAUDE.md만으로도 수백~천 토큰이 소모되며, 템플릿을 추가하면 코드를 읽기도 전에 수천 토큰이 사라집니다. 하루에 수십 개의 태스크를 자율 주행시킨다면 무시할 수 없는 수준입니다.

따라서 방침은 간단합니다. 절차와 템플릿은 스킬(Skill)에 두고, CLAUDE.md는 안내 역할에 집중하게 한다. 이것이 「출력을 최소화한다」는 기둥이 됩니다.

완성되면 다음과 같은 구조가 됩니다.

my-project/
├── CLAUDE.md # 안내역 (골격 + 정지 포인트 + 스킬 호출)
├── SPEC.md # 실행하면 feature-spec이 생성
...

실행할 때는 claude를 기동하기만 하면 됩니다. 부모 에이전트가 CLAUDE.md를 읽고, 태스크를 분해하며, 서브 에이전트를 병렬로 실행하고, 필요한 페이즈에서 스킬을 로드하여 결과를 통합합니다. 병렬화가 효과를 발휘하는 것은 조사·구현·검증의 3개 측면입니다.

Parent Agent (Claude Code)
└ CLAUDE.md (안내역) + 필요할 때만 Skill을 로드
Phase 1 조사 〈병렬·읽기〉 Explore
...

Claude Code를 사용하기 시작하면 반드시 이 벽에 부딪힙니다.

부탁한다 → 절반쯤 하고 멈춘다 → 「계속해」 → 또 멈춘다 → ……

3시간 뒤, 「계속해」를 40번이나 치고 있는 자신을 발견하게 됩니다. 이를 해결하는 것이 4가지 메커니즘입니다.

• 사양 주도 (Specification-driven): 구현 전에 「무엇을 만들 것인가」를 사양서로 확정한다.
• 병렬 (Parallel): 독립된 작업을 동시에 실행한다 (조사·구현·검증).
• 루프 (Loop): 완료 조건을 만족할 때까지 자율적으로 실행한다.
• TDD: 「완료」를 기계가 판정할 수 있는 상태를 만든다.

토대가 되는 것은 1번입니다. 사양 없이 병렬로 실행하면 각 에이전트가 제멋대로 해석하여 구현을 시작하고, 통합 시점에 모순이 분출됩니다. 사양서가 모든 에이전트의 공통된 「정답」이 되기 때문에 병렬 처리가 성립합니다.

특히 「어떤 세트가 서로 독립적인가 (=동시에 작성해도 충돌하지 않는가)」를 사양 단계에서 미리 선언해 두는 것이 중요합니다. 이것이 후속 단계인 병렬 구현의 전제가 됩니다. 이 4가지를 이제부터 만들 파일들에 심어 넣겠습니다.

먼저 골격을 준비합니다. 처음부터 skills 디렉토리도 만들어 둡니다.

mkdir my-project && cd my-project
mkdir -p .claude/agents .claude/skills tests
touch CLAUDE.md

CLAUDE.md는 실행 시마다 매번 읽힙니다. 따라서 여기에는 골격과 정지 포인트(Stop point)만을 작성하고, 절차의 상세 내용은 스킬(skills)에 맡깁니다.

# Parallel Subagent Framework
## 실시 시 커스터마이징 (교체할 것)
- 테스트 명령: <테스트 명령> # 예: bun run test / pytest
...

요령은 두 가지입니다. 명령은 <테스트 명령>과 같이 플레이스홀더(Placeholder)로 만들어 기술 스택에 의존하지 않게 하는 것입니다. 그리고 정지 포인트는 「① 사양 리뷰」, 「② 구조화 리뷰」 두 곳으로 고정하는 것입니다.

조사 단계에서는 Claude Code의 내장 서브에이전트인 Explore를 사용합니다. 읽기 전용이며 기본적으로 Haiku 모델을 사용하므로 빠르고 비용이 저렴합니다. explorer.md를 직접 만들 필요 없이, CLAUDE.md에 자연어로 지시를 적으면 Claude가 자동으로 Explore로 위임합니다.

CLAUDE.md에 추가합니다.

## Phase 1: 조사 (병렬·내장 Explore 활용)
다음 세 가지 조사를 각각 독립된 서브에이전트로 **병렬로** 실행한다.
- UI 디렉토리를 조사한다. 관련 컴포넌트의 파일 경로·props 타입·state·주요 이벤트 핸들러를 불렛 포인트로 보고한다. 코드는 작성하지 마라.
...

효과를 발휘하는 것은 **「코드는 작성하지 말고 조사만 할 것」(역할 분리)**과 **「불렛 포인트로 보고할 것」(출력 최소화)**이라는 두 가지 포인트입니다. 불필요한 출력으로 부모의 컨텍스트(Context)를 채우지 않기 위한 제약입니다.

CLAUDE.md의 지시는 「부탁」이지 「보장」이 아니다

CLAUDE.md에 적은 지시는 자연어로 해석됩니다. 「병렬로 실행한다」라고 적어도 Claude가 반드시 병렬로 실행할지는 모델의 판단에 달려 있습니다.

확실하게 병렬 실행을 시키고 싶다면, 셸 스크립트(Shell script)로 claude -p(헤드리스 실행)를 여러 프로세스로 동시에 기동하거나, /batch 명령으로 병렬 에이전트를 전개하십시오. 또한, 「도중에 멈추지 않고 끝까지 자율적으로 달려주길 원한다」면 /goal 명령으로 완료 조건을 설정하면, 조건을 만족할 때까지 Claude가 자율적으로 작업을 계속합니다.

claude -p (헤드리스/SDK 실행)는 종량제로 과금될 가능성이 있다

일반적인 대화 세션은 Pro / Max 구독 범위 내에서 작동하지만, claude -p와 같은 헤드리스/SDK를 경유한 실행은 환경이나 플랜에 따라 구독 범위가 아닌 API 종량제 과금으로 취급될 수 있습니다. 배치(Batch) 방식으로 다수를 실행하면 과금이 늘어날 수 있으므로, 자동화에組み込む(組み込む, 포함시키기) 전에 자신의 플랜에서의 과금 구분과 어떤 키/인증으로 작동하고 있는지를 반드시 확인하십시오.

Explore 모델에 관한 주의사항

문서상 Explore는 기본적으로 Haiku를 사용하는 것으로 되어 있습니다. 다만 환경이나 버전에 따라 세션의 모델을 상속받는 경우가 보고되고 있습니다. 또한 MCP 서버나 플러그인을 다수 설치한 환경에서는 Haiku의 프롬프트 크기 제한을 초과하여 Explore가 실패할 수 있습니다. 그 경우에는 CLAUDE_CODE_SUBAGENT_MODEL 환경 변수로 폴백(Fallback) 모델을 설정하십시오.

이곳이 사양 주도 개발 (Specification-Driven Development)의 구현부입니다. 조사 결과를 사양서 (Specification)로 확정하고, 사람이 승인하면, 이후의 구현·테스트·리뷰는 모두 이 사양을 기준으로 동작합니다. 즉, **사양서가 모든 에이전트의 공통된 "정답(Truth)"**이 되는 것입니다.

템플릿을 CLAUDE.md에 작성하면 매번 컨텍스트에 포함되므로, 스킬 (Skill)로 만들어 사양서를 작성하는 단계에서만 로드하도록 합니다.

---
name: feature-spec
description: 조사 결과로부터 기능 사양서를 생성한다. 신규 기능 구현 플로우에서 사양을 확정하는 단계에서 사용한다.
...

2부 구성으로 만드는 이유는 두 가지가 있습니다.

• 승인 허들을 낮춤: 리뷰어가 비엔지니어라도 사용자 관점인 Part 1만 읽고 승인할 수 있습니다. 단, Part 2도 필요한 경우에는 적절히 수정하십시오.
• 병렬 구현의 전제 조건 설정: Part 2의 **병렬 그룹 선언 (Parallel Group Declaration)**을 통해 "어떤 세트가 파일 독립적인지, 어떤 것이 의존하는지"를 확정해 둡니다. 덕분에 구현 단계에서 안전하게 병렬화할 수 있습니다. 사양 주도 방식과 병렬화가 하나로 이어지는 지점이 바로 여기입니다.

사양서 생성은 플로우 상에서 반드시 거쳐야 하는 단계입니다. 스킬은 "모델이 발화를 판단"하기 때문에, 자동 발화에만 의존하면 호출되지 않을 때가 있습니다. 따라서 STEP 1에서 작성한 대로, CLAUDE.md의 플로우에서 "skill feature-spec 을 사용한다"라고 이름으로 명시적으로 호출하는 것이 안전합니다.

이 단계를 CLAUDE.md에도 한 페이지 추가해 둡니다. 포인트는 정지 ① (사양 리뷰)를 여기서 고정하는 것입니다. 스킬의 발화에 의존하지 않고, 플로우 측에서 "승인 전까지는 구현으로 진행하지 않는다"라고 명시합니다.

## Phase 2: 사양서 (skill「feature-spec」 사용)
조사 결과를 skill「feature-spec」으로 SPEC.md에 정리한다 (2부 구성 + 병렬 그룹 선언).
- 사람에게는 Part 1만 제시하고, Part 2는 "기술 상세 내용이므로 리뷰 불필요"라고 전달한다.
...

구현 중 계속 적용될 품질 규약은 reviewer를 서브 에이전트 (Sub-agent)에 번들링합니다. 우선 TDD의 기본입니다.

## 구현 세트 진행 방식 (RED → GREEN → REFACTOR)
1. 테스트를 먼저 작성한다 (RED)
2. 통과할 수 있는 최소한의 구현을 작성한다 (GREEN)
...

그리고 자율 에이전트에서 가장 중요한 "태만(slacking) 방지"입니다.

## 절대 해서는 안 되는 일
- 테스트를 삭제하거나 무효화하여 "통과했다"고 치부하는 것
- 테스트의 기대값 (Assertion)을 몰래 완화하여 통과시키는 것
...

"기대값을 완화하지 마라"는 것은 삭제 금지만으로는 막을 수 없는 교묘한 우회로입니다.

병렬로 읽는 것은 충돌하지 않습니다. 어려운 것은 병렬로 쓰는 것입니다. 동일한 파일을 여러 에이전트가 건드리면 통합 시에 깨집니다. 그래서 두 가지 조건을 둡니다.

• 파일 독립성: 동시에 실행되는 세트가 서로 다른 파일만 건드린다 (사양서의 병렬 그룹이 이미 선언됨). 이것이 충족되면 worktree조차 필요 없습니다. 각자가 신규 파일을 만들기만 하므로 충돌하지 않습니다.
• 격리: 독립성을 보장할 수 없거나 기존 파일을 여러 세트가 건드리는 경우, 각 구현자를 별도의 git worktree로 나누어 쓰기 충돌을 방지합니다.

병렬 구현 후에는 반드시 **통합 게이트 (Integration Gate)**를 한 단계 둡니다. 공유 파일을 건드리는 결선(합성·라우팅)은 이 단계에서만 1개의 에이전트가 순차적으로 수행하며, 마지막에 모든 테스트와 lint를 통과(Green)시킵니다.

## Phase 3: 구현 (TDD・병렬)
사양서 Part 2의 "병렬 그룹"별로 implementer를 동시 기동. 각자 RED→GREEN→REFACTOR 수행.
- 각 세트는 자신의 파일과 자신의 테스트만 작성한다 (공유 파일은 건드리지 않는다).
...

서브 에이전트는 .claude/agents/에 정의하며, 프론트매터 (Frontmatter)의 model 필드로 역할별 모델을 고정합니다. 태스크마다 동적으로 전환하는 것이 아니라, 역할로 할당하는 것이 포인트입니다.

---
name: implementer
description: 기능 구현·버그 수정용. 복잡한 구현에 사용한다.
...

---
name: reviewer
description: 코드 품질 리뷰용. 코드 변경 후에 사용한다.
...

model

에는 **에일리어스 (alias: haiku / sonnet / opus), 풀 ID (예: claude-opus-4-6), 또는 부모를 상속하는 inherit (기본값)**를 지정할 수 있습니다. 역할과 모델의 대응은 다음과 같은 이미지입니다 (상황에 맞춰 튜닝하세요).

역할	모델	이유
메인 (구현)	opus	복잡한 작업을 수행하는 기초 체력
리뷰	sonnet	속도와 품질의 균형
조사 (Explore)	haiku	고속 · 저비용

각 서브 에이전트(sub-agent)는 독자적인 컨텍스트(context)에서 동작하므로, 메인 대화를 압박하지 않습니다.

model은 에일리어스로 작성할 것. 풀 ID로 작성하면 새로운 모델이 나올 때마다 모든 파일을 다시 작성해야 합니다. 에일리어스(opus / sonnet / haiku)를 사용하면, Claude Code가 최신 대응 모델로 자동 해결해 줍니다.

툴 이름 확인 방법

tools 필드에 지정할 수 있는 툴 이름은 Claude Code의 버전에 따라 달라질 수 있습니다. /tools 명령어로 현재 이용 가능한 툴 목록을 확인하고, 정확한 이름을 사용하세요.

이 부분이 이 글에서 가장 전달하고 싶은 핵심입니다.

병렬 에이전트는 컨텍스트를 절약하면서 동작하기 때문에, 구조적으로 매크로 관점(macro perspective)이 약해집니다. 개별 세트는 통과(green)하더라도, 전체적으로 보면 중복이나 누락이 남을 수 있습니다. 따라서 테스트와 lint가 통과된 '후'에, 사람이 반드시 멈춰서 눈으로 확인하는 리뷰를 넣습니다.

다만, 갑자기 사람이 전체를 정밀 조사하는 것은 부담이 큽니다. 그래서 2단계로 구성합니다.

• 기계 측의 사전 필터링: 사람의 리뷰 전에 '검증을 관점별로 나누어 병렬로 실행하는 공정'을 하나 추가합니다 (한 명에게 전부 보여주는 것이 아니라, 관점별로 여러 리뷰어로 가지를 치는 방식 = 팬아웃 (fan-out)). 읽기 전용 리뷰어를 차원별(정확성 / 사양 커버리지 / 중복 · 스코프 / 타입 안전성)로 동시 기동하여, 각자가 불렛 포인트로 지적 사항만 반환하게 합니다. 읽기만 하므로 충돌이 발생하지 않으며, 단일 리뷰어가 놓칠 수 있는 매크로 문제를 차원 분담을 통해 잡아낼 수 있습니다. 이것이 병렬의 세 번째 요소(즉, 검증의 병렬화)이며, 가장 리스크가 적게 추가할 수 있는 병렬화 방식입니다.
• 사람의 판단: 그 지적 사항을 바탕으로, 마지막에 사람이 /structured-review를 통해 멈춰서 판단합니다.

1단계(기계 측의 필터링)는 STEP 5에서 정의한 reviewer를 차원별로 병렬 기동하는 공정입니다. 플로우(Phase 5 검증)에 대응하는 관문이므로, CLAUDE.md에도 한 페이지 추가해 둡니다.

## Phase 5: 검증을 관점별로 병렬 실행 (읽기 전용 · 정지 ② 이전)
테스트 · lint가 통과되면, reviewer를 차원별로 병렬 기동한다 (읽기만 하므로 충돌하지 않음).
- 정확성 (버그 · 경계 조건)
...

이것은 반드시 발화시키고 싶은 정지 포인트입니다. 스킬(skill)의 자동 발화는 '호출되지 않을 수도 있기' 때문에, disable-model-invocation: true를 붙여 사용자 기동 전용으로 만들고, /structured-review로 명시적으로 호출합니다.

---
name: structured-review
description: 구현 후의 구조화 리뷰 (사람의 최종 체크).
...

많은 자율 주행 플로우(self-driving flow)는 정지 포인트를 '구현 전의 사양 리뷰'로만 설정하고, 구현 후에는 테스트가 통과되면 자동으로 완료되도록 해버립니다. 매크로 관점이 약하다는 것을 알고 있다면, 구현 후에도 관문을 두어야 합니다. 정지는 두 곳, 사양 리뷰와 구조화 리뷰입니다.

disable-model-invocation의 알려진 문제

disable-model-invocation: true를 설정한 스킬이라도, 세션 재개(--resume) 시 모델에게 보여지는 버그나, 반대로 사용자가 슬래시 명령어로 명시적으로 호출해도 Claude가 실행을 거부하는 케이스가 보고되고 있습니다 (2026년 2월 기준 GitHub Issues). 제대로 작동하지 않을 경우, CLAUDE.md의 절대 규칙에

---
name: e2e-runner
description: E2E 테스트와 스크린샷을 생성 및 실행한다.
...

.claude/skills/e2e-runner/
├── SKILL.md
└── screenshot.sh ← 동봉됨

이렇게 하면 E2E 시에만 템플릿과 스크립트가 로드되며, 그 외의 페이즈에서는 단 1바이트도 소비하지 않습니다. 게다가 E2E는 "E2E 작성해줘"라고 하면 발화(trigger)가 명확하므로, 이 부분은 자동 발화에 맡겨도 OK입니다.

루프의 안전장치입니다. "멈추지 마"를 자연어로 쓰는 대신, 2026년 5월 Claude Code v2.1.139에서 도입된 /goal을 사용합니다.

/goal은 완료 조건을 설정하면 달성할 때까지 자율 주행(self-driving)하며, 각 턴이 끝난 후 별도의 에바류에이터(Evaluator) 모델(기본값은 Haiku)이 대화 트랜스크립트(transcript)를 읽고 조건 달성 여부를 판정하는 기능입니다. 조건을 만족하지 못하면 제어권을 반환하지 않고 다음 턴으로 넘어갑니다.

/goal 모든 구현 세트가 통과(green) 되고 lint 통과 및 구조화된 리뷰(structured review) 승인까지 완료할 것

이로써 "멈추지 마"가 말투에 의존하지 않게 되어, 서브 에이전트가 기분에 따라 이탈하는 사고가 줄어듭니다.

/goal 에바류에이터의 한계

에바류에이터 모델은 대화 트랜스크립트만을 읽고 판정합니다. 파일을 읽거나 명령어를 실행하지는 않습니다. 즉, Claude가 "테스트를 모두 통과했습니다"라고 보고하면 에바류에이터는 그것을 믿습니다. 완료 조건은 Claude가 대화 중에 출력으로서 명시적으로 보여줄 수 있는 것(테스트 실행 결과 붙여넣기, lint 출력 등)으로 설정해야 합니다. "코드 품질이 높다"와 같은 주관적인 조건은 작동하지 않습니다.

단, 자율 주행은 폭주와 종이 한 장 차이이므로, 반드시 **서킷 브레이커(Circuit Breaker)**를 장착해야 합니다.

## 서킷 브레이커
- 플로우 시작 시 `/goal`을 1회 설정한 후 자율 주행에 진입한다 (조건 작성 방식은 아래 참조).
- 완료 조건은 타이트하게 (모호한 조건은 무한 루프의 연료가 됨)
...

/goal의 상한선은 플래그가 아니라 "조건문"에 작성한다

/goal의 형태는 다음 세 가지입니다.

명령어	동작
/goal <조건>	골(Goal) 설정 (해당 턴이 즉시 시작됨)
/goal	상태 확인 (경과 시간, 평가된 턴 수, 누적 토큰, 최근 판정 이유)
/goal clear	골 해제 (stop / off / reset / none / cancel 도 동일)

턴 상한선 등은 플래그가 아니라 완료 조건 문장 안에 작성합니다. 공식 예시는 **"or stop after 20 turns"와 같은 턴/시간 절(clause)**입니다. 에바류에이터는 대화에 나타난 내용만 보기 때문에(명령어 실행이나 파일 읽기는 하지 않음), 누적 토큰은 /goal의 상태로 확인은 가능하지만, 토큰 수를 정지 조건으로 삼는 것은 불확실하므로 턴/시간으로 제한하는 것이 확실합니다. 조건문은 최대 4,000자까지 가능합니다.

참고로 /goal의 실체는 **세션 스코프(session scope)의 프롬프트 기반 Stop 훅(hook)**이며, 신뢰 대화(trusted dialog)를 승인한 워크스페이스에서만 동작합니다 (disableAllHooks 등이 활성화되어 있으면 사용할 수 없습니다).

국소 상한(수정 3회)에 더해, 플로우 전체의 상한도 반드시 가져야 합니다.

이제 완성되었습니다. 남은 것은 실행하는 것뿐입니다.

claude
# 또는
claude -p "사용자 목록 화면에 검색 기능을 추가해줘"

부모(Parent)가 CLAUDE.md의 골격을 읽고 다음과 같이 흐릅니다.

• Phase 1 병렬 조사: 빌트인 Explore를 사용하여 동시 조사
• Phase 2 명세서 → 정지①: feature-spec 스킬이 병렬 그룹 선언이 포함된 명세서를 출력하고, 승인을 요청하며 정지
• Phase 3 병렬 구현: 승인 후, 독립된 세트들을 동시에 구현
• Phase 4 통합 게이트: 연결 지점을 한 곳으로 모으고, 테스트 + lint를 통과(green) 상태로 만듦
• Phase 5 병렬 검증 → 정지②: 검증을 관점별로 나누어 병렬 실행하고, 그 지적 사항을 가지고 /structured-review를 통해 다시 정지

조사·구현·검증의 3면에서 병렬성이 효과를 발휘하면서도, 필요한 페이즈에서만 스킬이 로드되므로 컨텍스트는 항상 가벼운 상태를 유지하게 됩니다.

STEP 0~8을 마치면, 여러분의 손에는 이 프레임워크 일체가 남게 됩니다.

my-project/
├── CLAUDE.md # STEP 1,2,4,6,8: 안내자 (골격 + 각 Phase + 정지 + Breaker)
├── .claude/
...

이것이 바로 핸즈온(STEP 0~8)을 통해 구축되는 템플릿 그 자체입니다. 서두의 「완성 이미지」에 등장하는 SPEC.md나 src/의 구현 파일은, 이 템플릿을 실제로 실행했을 때(전항 「실행해 보기」) feature-spec이나 implementer가 만들어내는 결과물이며, 템플릿에는 처음부터 포함되어 있지 않습니다.

STEP 1~8에서는 각 파일을 단편적으로 보여드렸습니다. 여기에서 완성형을 한곳에 모아 정리합니다 (특히 CLAUDE.md는 5개의 STEP에 분산되어 있으며, reviewer.md는 본문에서 생략했던 품질 규약을 전개해 두었습니다). 명령어는 <테스트 명령어>와 같이 플레이스홀더(Placeholder) 상태로 되어 있습니다. 자신의 스택(Stack)에 맞게 교체하면 그대로 작동합니다.

# Parallel Subagent Framework
## 실행 시 커스터마이징 (교체할 것)
- 테스트 명령어: <테스트 명령어> # 예: bun run test / pytest
...

---
name: implementer
description: 기능 구현 및 버그 수정용. 복잡한 구현에 사용.
...

---
name: reviewer
description: 코드 품질 리뷰용. 코드 변경 후에 사용.
...

---
name: feature-spec
description: 조사 결과로부터 기능 명세서를 생성한다. 신규 기능 구현 플로우에서 사양을 확정하는 단계에서 사용.
...

---
name: structured-review
description: 구현 후의 구조화된 리뷰 (인간의 최종 체크).
...

---
name: e2e-runner
description: E2E 테스트와 스크린샷을 생성 및 실행한다.
...

#!/usr/bin/env bash
# E2E 스크린샷 촬영 스크립트 (e2e-runner 스킬 포함)
# Usage: ./screenshot.sh <url> <name>
...

# tests/
테스트 하네스(Test Harness) 보관 장소. 구현 세트별 테스트를 여기에 둔다.
## 규약
...

screenshot.sh에는 실행 권한을 부여해 둡 (chmod +x .claude/skills/e2e-runner/screenshot.sh).

제로(Zero)에서부터 구축해 오며 마지막에 남는 것은 심플합니다. 「무엇을 만들 것인가」를 사양으로서 확정하는 것과, 「마지막 구조화 리뷰」만큼은 인간의 업무라는 점입니다. 이 순서와, 놓쳐서는 안 될 두 개의 관문만 지킨다면 병렬 에이전트는 매우 강력한 무기가 됩니다.

직접 손을 움직이며 읽어주셨다면 기쁘겠습니다. 막히는 부분이나 더 알고 싶은 점이 있다면 꼭 알려주세요! 여기까지 읽어주셔서 감사합니다.

평소에는 GEAR.indigo Biz라는 요구사항 정의·설계 AI 솔루션을 무료로 제공하고 있습니다!

본 에이전트와 조합하여 사용하는 경우도 많으니, 꼭 확인해 보세요!

GEAR.indigo Biz는 BYOK(Bring Your Own Key) 방식으로 무료로 사용할 수 있습니다

「회의 메모를 붙여넣기만 하면. 요구사항과 설계가 알아서 진행된다.」 —— 본 기사에서 쓴 「도구를 잊고, 결정에 집중한다」는 상태를, 꼭 직접 체험해 보시기 바랍니다.