⚡
★ 86.6k

Execution & Subagents

계획을 실행하는 것은 계획을 작성하는 것과는 다른 규율입니다. 이 챕터는 작업이 안전하게 실행되는 방법을 다룹니다.

Controller와 Subagent의 역할

계획 실행에는 두 종류의 에이전트가 있습니다:

Controller (조율자):

  • 계획을 소유합니다
  • 다음 실행할 작업을 결정합니다
  • subagents를 디스패치합니다
  • 결과를 검토하고 상태를 업데이트합니다
  • 차단 상태를 사용자에게 에스컬레이션합니다

Subagent (실행자):

  • 단 하나의 작업만 받습니다
  • 이전 작업에 대한 기억이 없습니다
  • 완료 후 결과와 상태를 반환합니다
  • 다음 작업에 대해 알지 못합니다

이 분리는 핵심입니다. Subagent는 격리된 환경에서 작동하기 때문에 이전 작업의 오류나 가정이 후속 작업으로 전파되지 않습니다.

CONTROLLER LOOP

┌──────────────────────────────────────────────────────────────┐
│                     CONTROLLER LOOP                          │
│                                                              │
│  1. Load plan → identify next PENDING task                   │
│  2. Dispatch subagent with: task description + relevant code │
│  3. Subagent completes task → returns result + status        │
│  4. Controller runs TWO-STAGE REVIEW                         │
│  5. Handle status:                                           │
│     DONE           → mark task complete, continue           │
│     DONE_WITH_CONCERNS → log, continue with note            │
│     NEEDS_CONTEXT  → gather context, re-dispatch            │
│     BLOCKED        → stop, escalate to user                 │
└──────────────────────────────────────────────────────────────┘

각 단계는 순서대로 진행됩니다. Controller는 현재 작업의 상태가 해결될 때까지 다음 작업으로 넘어가지 않습니다.

Context 격리의 세 가지 이점

이점 1: 오류 전파 방지

Subagent가 작업 3에서 잘못된 가정을 한다면, 그 가정은 subagent의 context에만 존재합니다. 작업 4를 위한 새 subagent는 이 오염된 context를 가지고 시작하지 않습니다.

context 격리가 없다면: 잘못된 가정이 모든 후속 작업에 영향을 미칩니다. context 격리가 있다면: 문제가 해당 작업에만 국한됩니다.

이점 2: 병렬 실행 지원

독립적인 작업들은 동시에 실행될 수 있습니다. 공유 context가 없기 때문에 두 subagent가 서로 다른 파일에서 동시에 작업해도 충돌이 없습니다.

이점 3: 검토 가능한 인계

각 subagent는 명확한 완료 보고서와 함께 종료됩니다. Controller는 이것을 검토합니다. 계획 전체에 걸쳐 흐릿하게 전달되는 대신, 작업 간 인계가 명시적이고 검사 가능합니다.

2단계 검토 (Two-Stage Review)

Subagent가 결과를 반환하면, controller는 두 단계로 나뉜 검토를 실행합니다:

Stage 1: Spec 준수 확인

"요청한 것을 만들었나요?"

  • 작업 설명의 모든 요구사항이 충족되었나요?
  • 완료 기준이 충족되었나요?
  • 아무것도 생략되지 않았나요?

Stage 2: 코드 품질 확인

"코드가 올바르고 유지보수 가능한가요?"

  • 코드가 프로젝트 컨벤션을 따르나요?
  • 엣지 케이스가 처리되었나요?
  • 새로운 테크니컬 데트가 도입되었나요?
  • 코드가 읽기 쉽고 명확한가요?

이 두 관심사는 별도로 평가됩니다. 코드는 spec을 충족하지만 품질이 낮을 수 있고, 또는 훌륭한 코드이지만 잘못된 것을 만들 수도 있습니다. 두 gate를 모두 통과해야 합니다.

Status 프로토콜

모든 subagent는 결과를 반환할 때 정확히 네 가지 상태 중 하나를 사용합니다:

DONE

작업이 완료되었습니다. 모든 요구사항이 충족되었습니다. 우려 사항이 없습니다.

Controller 동작: 작업을 완료로 표시하고 다음 작업으로 이동합니다.

