Chorus 플러그인을 연결하면, 이미 [AI-DLC 워크플로](/ko/guides/ai-dlc-workflow/)에서 익숙한 워크플로 위에
몇 가지 동작이 더해집니다. 적절한 순간에 독립적인 검토를 촉구하고, 수작업 기록 없이 에이전트 세션을
추적하며, 무인 에이전트가 할 수 있는 일을 제약합니다. 이 페이지는 그 동작들을 설명합니다. 수명 주기
단계나 런타임의 설치·실행·복구 방법은 반복하지 않습니다. 그것들은 각각
[AI-DLC 워크플로](/ko/guides/ai-dlc-workflow/), [Chorus 데몬 운영](/ko/guides/daemon-operations/),
[세션 중단과 재개](/ko/guides/session-recovery/), 그리고
[에이전트 플랫폼 참고 문서](/ko/reference/agents/)를 참고하세요.

## 검토자 서브에이전트

플러그인은 파이프라인의 세 지점에 독립적인 품질 관문을 더합니다. 각 지점에서 `PostToolUse` 훅이 실행되며,
**메인 에이전트**에게 전용 **읽기 전용 검토자 서브에이전트**를 생성하도록 촉구하는 리마인더를 주입합니다.
검토자는 **자동으로 실행되지 않습니다**. 메인 에이전트가 생성하고 런타임의 완료 대기 방식으로 기다린 뒤,
이번 라운드의 판정 댓글을 읽습니다. 완료된 검토는 `PASS`, `PASS WITH NOTES`, 또는 `FAIL` 판정을 게시합니다.

- `PASS` / `PASS WITH NOTES` — 작업은 계속됩니다. 메모는 참고용입니다.
- `FAIL` — 나열된 차단 요소를 먼저 고치고 작업을 재제출해야 다음으로 넘어갑니다.

검토자는 작업을 변경하지 않고 검사합니다. 제안 검토자는 `ls`, `rg`, `find`, `git log/show/diff`
같은 읽기 전용 셸 명령을 사용할 수 있으며, 경로가 없다고 보고하기 전에 반드시 확인해야 합니다. 파일 변경,
Git 쓰기 작업, 의존성 설치, 테스트/빌드 실행은 금지됩니다. 작업 검토자와 코드 검토자는 여기에 더해
프로젝트 자체의 테스트, 빌드, lint 명령도 실행할 수 있습니다. 이는 Kiro를 포함한 모든 환경에 해당하며,
Kiro에서는 차단 명령 목록이 파일 변경, Git 쓰기, 설치를 막습니다.

| 검토자 | 실행 시점 | 검토 대상 | 판정 게시 위치 |
| --- | --- | --- | --- |
| 제안 검토자 | `chorus_pm_submit_proposal` 이후 | 문서 완전성, 작업 세분성, 수락 기준과의 정합, 그리고 의존성 그래프 | 제안 |
| 작업 검토자 | `chorus_submit_for_verify` 이후 | 그 작업의 구현이 수락 기준과 제안 문서를 충족하는지, 그리고 해당하는 기준이 없어도 적용되는 기본 품질 점검: 정확성, 이미 있는 것의 재구현, 그 작업 자체 코드의 보안 허점, 실패할 수 없는 테스트, 필수 작업의 실패를 조용히 삼키는 처리 | 작업 |
| 코드 검토자 | 아이디어를 뿌리로 하는 제안의 마지막 작업이 검증될 때(`chorus_admin_verify_task`) | 그 아이디어의 모든 작업에 걸친 **집계** 변경 — 작업 간 통합, 아키텍처 이탈, 보안, 회귀, 기능 수준 커버리지 | 아이디어 |

코드 검토자는 출시 직전의 최종 관문입니다. 아이디어를 뿌리로 하는 제안의 *마지막* 작업이 검증될 때만
실행되며, 단일 작업이 아니라 기능 전체를 한 번에 검토합니다.

### 라운드를 넘어 발견 사항 추적하기

