콘텐츠로 이동

에이전트 흐름

pilot은 명시적으로 호출되는 4개의 agent를 통해 하나의 feature 개발 cycle을 진행합니다. 모든 agent는 orchestrate-load.py로 로드된 동일한 context를 공유하지만, 각자 고유의 역할과 관점을 가집니다.

흐름 시퀀스

sequenceDiagram
    autonumber
    actor User
    participant Planner as @pilot-planner
(설계)
    participant Critic as @pilot-planner-critic
(반론)
    participant Generator as @pilot-generator
(구현)
    participant Evaluator as @pilot-evaluator
(검증)

    User->>Planner: 호출
    Planner-->>User: plan.md 작성 + 확인 요청
    User->>Critic: 호출 (선택, 권장)
    Critic-->>User: .plan.critic.md (챌린지 리스트)
    Note over User: 의장 역할 — C# 채택 결정
    User->>Planner: 재호출 (수정)
    Planner-->>User: plan.md 갱신 + 합의 표 채움
    User->>Generator: 호출
    Generator-->>User: 구현 + sanity check
    User->>Evaluator: 호출
    Evaluator-->>User: VERIFICATION REPORT
    Note over Evaluator: status: READY → 사이클 종료

명시적 호출은 @agent_name 형태로 수행되며, 사용자는 각 phase 사이에서 plan, critic 피드백, 구현 결과를 검토하고 의사결정을 내릴 수 있습니다.

에이전트별 역할 분리

동일한 context를 서로 다른 시각에서 검증한다는 점이 핵심입니다.

에이전트 기본 자세 금지 사항
Planner 한 발 물러나 영향 범위와 의존성을 먼저 살핀다. 한 번에 3단계를 초과하는 계획 수립 / 영향 받는 파일 목록이 비어 있는 단계 작성 금지
Planner-Critic 전제 조건, 범위, edge case, 대안적 접근법 등을 의심하고 검증한다. code나 plan 직접 수정 금지 / 모호하고 일반적인 지적 지양 / 개인 선호를 blocking 이슈로 격상 금지
Generator 기존 code 패턴을 우선적으로 재사용한다. 불필요한 추상화는 지양한다. 기존 패턴 대신 새로운 helper나 추상화 계층 임의 신설 금지 / 요구사항 범위를 벗어난 오버엔지니어링 금지
Evaluator 명확한 검증 데이터(증거) 없이는 통과시키지 않는다. 반려에 타협하지 않는다. 구현자의 의도를 임의로 추정해 통과시키는 행위 금지 / 증거 확인 없이 status: READY를 부여하는 행위 금지

Critic의 1.5-pass 구조

critic은 작성된 plan.md를 검토하되, 이를 직접 수정하지 않습니다. 피드백은 .plan.critic.md에 기록되며, 이후 planner가 재호출되어 사용자가 수용 여부를 결정한 피드백을 바탕으로 plan.md를 업데이트하고 합의 표(accepted | rejected | deferred)를 작성합니다.

이러한 역할 분리를 통해 얻을 수 있는 이점은 다음과 같습니다:

  • 사용자가 중재자(의장) 역할 수행 — AI 간의 자동 토론에 의존하지 않고 사용자가 직접 의사를 결정합니다.
  • 의사결정 이력 보존 — 어떤 피드백이 어떻게 처리되었는지가 git diff 기록으로 명확히 남습니다.
  • 수렴 신호 제공 — 동일한 피드백이 3 round 이상 반복된다면 plan의 문제가 아니라 요구사항 자체가 모호하다는 신호입니다. 이때 사용자는 상황을 인지하고 features/NN-*.md 파일의 요구사항을 구체화해야 합니다.

pilot-code-review와의 책임 경계

@pilot-code-review는 위 cycle 외부에 존재하는 독립된 agent입니다:

에이전트 검토 대상 호출 시점
@pilot-planner-critic 작성된 계획 (plan.md) planner 완료 직후, generator 실행 전
@pilot-code-review 작성된 코드 (git diff) evaluator 검증 완료 후, PR(Pull Request) 생성 전

두 agent 모두 비판적인 review 역할을 수행하지만, 검토 대상이 다릅니다.

호출 순서 제약

  • generator를 호출하기 전에 plan.md가 반드시 존재해야 합니다 (실행 시 plan-validate.py가 형식을 검증합니다).
  • evaluator를 호출하기 전에 generator의 구현 작업이 완료되어야 합니다.
  • critic 단계는 선택 사항입니다 — 단순한(trivial) 수정 시에는 생략해도 무방합니다.

자동화된 pipeline이 아닌 각 phase 사이에 사용자가 유연하게 개입할 수 있습니다. 진행 방향이 잘못되었다면 즉시 중단하고 설정을 조정할 수 있습니다.

예외 — autopilot (감독형 자율 모드)

위 수동 흐름이 기본이지만, 저위험·소규모 feature 에서는 4-에이전트 호출을 매번 직접 하는 마찰이 큽니다. /pilot:autopilot NN 은 이미 명세가 존재하는 단일 feature 에 한해 planner → critic → generator → evaluator 를 자동 순차 진행하는 opt-in 예외 모드입니다.

자동이라고 해서 사람을 흐름에서 배제하지 않습니다 — 위험 신호(hard-stop)에 걸리면 즉시 멈추고 제어를 사용자에게 반환합니다:

hard-stop 신호 의미
plan-validate 실패 plan.md 형식 계약 위반 — generator 로 넘기지 않음
critic blocking 챌린지 blocking 은 auto-accept 하지 않음 — 사람 판단 필요
재시도 소진 evaluator NOT_READY 가 generator 재진입 1회 후에도 지속
신호 파싱 실패 critic·evaluator 산출물을 신뢰성 있게 읽지 못함 — 추측 없이 멈춤

핵심 설계는 오케스트레이터가 도메인 판단을 하지 않는다는 것입니다. "이 챌린지가 타당한가"는 critic·planner 가, "요구사항을 충족했나"는 evaluator 가 판단하고, autopilot 은 그들이 내놓은 신호(enum)만 읽어 다음 단계로 전이합니다. 자동 모드에서도 critic 은 항상 실행되며, suggestion/nit 만 있을 때만 planner 가 자동 반영하고 blocking 이 하나라도 있으면 멈춥니다. 모든 자동 결정은 features/NN-{slug}.auto.md 감사 로그에 남아 사후 검증이 가능합니다.

상세 절차·재개 동작은 Reference → /autopilot 참조.

다음 단계