subagent-driven-development

개요

subagent-driven-development란?

subagent-driven-development는 구현 플랜을 서로 독립적인 작업들의 시퀀스로 실행하고, 각 작업을 새로운 subagent가 담당하도록 오케스트레이션하는 에이전트 스킬입니다. 각 작업마다 다음을 수행합니다.

1. 해당 작업만 전담하는 implementer subagent를 생성합니다.
2. 스펙 준수 여부를 검토하는 spec compliance reviewer subagent를 실행합니다.
3. 코드 품질을 검토하는 code quality reviewer subagent를 실행합니다.

이 세 subagent는 모두 엄격하게 제한된 컨텍스트 안에서 현재 작업에만 집중하도록 유지되며, 메인 세션은 전체 조율과 의사결정에 집중할 수 있습니다.

이 스킬은 어떤 사람을 위한 것인가요?

subagent-driven-development는 다음과 같은 개발자와 팀을 위해 설계되었습니다.

• Claude / claude-code 같은 AI 코딩 어시스턴트를 사용하면서 더 신뢰도 높은 결과를 원할 때
• 개별 작업 단위로 쪼개진 문서 형태의 구현 플랜을 기반으로 개발할 때
• 하나의 AI 세션 안에서 코드 구현과 리뷰를 구조적으로, 반복 가능하게 진행하고 싶을 때
• "일단 돌아가는 것"이 아니라 스펙 준수와 코드 품질 모두를 중요하게 여길 때

특히 SHA, 플랜 파일, diff 등을 subagent에 넘길 수 있는 GitHub 중심의 워크플로와 잘 맞습니다.

어떤 문제를 해결하나요?

이 스킬은 하나의 AI 에이전트에게 end‑to‑end 개발을 모두 맡길 때 흔히 발생하는 문제들을 다룹니다.

• 컨텍스트 비대화: 하나의 에이전트가 너무 많은 히스토리를 쌓으면서 집중력을 잃는 문제
• 스펙 드리프트: 구현이 원래 플랜이나 요구사항에서 점점 벗어나는 문제
• 리뷰 약화: 코드를 작성한 것과 동일한 컨텍스트에서 리뷰를 시도해 실수를 놓치는 문제

subagent-driven-development는 작업마다 새로운 에이전트를 사용하고, 컨텍스트를 엄격하게 관리하며, 두 단계 리뷰(스펙 → 품질)를 강제하는 패턴을 제공합니다. 이를 통해 정확도를 높이고 변경 범위를 명확히 유지하며, 구현 플랜의 각 단계에 대해 reasoning하기 쉬워집니다.

언제 subagent-driven-development를 쓰는 것이 좋을까요?

다음과 같은 상황에서 이 스킬 사용을 추천합니다.

• 이미 작업 단위로 쪼개진 구현 플랜이 준비되어 있을 때
• 각 작업이 대부분 독립적이고, 작업 간에 상시 조율이 필요하지 않을 때
• 이 플랜을 현재 세션 안에서 완료할 계획이고, 여러 날에 걸쳐 진행하지 않을 때

아직 플랜이 없거나 작업들이 강하게 연결되어 빠르게 바뀌는 상황이라면, 다음을 고려해 볼 수 있습니다.

• 다른 스킬이나 수동 플래닝을 사용해 먼저 플랜을 브레인스토밍/설계하기
• 탐색적인 작업에는 보다 자유로운 single‑agent 워크플로 사용하기

사용 방법

설치

1. 스킬을 환경에 추가하기

obra/superpowers 리포지토리에서 subagent-driven-development 스킬을 설치합니다.

npx skills add https://github.com/obra/superpowers --skill subagent-driven-development

이 명령은 스킬 정의와 관련 프롬프트 템플릿을 skills-enabled 환경으로 가져와, 플랜의 각 작업에 대해 subagent 오케스트레이션이 가능하도록 합니다.

2. 핵심 파일 살펴보기

설치 후 리포지토리의 스킬 디렉터리(또는 skills 브라우저)를 열어 다음 파일들을 확인합니다.