모든 발견 사항에는 고정된 ID가 붙습니다. 차단 요소는 `B<round>-<slug>`, 메모는 `N<round>-<slug>`이며,
round는 그 사항을 처음 보고한 라운드입니다(예: `B1-ac3-not-implemented`). ID는 바뀌지 않으므로, 3라운드
판정에 `B1-…` 줄이 있다면 그 문제가 두 번의 수정 시도를 버텨 냈다는 뜻입니다. 2라운드부터 검토자는 이전의 모든
발견 사항을 **Prior findings** 아래에 나열하고, 각각에 `fixed`, `still-open`, `not-verifiable` 세 상태 중 하나와
판단을 위해 다시 실행한 내용을 적습니다. 발견 사항을 닫는 것은 `fixed`뿐입니다. 아직 열려 있거나 다시 검증할
수 없었던 차단 요소가 하나라도 있으면 판정은 `FAIL`로 유지되며, 열린 메모 때문에 판정이 `PASS WITH NOTES`보다
나빠지는 일은 없습니다.

판정에는 길이 제한이 없으며, 차단 요소의 근거는 빠짐없이 적습니다. 그 대신 첫 라운드의 메모는 최대 다섯 개이고,
이후 라운드에서는 새 메모를 추가하지 않습니다. 그래서 각 댓글은 조치가 필요한 내용에 집중합니다.

### 이번 라운드의 판정 기다리기

Claude Code에서는 검토자의 완료 알림을 기다립니다. 포그라운드 실행을 요청해도 실행 결과 자체는 판정이
아닙니다. Codex는 네이티브 생성·대기 방식을 사용합니다. Pi에 포함된 `subagent` 도구는 검토자가 돌아올 때까지
블로킹합니다. 모든 런타임에서 이전 라운드가 아니라 **이번 생성 이후** 게시된 `VERDICT:` 댓글을 읽어야 합니다.

새 판정이 없으면 무응답과 명시적인 인계를 구분하세요.

- **명시적인 검토 거부나 라운드 상한 알림**: 중단하고 사람에게 결정을 넘깁니다. 다시 생성하거나 자체 검토로
  이 인계를 대체해서는 안 됩니다.
- **아무 응답도 없음**: 한 번만 재시도합니다. 재시도에서도 명시적인 거부가 있는지 확인하세요. 두 번째에도
  완전히 응답이 없을 때만 메인 에이전트가 읽기 전용 자체 검토를 수행하고 판정을 게시할 수 있습니다.
  무응답은 절대 통과가 아닙니다.

### 원래 의도와의 정합성 확인

세 검토자는 작업을 원본 아이디어의 의도, 즉 아이디어 본문, 사람이 답한 요구사항 구체화, 사람이 작성한 댓글과도
비교합니다. 에이전트의 댓글과 에이전트가 답한 요구사항 구체화는 감사용 문맥일 뿐, 범위 변경을 승인하는 근거가 아닙니다.

범위 추가, 요구사항 누락, 그리고 수락 기준은 통과하지만 원래 요구사항을 놓친 변경은 차단 요소입니다. 단, 근거로
제시된 사람의 댓글이나 답변, 또는 사람의 명시적인 재정의가 그 변경을 승인했다면 예외입니다. 제안 검토자는 계획을,
작업 검토자는 구현을, 코드 검토자는 기능 전체를 확인합니다.

### 검토자 켜기 또는 끄기

이 검토자들은 플러그인을 설치하거나 구성할 때 조정할 수 있는 `userConfig` 설정으로 제어됩니다. 각 검토자에는
켜기/끄기 토글(모두 기본 **켜짐**)과, 사람에게 에스컬레이션하기 전에 "검토-수정" 루프를 몇 번까지 돌릴지
제한하는 최대 라운드 상한이 있습니다.

| 설정 | 유형 | 기본값 | 효과 |
| --- | --- | --- | --- |
| `enableProposalReviewer` | boolean | `true` | 제안 제출 후 제안 검토자 생성을 촉구 |
| `enableTaskReviewer` | boolean | `true` | 작업을 검증 요청한 후 작업 검토자 생성을 촉구 |
| `enableCodeReviewer` | boolean | `true` | 아이디어의 마지막 작업이 검증된 후 코드 검토자 생성을 촉구 |
| `maxProposalReviewRounds` | number | `3` | 사람에게 에스컬레이션하기 전의 최대 제안 검토-수정 라운드 수(`0` = 무제한) |
| `maxTaskReviewRounds` | number | `3` | 에스컬레이션 전의 최대 작업 검토 라운드 수(`0` = 무제한) |
| `maxCodeReviewRounds` | number | `3` | 에스컬레이션 전의 최대 코드 검토 라운드 수(`0` = 무제한) |

