subagent-driven-development

subagent-driven-development 스킬 개요

subagent-driven-development가 실제로 하는 일

subagent-driven-development 스킬은 구현 계획을 실행 가능한 작업으로 쪼개고, 각 작업을 새 subagent에 독립적으로 맡긴 뒤, 모든 결과를 명세 준수 여부 먼저, 코드 품질은 그다음 순서로 2단계 검토하는 워크플로입니다. 이 스킬의 진짜 가치는 단순히 “에이전트를 더 많이 쓰는 것”이 아니라, 각 작업자에게 해당 작업, 요구사항, 그리고 필요한 로컬 코드 맥락만 의도적으로 분리해 전달한다는 데 있습니다.

이 스킬이 가장 잘 맞는 경우

이 subagent-driven-development skill은 이미 계획이 있고, 그것을 현재 세션 안에서 신뢰할 수 있는 구현으로 바꿔야 하는 사람에게 가장 잘 맞습니다. 특히 다음과 같은 경우에 적합합니다.

• 작업들이 대체로 서로 독립적일 때
• coordinator agent가 오케스트레이션에만 집중하길 원할 때
• 요구사항 이탈과 성의 없는 코드 둘 다 잡아내고 싶을 때
• 일회성 코딩 프롬프트가 아니라 반복 가능한 리뷰 루프가 필요할 때

해결하려는 핵심 문제

사용자들이 subagent-driven-development for Agent Orchestration을 찾는 이유는, 일반적인 “이 계획을 구현해줘” 프롬프트가 일정한 방식으로 실패하기 시작하기 때문입니다. 예를 들어 에이전트가 여러 작업을 섞어 처리하거나, 제약을 잊거나, 과하게 만들거나, 겉보기엔 그럴듯하지만 실제 명세는 놓친 코드를 내놓는 경우입니다. 이 스킬은 이런 실패를 줄이기 위해, 인계와 검토를 엄격하게 분리한 실행 패턴을 제공합니다.

일반적인 프롬프트와 무엇이 다른가

핵심 차이는 매우 실무적입니다.

• 작업마다 새로운 subagent 사용: 긴 대화 이력을 끌고 가는 단일 에이전트 대신, 노이즈 없는 새 컨텍스트로 시작
• 명시적인 작업 패킷 제공: 여러 파일에 흩어진 요구사항을 스스로 추론하게 두지 않고, 작업 전문을 그대로 붙여 넣음
• 코딩 전 질문 필수화: 애매한 요구사항이 구현 전에 드러나게 함
• 2단계 리뷰 분리: “명세대로 만들었는가?”와 “코드가 좋은가?”를 별개로 판단

이 분리는 중요합니다. 많은 팀이 범위 검증보다 코드 품질 검토를 먼저 하는데, 그러면 과도하게 만들었거나 덜 만든 결과를 놓치기 쉬워집니다.

오히려 선택하면 안 되는 경우

아직 구체적인 구현 계획이 없는 상태라면 subagent-driven-development로 시작하지 마세요. 작업들이 서로 강하게 얽혀 있거나, 현재 세션이 아니라 별도 병렬 실행 흐름으로 보내야 할 일이라면 더더욱 그렇습니다. 이런 경우에는 보통 먼저 계획 수립을 하거나, 다른 실행용 스킬을 선택하는 편이 낫습니다.

subagent-driven-development 스킬 사용 방법

subagent-driven-development 스킬 설치

이 저장소의 스킬을 Skills CLI로 설치한다면 다음 명령을 사용하세요.

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

설치 후 첫 실행 전에, 설치된 스킬 문서와 함께 제공되는 프롬프트 템플릿들을 먼저 열어보는 것이 좋습니다.

먼저 읽어야 할 파일

빠르게 익히려면 다음 순서로 읽으세요.

1. SKILL.md
2. implementer-prompt.md
3. spec-reviewer-prompt.md
4. code-quality-reviewer-prompt.md

이 순서대로 보면 먼저 전체 워크플로를 이해하고, 그다음 구현 담당자와 두 단계 리뷰어가 실제로 어떤 형태의 프롬프트를 받는지 파악할 수 있습니다.

시작 전에 호출 패턴부터 이해하기

실전에서 subagent-driven-development usage는 마법 같은 단일 명령이 아닙니다. coordinator 역할을 직접 수행하는 방식으로 써야 합니다.

1. 계획에서 작업 하나를 꺼낸다
2. 범위를 엄격히 제한한 프롬프트로 새 implementer subagent를 보낸다
3. 결과 보고를 반드시 받는다
4. 실제 코드를 기준으로 spec reviewer를 돌린다
5. spec을 통과했을 때만 code quality reviewer를 돌린다
6. 수락, 수정 요청, 또는 재할당을 결정한다

