Claude Code Subagent vs 구조화된 태스크 분할: 언제 무엇을 사용할 것인가

구조화된 태스크 분할 실전

답이 "별도 에이전트"일 때, feature를 서로 방해하지 않고 병렬 실행할 수 있는 태스크로 분해할 방법이 필요하다.

분해 프로세스:

1. 종속성 그래프 식별. 무엇이든 나누기 전에 무엇이 무엇에 의존하는지 매핑한다:

Feature: User profile page with activity feed

- API endpoint: GET /users/:id/profile     (no deps)
- API endpoint: GET /users/:id/activity     (no deps)
- React component: ProfileHeader            (depends on profile API)
- React component: ActivityFeed             (depends on activity API)
- Integration test: profile page end-to-end (depends on all above)

두 API 엔드포인트는 종속성이 없다. 병렬 실행 가능하다. 두 React 컴포넌트는 각각 하나의 API에 의존한다. 통합 테스트는 모든 것에 의존한다.

2. 소유권 경계 설정. 각 태스크에 파일 범위를 부여한다. Profile API 에이전트는 server/routes/profile.ts와 server/services/profile.ts를 소유한다. Activity API 에이전트는 server/routes/activity.ts와 server/services/activity.ts를 소유한다. 어느 쪽도 상대의 파일을 건드리지 않는다. 공유 유틸리티의 수정이 필요하면, 한 에이전트가 변경을 만들고 다른 에이전트가 기다린다.

3. 태스크별 수락 기준 정의. 각 태스크에는 다른 태스크를 보지 않고 검증할 수 있는 명확한 "완료" 조건이 필요하다. "Profile API가 올바른 형태로 200을 반환한다"는 검증 가능하다. "프로필 페이지가 작동한다"는 불가능하다. 통합에 의존하기 때문이다.

4. 핸드오프 아티팩트 지정. 하류 에이전트가 상류 에이전트로부터 무엇이 필요한가? 보통: 알려진 브랜치의 commit된 코드, 상태 업데이트, 인터페이스 계약을 설명하는 코멘트(API 형태, 컴포넌트 props, 함수 시그니처).

이 분해는 모호한 "프로필 페이지 만들기"를 명시적 종속성과 검증 기준을 가진 다섯 개의 개별 태스크로 변환한다. 각 태스크는 필요한 컨텍스트만을 가진 에이전트에 할당될 수 있다.

Beads를 활용한 구조화된 분할

여기서 실제 태스크 시스템을 갖는 것이 중요해진다. 다섯 개의 병렬 태스크를 포스트잇과 터미널 출력으로 추적할 수 없다.

beads는 로컬 퍼스트 이슈 트래커로, 이 분해를 네이티브로 모델링한다. Epic이 feature를 나타낸다. Children이 서브태스크를 나타낸다. Dependencies가 전제 조건이 완료되기 전에 에이전트가 작업을 시작하는 것을 방지한다.

실전에서 분할은 이렇게 보인다:

# Create the epic
bd create --title "User profile page with activity feed" \
  --type epic --priority p2

# Create subtasks as children
bd create --title "GET /users/:id/profile endpoint" \
  --parent bb-epic1 --type task --priority p2

bd create --title "GET /users/:id/activity endpoint" \
  --parent bb-epic1 --type task --priority p2

bd create --title "ProfileHeader React component" \
  --parent bb-epic1 --type task --priority p2 \
  --deps bb-profile-api

bd create --title "ActivityFeed React component" \
  --parent bb-epic1 --type task --priority p2 \
  --deps bb-activity-api

bd create --title "Profile page integration test" \
  --parent bb-epic1 --type task --priority p2 \
  --deps bb-profile-header,bb-activity-feed

구조가 명시적이다. bd show bb-profile-header를 실행하는 에이전트는 profile API 태스크에 의존한다는 것을 본다. 그 태스크가 아직 완료되지 않았으면, 에이전트는 시작하지 말아야 한다는 것을 안다. API 에이전트가 완료하고 태스크를 완료로 표시하면, 프론트엔드 에이전트의 종속성이 해제된다.

