리뷰어 에이전트 디스패치

이 가이드에서는 리뷰어 에이전트를 디스패치해 풀 리퀘스트를 리뷰하도록 하는 방법을 설명합니다.

PR 뷰에서

1. PR을 열고 개요 탭으로 이동합니다
2. ⋯ 오버플로 메뉴를 열고 AI에게 물어보기를 선택합니다

이렇게 하면 기본 제공되는 pr_review 파이프라인이 시작됩니다. 이 파이프라인은 PR의 리뷰 스페이스를 열고, 워크스페이스의 리뷰 수준에 따라 리뷰어를 디스패치한 다음(기본값은 기본 제공되는 qa, architect, engineer 에이전트 세 명입니다), 리드 에이전트가 이를 통합하게 합니다. 이 경로에서는 역할을 직접 선택하지 않습니다. 어떤 역할이 실행되고 각 역할이 어떤 파일을 보는지 제어하려면, 아래의 MCP 도구나 파이프라인 단계를 사용하세요.

dispatch_reviewers MCP 도구 사용

기존 리뷰 스페이스 안에서 호출합니다:

dispatch_reviewers(
  space_id: "...",
  workspace_id: "...",
  reviewers: [
    {role: "reviewer"},
    {role: "security", scope: "src/auth/**"}
  ]
)

space_id, workspace_id, reviewers는 모두 필수입니다. 각 리뷰어 명세는 role과, 선택 사항인 파일 글롭 scope, 기본 브리프를 대체하는 prompt_override를 받습니다. 선택 사항인 concurrency(1–8)는 병렬 디스패치 수를 제한합니다. 생략하면 워크스페이스의 review_concurrency 설정이 적용됩니다(기본값 3, 설정 → 워크스페이스 → 일반에서 설정).

이 도구는 dispatched와 unmatched 목록과 함께 즉시 반환합니다. 디스패치된 모든 리뷰어는 참가자로 스페이스에 추가되고, 시스템 메시지로 알려지며, 자신의 브리프와 함께 디스패치됩니다. 발견 사항은 해당 스페이스에 review_node 메시지로 도착합니다.

파이프라인 단계에서

설정 → 워크스페이스 → 파이프라인 템플릿을 열고 템플릿을 연 다음:

1. 팔레트에서 Reviewer (prompt) 노드를 추가합니다
2. 디스패치할 에이전트를 선택하고 리뷰어 프롬프트를 작성합니다. 업스트림 출력에는 {{key}} 플레이스홀더를 사용합니다(예: {{repo_local_path}}, {{pr_number}})
3. 다운스트림 단계에서 발견 사항을 읽을 수 있도록 출력 키를 설정합니다(기본값 reviewer_findings)

이 단계는 에이전트를 디스패치하고 해당 실행이 끝날 때까지 중단됩니다. 그러면 엔진이 그 실행의 submit_output 페이로드를 노드의 출력 키 아래에 있는 파이프라인 상태로 가져옵니다. (팔레트 설명에는 이 단계가 complete_task 호출을 기다린다고 적혀 있지만, 그 도구는 존재하지 않습니다. 해당 문구는 무시하세요.)

여러 리뷰어 노드를 같은 업스트림 단계에 연결해 팬아웃한 다음, Consolidate (join) 노드로 그 출력을 통합하세요.

편집기는 숨겨진 터미널을 도달 가능한 모든 싱크에 다시 연결하므로, 기본 제공되는 Step 뒤에 추가한 노드도 실행됩니다. 같은 업스트림 단계에 연결된 팬아웃 노드는 병렬로 실행됩니다.

새 PR에서 자동 디스패치

리뷰 파이프라인이 스스로 실행되게 하려면:

1. 설정 → 워크스페이스 → 파이프라인 템플릿에서 템플릿을 엽니다
2. 노드 라이브러리의 트리거 섹션에서 PR 게시됨 또는 외부 PR 열림을 캔버스로 끌어다 놓습니다(또는 트리거 추가 고스트 타일에서 선택합니다)
3. 새 노드를 선택하고 인스펙터에서 활성화됨을 켠 다음, 템플릿을 활성화합니다

여기서 중요한 이벤트는 두 가지이며, 서로 바꿔 쓸 수 없습니다:

이벤트	발생 시점	페이로드 키
PullRequestPublished	Control Center를 통해 PR이 열림 — 작성 화면 또는 pr_lifecycle.publish를 호출하는 에이전트	pr_id, workspace_id, repo_owner, repo_name
ExternalPrDetected	PR 폴링 서비스가 GitHub에서 직접 열린 PR을 발견함	repo_owner, repo_name, pr_number, pr_title, author

github.com에서 열린 PR은 결코 PullRequestPublished를 발생시키지 않으므로, 그 이벤트에만 연결된 템플릿은 그 PR을 보지 못합니다. 또한 PullRequestPublished에는 pr_number가 없습니다. 스크립트나 프롬프트가 {{pr_number}}를 참조하는 단계는 ExternalPrDetected가, 또는 그 값을 제공하는 수동 실행이 입력을 공급해야 합니다.

체크포인트: 활성화한 뒤 파이프라인을 열고 다음으로 일치하는 PR에 대해 실행이 나타나는지 확인합니다. 비활성화된 템플릿은 트리거가 허공에 발화하게 만듭니다. 엔진은 비활성화된 템플릿을 거부하고 실행을 시작하지 않은 채 반환합니다.

역할이 에이전트와 매칭되는 방식

dispatch_reviewers는 워크스페이스의 모든 에이전트를 요청된 각 역할 레이블과 대소문자를 구분하지 않고 채점합니다:

일치 항목	점수
역할 레이블을 포함하는 스킬	+3
역할 레이블을 포함하는 제목	+2
역할 레이블을 포함하는 에이전트 이름	+1

점수는 누적되며 총점이 가장 높은 후보가 선택됩니다(동점이면 먼저 발견된 후보). 0점보다 높은 후보가 없으면 그 명세는 디스패치되지 않고 도구의 unmatched 목록으로 돌아옵니다. 따라서 아무도 매칭되지 않는 역할은 보고되며, 결코 조용히 건너뛰지 않습니다.

리뷰 스페이스

PR에는 리뷰어마다 하나가 아니라 정확히 하나의 리뷰 스페이스가 있습니다. 이 스페이스는 pr.ensureSpace가 멱등하게 생성하며, ReviewSpaceAssociation을 통해 PR에 연결되고, PR의 head ref를 기준으로 프로비저닝됩니다. 디스패치된 모든 리뷰어는 그 스페이스에 참여하고 자신의 review_node 발견 사항을 그곳에 게시합니다. 이것이 발견 사항을 서로 비교할 수 있게 하고, 리드 에이전트가 그 전반에서 합의에 도달할 수 있게 합니다.

디스패치 모니터링

디스패치된 각 리뷰어는 자체 AgentRunLog를 갖습니다. 진행 상황은 다음에서 확인합니다:

• 리뷰 스페이스 — 발견 사항이 실시간으로 들어옵니다
• PR의 리뷰 탭 — 리뷰 상태 표시줄과 판정을 보여줍니다
• 옵저버빌리티 → 실시간(/workspaces/:id/observability) — 실행별 상태, 실시간 경과 시간, 대화록 드로어, 종료 제어 기능을 갖춘 에이전트 로스터입니다. 여기에는 키보드 단축키가 없습니다. 사이드바 하단에서 열 수 있습니다.

관련 가이드

• AI 리뷰 사용
• PR 리뷰 및 병합
• 파이프라인 트리거 설정

관련 개념

• AI 리뷰
• 파이프라인과 자동화