이 리뷰 게이트를 건너뛰면, 설계 의도대로 subagent-driven-development를 쓰고 있다고 보기 어렵습니다.

이 스킬이 필요로 하는 입력

어떤 subagent를 보내기 전에 다음 입력을 준비하세요.

• 계획에서 가져온 정확한 작업 텍스트
• acceptance criteria 또는 요구사항
• 관련 아키텍처 맥락
• 작업 디렉터리 또는 repo 범위
• 의존성이나 선행 순서 메모
• 리뷰 diff 기준이 될 baseline commit 또는 SHA
• 추적을 위한 task number와 task name

원본 템플릿의 뉘앙스는 분명합니다. subagent에게 “plan file 읽고 알아서 해”라고 시키는 게 아니라, 작업 전문 전체를 프롬프트에 직접 붙여 넣는 방식을 전제로 합니다.

거친 목표를 강한 implementer 프롬프트로 바꾸기

약한 프롬프트는 이렇게 생겼습니다.

• “Implement task 4 from the plan.”

반면 더 강한 subagent-driven-development guide 프롬프트에는 보통 다음이 들어갑니다.

• 작업 제목과 번호
• 작업 전문 전체
• 이 작업이 필요한 이유
• repo 안에서 어디를 수정해야 하는지
• 파일 구조 관련 제약
• 테스트가 필요한지 여부
• 가정이 필요해질 경우 어떻게 할지
• 코딩 전에 질문하라는 요구

이 형태가 중요한 이유는, 이 스킬이 repo 전체를 자율적으로 해석하게 하는 방식이 아니라 통제된 컨텍스트 전달을 중심으로 설계되어 있기 때문입니다.

더 나은 작업 패킷 예시

implementer를 보낼 때는 다음과 같은 구조를 쓰는 것이 좋습니다.

• Task N: [name]
• FULL TEXT of task from plan
• Context: where this fits, dependencies, architecture
• Work from: [directory]
• Requirements: implement exactly what is specified
• If anything is unclear, ask before starting
• Write tests if required by task
• Commit, self-review, and report back

작업자에게 넓게 탐색해보라고 던지는 것보다 이 방식이 더 안정적입니다. subagent-driven-development에서는 assignment를 잘 포장하는 책임이 coordinator에게 있다고 보기 때문입니다.

품질 리뷰보다 spec 리뷰를 먼저 해야 하는 이유

이 부분은 subagent-driven-development install을 검토할 때 가장 가치가 큰 판단 포인트 중 하나입니다. 순서에는 분명한 이유가 있습니다.

먼저 spec reviewer를 돌려서 다음을 확인합니다.

• 요청한 내용이 실제로 구현되었는가?
• 요구사항을 빠뜨리지는 않았는가?
• 요청하지 않은 작업을 덧붙이진 않았는가?
• 작업을 잘못 이해하진 않았는가?

그다음에야 code quality reviewer를 돌려 유지보수성, 분해 방식, 파일 책임 분리, 변경의 형태를 봐야 합니다. 순서를 뒤집으면, 겉보기에 잘 짜인 코드가 범위 오류를 가려버릴 수 있습니다.

spec reviewer를 제대로 활용하는 방법

spec-reviewer-prompt.md 템플릿은 꽤 단도직입적입니다. implementer의 보고를 그대로 믿지 말고, 실제 코드를 줄 단위로 대조하라고 지시합니다. 템플릿을 변형하더라도 그 톤은 유지하는 편이 좋습니다. reviewer에게 필요한 것은 다음입니다.

• 전체 작업 요구사항
• implementer가 주장한 결과
• 변경된 코드에 대한 접근

핵심은 예의 바른 확인이 아니라, 독립적인 검증입니다.

code quality reviewer를 제대로 활용하는 방법

여기서의 코드 품질 리뷰는 일반적인 스타일 단속이 아닙니다. 이 스킬에서는 특히 다음을 봅니다.

• 파일 하나당 책임이 명확한가
• 인터페이스가 잘 정의되어 있는가
• 이해 가능한 단위로 잘 분해되어 있는가
• 계획된 파일 구조와 맞는가
• 이번 작업 때문에 새 파일이 과하게 커졌거나 기존 파일이 비대해졌는가

마지막 항목이 특히 유용한 이유는, subagent가 문제를 해결하면서 한 번의 변경에 너무 많은 것을 욱여넣는 경우가 흔하기 때문입니다.

실제 repo 안에서의 권장 워크플로

실무적인 subagent-driven-development usage 루프는 보통 이렇게 굴러갑니다.