• SKILL.md – 고수준 설명, 사용 시나리오, 핵심 워크플로
• implementer-prompt.md – implementer subagent용 템플릿
• spec-reviewer-prompt.md – spec compliance reviewer subagent용 템플릿
• code-quality-reviewer-prompt.md – code quality reviewer subagent용 템플릿

이 파일들은 자체 자동화나 도구 연동에 그대로 복사·수정해 사용할 수 있는 템플릿으로 보면 됩니다.

구현 플랜 준비하기

1. 작업 목록 작성 또는 다듬기

subagent-driven-development를 사용하기 전에, 다음 조건을 만족하는 작업들로 구성된 구현 플랜을 준비합니다.

• 범위가 명확하고 테스트 가능할 것
• 서로 간 의존성이 크지 않고, 대체로 독립적일 것
• implementer subagent가 추측 없이 행동할 수 있을 만큼 충분한 상세가 포함될 것

각 작업은 implementer 프롬프트의 “FULL TEXT of task from plan” 부분에 그대로 복사·붙여넣기 할 수 있어야 합니다.

2. 작업 디렉터리와 Git 전략 결정하기

프롬프트 템플릿은 Git 기반 워크플로와 특정 작업 디렉터리를 전제로 합니다.

• implementer가 작업할 directory를 정합니다.
• 변경 사항 추적 방식(예: 각 작업별 BASE_SHA, HEAD_SHA)을 정합니다.

이 값들은 스펙 리뷰와 코드 품질 리뷰 프롬프트에 전달되어, 정확한 리뷰를 가능하게 합니다.

작업 단위로 워크플로 실행하기

1. implementer subagent 디스패치

각 작업 N에 대해, implementer-prompt.md 템플릿을 사용해 새로운 implementer subagent를 생성합니다.

템플릿의 핵심 포인트는 다음과 같습니다.

• implementer에게 명시적으로 *“You are implementing Task N: [task name]”*라고 알려줍니다.
• ## Task Description 섹션에 작업 전체 텍스트를 그대로 붙여넣습니다.
• 다음 항목을 채웁니다.
  • Context – 이 작업이 시스템 내에서 어떤 역할을 하는지
  • directory – 실제 변경을 적용할 디렉터리

implementer에게는 다음과 같은 지침이 주어집니다.

1. 불명확한 부분이 있다면 시작 전에 질문으로 명확히 할 것
2. 작업에 명시된 내용만 정확히 구현할 것
3. 필요 시 테스트를 작성하고 실행할 것
4. 구현 결과를 검증할 것
5. 작업을 커밋할 것
6. 수행한 작업 내용을 명확한 보고서 형태로 정리할 것

각 작업마다 새로운 subagent를 만들기 때문에, 이 에이전트는 오직 당신이 제공한 컨텍스트만 보고 메인 세션의 잡다한 히스토리를 물려받지 않습니다.

2. 스펙 준수 리뷰 수행하기

implementer가 작업을 마치고 보고서를 제공하면, spec-reviewer-prompt.md를 사용해 spec compliance reviewer subagent를 실행합니다.

이 템플릿에서는 다음을 수행합니다.

• ## What Was Requested 섹션에 작업 요구사항을 붙여넣습니다.
• ## What Implementer Claims They Built 섹션에 implementer의 보고서를 붙여넣습니다.

spec reviewer는 implementer의 보고서를 그대로 믿지 말 것을 명시적으로 지시받으며, 다음을 수행해야 합니다.

• 실제 코드를 직접 읽기
• 요구사항을 기준으로 코드 내용을 줄 단위로 비교하기
• 누락된 요구사항, 불필요하거나 원치 않는 작업, 오해에서 비롯된 구현을 식별하기

spec reviewer가 문제를 찾으면, (같은 subagent이든 새로운 subagent이든) implementer와 다시 루프를 돌며 부족한 부분을 채운 뒤 다음 단계로 넘어갑니다.

3. 코드 품질 리뷰 수행하기

스펙 준수 단계가 통과되면, code-quality-reviewer-prompt.md를 사용해 code quality reviewer subagent를 실행합니다.

템플릿은 다음과 같은 code review 스타일의 작업 기술을 기대합니다.