어떤 검토자를 끄면 그 독립적인 품질 점검은 사라지지만 토큰 사용량은 줄어듭니다. 별도의 `enableOpenSpec`
토글이 OpenSpec 모드를 제어하며, 이는 별도 페이지에서 다룹니다.

:::caution[검토자 토글은 Claude Code에만 있음]
Claude Code와 Codex는 모두 세 검토자 전부를 탑재하고 동일한 세 검토 촉구를 보냅니다. Claude Code 전용인
것은 `userConfig` **설정 토글** — 위 표의 `enable*` 스위치와 라운드 상한 설정입니다. Codex에는
`userConfig`가 없으므로, Codex에서는 설치 시 토글이 아니라 스킬과 훅이 이 검토자들을 직접 제어합니다.
아래 [Codex의 차이점](#codex의-차이점)을 참고하세요. 토글의 차이를 어떤 검토자가 존재하는지의 차이로
잘못 읽지 마세요.
:::

## 세션 수명 주기 훅

두 번째 훅 그룹은 에이전트의 Chorus **세션**을 자동으로 관리합니다. 그래서 사용자도 에이전트도 세션을 직접
열거나, 하트비트를 보내거나, 닫을 필요가 없습니다. 이들은 판단이나 촉구 없이 스스로 실행됩니다.

- **`SessionStart`** — 연결성을 확인하고, 에이전트를 체크인하며, 플러그인이 미리 만들어 둔 세션이 있으면
  찾아냅니다.
- **`SubagentStart`** — 워커가 시작되기 전에 그 에이전트 유형 이름을 딴 Chorus 세션을 만들거나 재사용합니다. 같은 유형의 워커끼리 이 세션을 공유할 수 있습니다.
- **`SubagentStop`** — 종료하는 워커의 점유를 해제합니다. 작업 자동 체크아웃, 세션 종료, 조건을 충족하는 자동 검증은 그 세션을 공유하는 마지막 워커가 종료할 때까지 기다립니다.
- **하트비트와 리마인더** — 유휴 워커는 하트비트를 보내 오래 실행되는 동안 세션이 비활성으로 표시되지 않게
  합니다. `PostToolUse` 리마인더는 위에서 설명한 검토 지점에서 메인 에이전트를 촉구합니다.

이 훅들이 세션 수명 주기를 관장하므로, 에이전트는 스스로 세션을 만들거나 닫아서는 안 됩니다. 이
세션들이 실행되는 런타임 자체를 관리하는 방법(시작, 작업 디렉터리 선택, 중단, 재개)은
[Chorus 데몬 운영](/ko/guides/daemon-operations/)과
[세션 중단과 재개](/ko/guides/session-recovery/)를 참고하세요.

## 헤드리스 데몬 세션: 대화형 프롬프트 금지

에이전트가 [데몬](/ko/guides/daemon-operations/) 세션으로 무인 실행될 때는, 팝업에 답할 사람이 터미널
앞에 없습니다. 헤드리스 세션은 결정에 이르기 위해 대화형 프롬프트(예: `AskUserQuestion`)를 사용해서는 **안
됩니다** — 아무도 답할 수 없는 프롬프트는 실행 전체를 멈춰 세웁니다.

대신 에이전트는 모든 결정을 **Chorus를 통해** 되돌려 보내, 책임 있는 사람이 비동기로 응답할 수 있게 합니다.

- 작업이나 제안에 증거를 충분히 담은 **댓글**을 게시하고, 필요한 정확한 조치(예: 관리자 검증)를 적어 책임자를
  **@mention**합니다.
- 실시간 답변을 기다리며 막히는 대신, **요구사항 구체화**를 사용해 아이디어의 미해결 질문을 기록합니다.

이렇게 하면 감사 추적이 온전히 유지되고, 사람은 다음에 Chorus에 들어올 때 응답할 수 있으며, 세션은 아무도
볼 수 없는 프롬프트에서 기다리지 않아도 됩니다. 이 인계 방식은 세션이 대화형이든 헤드리스든 동일하게
적용되며, 다만 헤드리스인 경우에만 대화형 프롬프트가 불가능해질 뿐입니다.

## Codex의 차이점

Codex 플러그인은 이식판이지 완전한 복제본이 아닙니다. Codex는 Claude Code와 **같은 세 검토자**(제안·작업·코드
검토자)를 실행하며, 각각 제안 제출 후, 작업을 검증 요청한 후, 그리고 아이디어를 뿌리로 하는 제안의
마지막 작업이 검증된 후에 동일한 `PostToolUse` / 훅 촉구로 실행됩니다. 다른 점은 검토자 구성이 아니라
설정 방식과 생성 방식입니다.

- **`userConfig` 설정 토글이 없습니다.** Codex는 `enable*` 검토 스위치도 라운드 상한 설정도 노출하지 않습니다.
  검토 촉구는 Codex의 스킬과 훅이 직접 구동하므로, Claude Code처럼 설치 시에 끌 수 없습니다. 예를 들어
  코드 검토 관문은 기본으로 켜져 있고, 비활성화할 토글이 없습니다.
- **네이티브 생성.** 메인 에이전트는 Claude Code의 Agent Teams가 아니라 Codex 자체의 `spawn_agent` /
  `wait_agent`를 통해 검토자를 호출하며, `TeammateIdle`과 `TaskCompleted` 훅에 해당하는 것은 Codex에
  없습니다.

OpenClaw, Kiro, Pi 런타임에 대해서는 자동화 동작이 다릅니다. Claude Code의 동작을 그대로
가정하지 말고, [에이전트 플랫폼 참고 문서](/ko/reference/agents/) 아래 각 런타임의 페이지에서 무엇을
지원하는지 확인하세요.

## 에이전트용

- **트리거:**
  - `chorus_pm_submit_proposal` 이후, `PostToolUse` 훅이 `chorus:proposal-reviewer` 생성을
    촉구합니다. 완료를 기다린 뒤 제안의 이번 라운드 `VERDICT:` 댓글을 읽으세요.
  - `chorus_submit_for_verify` 이후, `chorus:task-reviewer`를 생성합니다. 작업의 `VERDICT:` 댓글을
    읽으세요.
  - 아이디어를 뿌리로 하는 제안의 **마지막** 작업에 대해 `chorus_admin_verify_task`를 한 후, 코드
    검토자를 생성합니다. 아이디어의 `VERDICT:` 댓글을 읽으세요. 이는 Claude Code
    (`chorus:code-reviewer`)와 Codex(`chorus-code-reviewer`) 양쪽에서 실행됩니다.
  - 검토자는 **자동으로** 실행되지 않습니다. 메인 에이전트가 직접 생성하고 판정을 기다립니다. `PASS` /
    `PASS WITH NOTES`는 계속, `FAIL`은 차단 요소를 고치고 재제출하라는 뜻입니다.
- **제약:**
  - 위의 읽기 전용 제한과 이번 라운드 판정 대기 규칙을 따르세요. 제안 검토는 셸 검사를 허용하지만
    테스트/빌드는 금지합니다. 다시 생성하거나 자체 검토해서 명시적인 사람 에스컬레이션을 우회하지 마세요.
  - 세 검토자(제안·작업·코드) 전부가 Claude Code와 Codex **양쪽**에 탑재됩니다. Claude Code 전용인
    것은 `userConfig` 설정 토글 — `enable*` 스위치(`enableProposalReviewer`, `enableTaskReviewer`,
    `enableCodeReviewer`)와 라운드 상한(`maxProposalReviewRounds`, `maxTaskReviewRounds`,
    `maxCodeReviewRounds`, 기본 3, `0` = 무제한)입니다. Codex에는 `userConfig`가 없으므로, Codex에서는
    스킬과 훅이 이 검토자들을 직접 제어하며 설치 시에 끌 수 없습니다.
  - `chorus_create_session`이나 `chorus_close_session`을 **호출하지 마세요**. 세션 수명 주기 훅
    (`SessionStart`, `SubagentStart`, `SubagentStop`)이 관리합니다.
  - **헤드리스** 데몬 세션은 대화형 프롬프트(`AskUserQuestion` 등)를 사용해서는 **안 됩니다**. 결정은
    Chorus 댓글 + `@mention`과 요구사항 구체화를 통해 되돌려 보내세요.