1. 다음 독립 작업을 선택한다
2. 현재 commit을 baseline으로 기록한다
3. 작업 전문 전체를 넣어 implementer를 보낸다
4. 요약 보고와 변경 파일 목록을 받는다
5. 요구사항과 실제 코드를 기준으로 spec review를 돌린다
6. spec에 실패하면 구체적인 누락/오해를 implementer에게 돌려보낸다
7. spec을 통과하면 code quality review를 돌린다
8. 품질에서 실패하면 범위를 좁힌 수정 요청을 한다
9. 병합하거나 다음 작업으로 넘어간다

이 흐름을 쓰면 순서와 승인 권한을 coordinator가 계속 쥘 수 있습니다.

결과 품질에 영향을 주는 제약

이 스킬은 다음 경계를 지킬 때 가장 잘 작동합니다.

• 얽힌 작업보다 독립 작업이 훨씬 낫다
• 추론된 요구사항보다 명시된 요구사항이 낫다
• “둘러보고 알아서 판단”보다 좁은 repo 범위가 낫다
• 큰 다기능 배치보다 짧은 작업 루프가 낫다
• 말없이 추측하는 것보다 명확한 escalation rule이 낫다

subagent 하나가 코드베이스 전체의 여러 움직이는 부분을 동시에 조율해야 한다면, 그 작업은 이 워크플로에 비해 너무 넓을 가능성이 큽니다.

흔한 도입 실수

가장 흔한 실수는 subagent-driven-development skill이라는 이름만 붙여놓고, 실제 프롬프트는 여전히 느슨하게 쓰는 것입니다. 이 워크플로는 컨텍스트를 꼼꼼하게 포장하고, 리뷰 순서를 강제할 때에만 비용 대비 효과가 납니다. 그렇지 않으면 오케스트레이션 오버헤드만 늘고 품질 이득은 거의 얻지 못합니다.

subagent-driven-development 스킬 FAQ

subagent-driven-development는 초보자에게도 괜찮을까?

네, 이미 무엇을 만들어야 하는지는 알고 있다면 괜찮습니다. 워크플로가 명시적이고, 제공된 프롬프트 템플릿도 시행착오를 줄여줍니다. 다만 이 스킬은 계획 수립을 대신해주지 않습니다. 아직 구현 계획이 선명하지 않은 초보자라면, 이 스킬이 작업 정의가 이미 존재한다고 가정하기 때문에 오히려 어려움을 겪을 수 있습니다.

언제 subagent-driven-development를 쓰지 말아야 하나?

다음 상황이라면 subagent-driven-development는 건너뛰는 편이 좋습니다.

• 아직 문제를 탐색 중일 때
• 작업들이 깊게 상호의존적일 때
• 요구사항이 계속 바뀌고 있을 때
• 한 사람 또는 한 에이전트가 시스템 전체를 계속 이어서 사고해야 할 때

이건 발견(discovery) 패턴이 아니라, 실행(execution) 패턴입니다.

에이전트 하나에게 전부 코딩하라고 하는 것과 뭐가 다른가?

긴 단일 프롬프트는 계획, 구현, 검증, 리뷰를 한 컨텍스트 창 안에 다 섞어버리는 경우가 많습니다. 반면 이 스킬은 그 역할들을 분리합니다. 그 결과 보통 집중도가 올라가고, 요구사항 이탈을 더 쉽게 잡아낼 수 있으며, coordinator의 컨텍스트도 코드 생성이 아니라 오케스트레이션에 유지할 수 있습니다.

이 스킬은 특별한 도구가 필요한가?

아니요. 이 스킬 폴더에는 별도의 특수 스크립트가 묶여 있지 않습니다. 저장소는 자동화 코드가 아니라 markdown 프롬프트 템플릿을 제공합니다. 따라서 subagent를 보낼 수 있고 코드 리뷰 작업을 돌릴 수 있는 환경이라면 어디서든 같은 패턴을 적용할 수 있습니다.

subagent-driven-development는 큰 프로젝트에서만 유효한가?

아니요. 작은 변경에도 쓸 수 있습니다. 다만 독립 작업이 여러 개 있는 계획이 있고, 요구사항 누락 비용이 리뷰 오버헤드를 감수할 만큼 큰 상황에서 가장 가치가 큽니다.

설치 전에 repo에서 무엇을 가장 중점적으로 봐야 하나?

이 스킬에서는 SKILL.md와 세 개의 프롬프트 템플릿이 가장 중요한 판단 근거입니다. 숨은 역할을 하는 helper script나 resource folder는 없기 때문에, 설치 여부는 결국 프롬프트 구조와 리뷰 규율이 현재 팀의 코드 출하 방식과 맞는지를 기준으로 보는 것이 맞습니다.

subagent-driven-development 스킬을 더 잘 쓰는 방법

프롬프트를 길게 쓰기보다 작업 패킷을 더 정확하게 만들기

subagent-driven-development skill의 결과를 개선하려면 장황함보다 정확도를 높이세요. 특히 다음 정보가 효과적입니다.