Task tool (superpowers:code-reviewer):
  Use template at requesting-code-review/code-reviewer.md

  WHAT_WAS_IMPLEMENTED: [from implementer's report]
  PLAN_OR_REQUIREMENTS: Task N from [plan-file]
  BASE_SHA: [commit before task]
  HEAD_SHA: [current commit]
  DESCRIPTION: [task summary]

리뷰어는 다음을 점검합니다.

• 구현의 깔끔함과 유지보수 용이성
• 파일 단위 책임과 인터페이스(가능하면 파일당 하나의 명확한 책임)
• 새로 생성되거나 변경된 파일의 크기와 분해 수준이 적절한지
• 테스트 커버리지 및 각 단위를 독립적으로 이해하고 테스트할 수 있는지

리뷰 결과는 강점, 이슈(Critical / Important / Minor), 전체 평가 등 구조화된 피드백 형식으로 반환됩니다.

이 피드백을 바탕으로 다음 중 하나를 결정할 수 있습니다.

• 변경 사항을 그대로 받아들인다.
• implementer에게 후속 리팩터링을 요청한다.

환경에 맞게 워크플로 조정하기

1. 스택에 맞게 프롬프트 커스터마이즈하기

implementer-prompt.md, spec-reviewer-prompt.md, code-quality-reviewer-prompt.md의 템플릿은 의도적으로 일반화되어 있습니다. 이를 다음에 맞게 조정하세요.

• 사용하는 프로그래밍 언어와 프레임워크
• 테스트 관례(예: pytest, Jest, Go test)
• 리포지토리 구조와 네이밍 규칙

세부 내용을 바꾸더라도, 핵심 구조—새로운 subagent, 명확한 섹션, 구체적인 역할 정의—는 그대로 유지하는 것이 좋습니다.

2. 반복 단계 자동화하기

패턴에 익숙해졌다면 스크립트나 도구로 자동화할 수 있습니다.

• 세 subagent 호출(implementer → spec reviewer → code quality reviewer)을 각 작업당 하나의 커맨드로 래핑하기
• 플랜 파일에서 작업별 프롬프트를 자동으로 생성하기
• Git 메타데이터를 읽어 BASE_SHA와 HEAD_SHA를 자동으로 채우기

이렇게 하면 subagent-driven-development를 팀 차원의 반복 가능한 워크플로 자동화로 만들 수 있습니다.

3. 이 스킬이 적합하지 않은 경우

다음 상황에서는 다른 접근법이 더 나을 수 있습니다.

• 작업들 간 의존성이 매우 높아 깔끔하게 분리하기 어려운 경우
• 아직 명확한 구현 플랜이 없는 경우
• 여러 세션에 걸쳐 며칠 동안 컨텍스트를 유지해야 하는 장기 작업이 필요한 경우

이런 경우에는 플래닝, 아키텍처 설계, 장기 실행 에이전트에 초점을 둔 스킬이나 프로세스를 먼저 사용하고, 이후 개별 작업 실행 준비가 되면 subagent-driven-development로 돌아오는 것이 좋습니다.

FAQ

실제로 "subagent-driven-development"는 어떻게 동작하나요?

실제 subagent-driven-development에서는 하나의 전지전능한 에이전트에게 플래닝, 코딩, 리뷰를 모두 맡기지 않습니다. 대신 다음과 같이 진행합니다.

• 메인 세션에서 전체 조율과 전반적인 컨텍스트를 유지합니다.
• 각 작업마다, 필요한 정보만 담은 새로운 subagent를 구성합니다.
• 그 subagent로 작업을 구현한 뒤, 또 다른 두 subagent를 실행해 리뷰를 진행합니다.

이 방식은 역할을 분리하고 컨텍스트를 관리 가능하게 유지하며, 구현 플랜 각 단계의 신뢰도를 높여 줍니다.

일반적인 single-agent 코딩 세션과 무엇이 다른가요?

single-agent 방식에서는 대화 내용과 코드 변경 이력이 하나의 컨텍스트에 계속 쌓이면서 다음과 같은 문제가 생길 수 있습니다.

• 오래된 요구사항과 새로운 요구사항이 뒤섞여 혼동이 생김
• 코드 작성과 리뷰에 같은 사고 패턴이 재사용되어, 리뷰가 형식적으로 흐름

subagent-driven-development는 다음과 같이 다르게 접근합니다.

• 구현과 리뷰에 서로 다른 프롬프트와 역할을 사용합니다.
• 각 subagent를 전체 세션 히스토리가 아닌 선별된 컨텍스트로 시작합니다.
• 리뷰 순서를 스펙 우선, 그다음 품질로 강제합니다.

이를 통해 구현은 더 정확해지고, 리뷰는 더 솔직하고 엄격해지는 경향이 있습니다.

템플릿을 꼭 그대로 따라야 하나요?

그럴 필요는 없습니다. 리포지토리에 있는 템플릿은 implementer, spec reviewer, code quality reviewer 프롬프트를 어떻게 구조화할 수 있는지 보여주는 예시입니다. 다음만 지키면 됩니다.

• 전체 패턴: implementer → spec review → quality review를 유지하기
• 핵심 행동: 예를 들어, spec reviewer는 보고서를 믿지 말고 실제 코드를 읽어야 한다는 점을 유지하기

이 틀 안에서 문구를 조정하고, 프로젝트별 가이드를 추가하고, 사용하는 도구와 관례에 맞게 통합해도 됩니다.

Git 없이도 subagent-driven-development를 사용할 수 있나요?

code quality reviewer 템플릿은 BASE_SHA, HEAD_SHA 같은 필드를 전제로 하는데, 이는 Git 워크플로와 자연스럽게 어울립니다. Git을 사용하지 않는 경우에도 다음과 같이 활용할 수 있습니다.

• 새로운 subagent와 두 단계 리뷰라는 핵심 아이디어는 동일하게 적용할 수 있습니다.
• SHA 대신 before/after 상태를 나타내는 고유 식별자(예: 아카이브 ID, 스냅샷 경로)를 사용하면 됩니다.

이 스킬이 Git 자체를 강제하는 것은 아니며, Git 중심 예시를 제공할 뿐입니다.

이 스킬이 특정 AI 모델에 의존하나요?

리포지토리는 특정 모델을 강제하지 않지만, Anthropic의 Claude / claude-code 같은 현대적인 범용 코딩 모델을 주요 대상으로 합니다. 다음을 만족하는 모델이라면 사용할 수 있습니다.

• 코드와 테스트를 읽고 추론할 수 있을 것
• 커스텀 프롬프트를 가진 여러 subagent를 생성할 수 있는 환경일 것

스택에 agent tools나 task runner가 있다면, 이 템플릿들을 그 시스템에 연동해 사용할 수 있습니다.

subagent-driven-development와 다른 superpowers 스킬 중 무엇을 써야 할지 어떻게 판단하나요?

SKILL.md 파일에 의사결정 기준이 정리되어 있습니다. 구현 플랜이 이미 존재하고, 작업들이 대부분 독립적이며, 현재 세션 안에서 작업을 마칠 계획이라면 subagent-driven-development 사용을 권장합니다. 이 조건이 맞지 않는다면 다음을 고려해 보세요.

• 플랜을 먼저 만들기 위해 플래닝/브레인스토밍 스킬 사용
• 강하게 연결되어 있고 여러 세션에 걸친 작업에는 다른 실행/플래닝 패턴 사용

리포지토리에서는 어디서부터 읽어보면 좋을까요?

이 스킬을 설치하거나 도입할지 평가 중이라면, 다음 순서로 살펴보는 것이 좋습니다.

1. SKILL.md – 스킬의 배경과 고수준 워크플로
2. implementer-prompt.md – implementer subagent를 어떻게 설정하는지
3. spec-reviewer-prompt.md – 스펙 준수 체크 방식 이해하기
4. code-quality-reviewer-prompt.md – 추가적인 품질 및 구조 체크 방식 확인하기

이후에는 이 템플릿들을 자신의 agent 오케스트레이션 또는 워크플로 자동화 환경에 맞게 수정·통합하여, subagent-driven-development의 장점을 온전히 활용할 수 있습니다.