에이전트 워크플로우는 예측 가능한 루프를 따른다:

# Agent claims the task
bd update bb-profile-api --claim --actor eng1

# Agent comments its plan before writing code
bd comments add bb-profile-api --author eng1 "PLAN:
1. Create route handler at server/routes/profile.ts
2. Add service layer at server/services/profile.ts
3. Return shape: { id, name, avatar, bio, joinedAt }
4. Test: curl localhost:3000/users/1/profile returns 200"

# Agent implements, tests, commits
# ...

# Agent marks done with verification steps
bd comments add bb-profile-api --author eng1 "DONE: Profile endpoint implemented.
Returns { id, name, avatar, bio, joinedAt }.
Verified: curl returns 200 with correct shape.
Commit: abc1234"

bd update bb-profile-api --status ready_for_qa

모든 단계가 기록된다. QA 에이전트는 DONE 코멘트를 읽고 정확히 어떻게 검증할지 안다. 하류 에이전트는 PLAN 코멘트를 읽고 코드가 완성되기 전에 API 계약을 안다.

이것은 프로세스를 위한 오버헤드가 아니다. 다섯 개의 병렬 에이전트가 다섯 개의 호환되지 않는 코드 조각을 생산하는 것을 방지하는 최소한의 구조다.

기본 선택

수개월간 프로덕션 작업에서 병렬 에이전트를 운영한 후, 따르는 결정 트리가 이것이다:

Subagent로 시작하는 경우:

• 태스크가 리서치 또는 탐색(검색, 읽기, 비교)일 때
• 결과가 단일 행동으로 수렴해야 할 때
• 전체 작업이 하나의 컨텍스트 윈도우에 들어갈 때
• 각 병렬 유닛의 독립적 검증이 불필요할 때

별도 태스크로 전환하는 경우:

• 작업의 다른 부분이 다른 파일을 건드릴 때
• 각 조각이 자체 수락 기준을 가질 때
• QA가 조각을 독립적으로 검증하기를 원할 때
• 작업이 충분히 길어서 한 조각이 다른 것보다 몇 시간 먼저 끝날 수 있을 때
• 에이전트가 다른 컨텍스트를 필요로 할 때 (프론트엔드 에이전트에게 데이터베이스 내부 구조는 불필요)

복잡한 feature를 위한 하이브리드 접근: 리서치 및 계획 단계에 subagent를 사용하고(분산, 정보 수집, 계획 종합), 구현을 독립 에이전트용 별도 태스크로 분해한다. Spec-driven development 워크플로우가 여기에 자연스럽게 맞는다: subagent를 가진 단일 에이전트가 spec을 작성하고, spec이 멀티 에이전트 플릿용 태스크로 분해된다.

분할 시각화

다섯 개에서 열 개의 구조화된 태스크에 종속성이 있으면, 터미널에서 진행 상황을 추적하기 어려워진다. bd list는 플랫 리스트를 보여준다. 어떤 태스크가 차단되었는지, 어떤 것이 시작 준비가 되었는지, epic이 얼마나 진행되었는지 보여주지 않는다.

이것이 Beadbox가 해결하는 문제다. 같은 beads 데이터베이스를 읽고 진행 표시기, 종속성 관계, 에이전트 할당이 있는 epic 트리를 렌더링한다. 어떤 서브태스크가 완료되었고, 어떤 것이 전제 조건에 차단되어 있고, 어떤 것이 에이전트가 가져갈 준비가 되었는지 볼 수 있다. --deps으로 지정한 종속성 그래프가 병렬 작업의 시각적 맵이 된다.

에이전트가 태스크를 완료하고 상태를 업데이트하면, Beadbox가 실시간으로 변경을 반영한다. 새로고침 없음, bd list 재실행 없음. 트리가 업데이트되고, 진행 바가 움직이고, 차단된 태스크가 종속성 해결과 함께 차단 해제된다.

같은 데이터. 단지 보이는 것.

이런 워크플로우를 구축하고 있다면, GitHub에서 Beadbox에 스타를 남겨주세요.