DONE_WITH_CONCERNS

작업이 완료되었지만 Controller가 알아야 할 사항이 있습니다. 우려 사항이 작업 완료를 막지는 않지만 무시해서도 안 됩니다.

예시: "기능이 구현되었지만 error path가 테스트되지 않은 것을 발견했습니다."

Controller 동작: 우려 사항을 기록하고 계속 진행합니다. 우려 사항은 최종 검토에서 해결되어야 합니다.

NEEDS_CONTEXT

작업을 완료하기 위해 subagent에게 제공되지 않은 정보가 필요합니다.

예시: "이 작업은 인증 미들웨어가 어떻게 작동하는지 알아야 하는데, task description에 포함되어 있지 않습니다."

Controller 동작: 필요한 context를 수집하고 추가 정보와 함께 작업을 다시 디스패치합니다.

BLOCKED

작업을 진행할 수 없습니다. 사용자가 결정해야 하는 충돌이나 불명확한 사항이 있습니다.

예시: "이 작업은 기존 API를 변경해야 하는데, 그것은 다른 팀 시스템을 손상시킬 것입니다. 어떻게 진행해야 할지 불명확합니다."

Controller 동작: 실행을 중지하고 사용자에게 에스컬레이션합니다. 사용자 결정 없이 계속 진행하지 않습니다.

모델 선택

모든 작업이 같은 모델을 필요로 하지는 않습니다. 작업의 복잡성에 따라 적절한 모델을 선택하세요:

작업 유형권장 모델이유
기계적 작업 (간단한 리팩토링, 포맷팅, boilerplate)더 빠르고 저렴한 모델단순 변환에 강력한 reasoning이 필요하지 않음
통합 작업 (기능 구현, TDD 사이클)균형 잡힌 모델품질과 속도의 균형 필요
아키텍처 작업 (설계 결정, 복잡한 debugging)가장 강력한 모델복잡한 추론이 품질에 영향을 미침

병렬 실행

독립적인 작업들은 병렬로 실행될 수 있습니다. 계획에서 이것은 PARALLEL_GROUP 마커로 표시됩니다:

## PARALLEL_GROUP

### Task 6: Write tests for the user model
...

### Task 7: Write tests for the order model
...

### Task 8: Write tests for the product model
...

## END_PARALLEL_GROUP

PARALLEL_GROUP 내의 작업들은 독립적입니다 — 동일한 파일을 수정하지 않고, 서로의 출력에 의존하지 않습니다. Controller는 이들을 동시에 디스패치할 수 있습니다.

병렬 실행의 규칙:

  • 병렬 작업들은 동일한 파일을 수정해서는 안 됩니다
  • 병렬 작업들은 서로의 출력에 의존해서는 안 됩니다
  • 모든 병렬 작업이 완료된 후에만 그룹 이후의 작업이 시작될 수 있습니다

대안: /executing-plans Skill

직접 실행 대신 /executing-plans skill을 명시적으로 호출할 수 있습니다:

/executing-plans [계획 파일 경로]

이 skill은 CONTROLLER LOOP를 자동으로 관리하고, 상태 전환을 처리하며, 사용자를 위해 에스컬레이션이 필요한 시점을 식별합니다.

일반적인 실행 실패 패턴

실패 패턴발생 원인올바른 응답
Context 누출Subagent가 이전 작업의 정보를 참조함각 subagent를 완전히 새로운 context로 디스패치
상태 표류Controller가 작업 상태를 잘못 추적함각 상태 변경 후 계획 파일을 업데이트
무한 NEEDS_CONTEXTContext 수집이 문제를 해결하지 못함BLOCKED로 에스컬레이션하고 사용자에게 명확화 요청
검토 건너뛰기Controller가 2단계 검토 없이 진행함다음 작업 디스패치 전에 항상 두 단계를 실행
잘못된 병렬화종속적인 작업들이 동시에 실행됨병렬 실행 전에 종속성 그래프를 검증

실행은 가장 덜 창의적인 단계입니다 — 그리고 그게 포인트입니다. 계획에 이미 모든 결정이 있다면, 실행은 단순히 그것을 하나씩 완료하는 것입니다. 실행 중 창의성은 계획이 불완전하다는 신호입니다.