• 정확한 acceptance criteria
• 명시적인 non-goals
• 이 작업에만 관련된 아키텍처 메모
• 파일 또는 디렉터리 경계
• 기대 동작의 예시
• 테스트 기대치

이런 정보는 implementer의 초점을 유지시켜 주고, spec reviewer가 이탈 여부를 더 쉽게 잡게 해줍니다.

작업 경계를 더 날카롭게 나누기

실패의 상당수는 작업 분할이 흐릿해서 발생합니다. 하나의 subagent가 여러 변수를 동시에 조율하고, 아키텍처를 결정하고, 요구사항까지 추론해야 한다면 작업을 더 쪼개야 합니다. 좋은 작업은 “요청한 것만 정확히 구현했는가?”를 비교적 쉽게 검증할 수 있을 정도로 좁아야 합니다.

먼저 질문하게 하는 단계를 유지하기

implementer 템플릿은 시작 전에 질문하고, 구현 중 예상 밖의 상황이 나오면 다시 질문하라고 명시합니다. 이 동작을 유지하세요. 확인 질문을 억누르면 속도는 빨라 보여도 신뢰도는 크게 떨어지고, 결국 이 스킬을 쓰는 이유 자체가 사라집니다.

더 강한 비교 입력으로 리뷰 품질 높이기

spec reviewer에게는 다음을 제공하세요.

• 전체 요구사항 텍스트
• implementer 보고서
• 변경 파일 또는 diff 범위
• 명시적인 제외 항목이 있다면 그것까지

code quality reviewer에게는 다음을 제공하세요.

• BASE_SHA
• HEAD_SHA
• 작업 요약
• 관련 계획 섹션

이처럼 비교 기준점을 구체적으로 주면, 리뷰가 단순한 의견 개진에 그치지 않습니다.

자주 발생하는 실패 패턴 살피기

가장 흔한 subagent-driven-development for Agent Orchestration 문제는 다음과 같습니다.

• implementer가 불필요한 기능을 추론해 추가한다
• 작업 패킷에서 핵심 제약 하나가 빠진다
• reviewer가 implementer 요약을 너무 쉽게 믿는다
• spec review보다 code quality review가 먼저 실행된다
• 작업이 너무 커서 깔끔하게 검증할 수 없다
• 파일 비대화가 방치된다

이 문제들은 모두, 더 나은 작업 패키징과 더 엄격한 게이트 운영으로 예방 가능합니다.

첫 결과가 약해도 바로 처음부터 다시 시작하지 않기

첫 번째 결과가 기대에 못 미친다면 곧바로 전부 리셋하지 마세요. 먼저 어느 층위에서 실패했는지 구분하는 것이 낫습니다.

• spec failure: 요구사항이 अस्पष्ट했거나, 빠졌거나, 과하게 구현됨
• quality failure: 분해 방식, 유지보수성, 파일 구조에 문제 있음
• coordination failure: 작업 분할 또는 컨텍스트 패키징이 잘못됨

그다음 실패한 층위만 수정하세요. 그래야 워크플로가 비효율적으로 무거워지지 않습니다.

파일 구조 가이드를 더 구체적으로 만들기

품질 템플릿에서 특히 유용한 포인트 하나는, 구현이 계획된 파일 구조를 따랐는지, 새로 만든 파일이 처음부터 너무 커지지 않았는지를 확인한다는 점입니다. 유지보수성을 중요하게 본다면, 리뷰어가 나중에 잡아주길 기대하기보다 작업 패킷 단계에서 의도한 파일 경계를 미리 적어두는 편이 좋습니다.

재사용 가능한 로컬 체크리스트 만들기

subagent-driven-development를 자주 쓸 예정이라면, 짧은 coordinator 체크리스트를 하나 두세요.

• plan exists
• task is independent
• full task pasted
• constraints included
• baseline SHA captured
• implementer asked to clarify before coding
• spec review completed
• quality review completed

이런 작은 습관이, 프롬프트를 더 길게 쓰는 것보다 일관성을 훨씬 잘 높여줍니다.

자신의 워크플로에 맞게 스킬 다듬기

기본 스킬은 의도적으로 가볍게 설계되어 있습니다. 실제 환경에서 더 잘 맞게 만들려면, 프롬프트 템플릿을 팀의 스택과 리뷰 기준에 맞춰 손보세요.

• 테스트 명령을 추가하기
• repo 고유의 아키텍처 규칙을 넣기
• 무엇을 over-engineering으로 볼지 정의하기
• 선호하는 보고 형식을 지정하기
• 코드베이스에서 자주 나오는 실패 패턴을 포함하기

이런 식의 현장 맞춤 조정이, 이론을 더 붙이는 것보다 보통 subagent-driven-development usage를 훨씬 더 실질적으로 개선합니다.