doc-review

Base guidelines: SKILL.md applies to this skill.

문서 검토 (Document Review)

다중 에이전트 협업 (Multi-Agent Collaboration)

사용자의 입력($ARGUMENTS) 내에 --add <ai-이름> 형태의 플래그가 포함되어 있는지 확인하십시오. 현재 지원되는 외부 AI 인터페이스는 --add gemini (또는 --add gem)입니다.

만약 해당 플래그가 감지되면, 작업을 단독으로 확정하지 말고 다음 절차를 따르십시오:

1. 의도 파악: 플래그를 제외한 나머지 문자열을 실제 지시사항으로 간주합니다.
2. 초안 작성: 본인(주 에이전트)의 지식과 코드베이스 컨텍스트를 바탕으로 작업의 초기 뼈대나 접근법을 생각합니다.
3. MCP 협업 호출: gem 도구를 호출하여 외부 Gemini 에이전트에게 조언이나 검토를 구합니다.
   • 호출 시 전달할 메시지 예시: "나는 현재 이 작업에 대한 초안을 세우고 있어. 내 초안은 [초안 요약]이야. 이 접근 방식의 기술적 타당성을 검토하고 누락된 에지 케이스나 더 나은 패턴을 조언해줄 수 있어?"
4. 결과 통합: gem 도구가 반환한 피드백을 당신의 최종 결과물에 통합(Synthesis)합니다.
5. 명시적 표시: 최종 산출물의 상단 또는 설명 부분에 "이 결과물은 Gemini와의 협업을 통해 검토 및 보완되었습니다."라는 문구를 추가하십시오.

이 협업 절차를 염두에 두고 아래의 본래 스킬 워크플로우를 진행하십시오.

다중 페르소나 분석을 통해 요구사항 또는 계획 문서를 검토합니다. 전문 리뷰어 에이전트를 병렬로 배치하고, safe_auto 수정을 자동으로 적용하며, 남은 발견 사항은 사용자의 결정을 위해 4가지 옵션(발견 사항별 단계별 진행, 최선의 판단으로 자동 해결, 미결 질문에 추가, 보고만 수행)으로 라우팅합니다.

대화형 모드 규칙

• 질문이 시작되기 전에 플랫폼 질문 도구를 미리 로드하십시오. Claude Code에서 AskUserQuestion은 지연된 도구이므로 세션 시작 시에는 스키마를 사용할 수 없습니다. 대화형 모드 작업 시작 시(라우팅 질문, 발견 사항별 단계별 질문, 일괄 미리보기 진행/취소, 단계 5 최종 질문 전) ToolSearch를 호출하여 select:AskUserQuestion 쿼리로 스키마를 로드하십시오. 대화형 흐름의 최상단에서 한 번 미리 로드하고, 첫 질문 시점까지 기다리지 마십시오. Codex, Gemini, Pi에서는 이 사전 로드가 필요하지 않습니다.
• 번호가 매겨진 리스트 폴백은 하니스(harness)에 차단형 질문 도구가 실제로 없을 때만 적용됩니다. ToolSearch가 일치하는 결과를 반환하지 않거나, 도구 호출이 명시적으로 실패하거나, 런타임 모드에서 도구가 노출되지 않는 경우(예: request_user_input을 사용할 수 없는 Codex 편집 모드) 등이 이에 해당합니다. 스키마 로드 대기 중인 상태는 폴백 트리거가 아닙니다. 위의 사전 로드 규칙에 따라 먼저 ToolSearch를 호출하십시오. 실제 폴백 상황에서는 옵션을 번호가 매겨진 리스트로 제시하고 사용자의 응답을 기다리십시오 — 절대 질문을 소리 없이 건너뛰지 마십시오. 도구가 불편하다는 이유로, 모델이 보고서 형식 모드라는 이유로, 또는 지침이 긴 스킬에 묻혀 있다는 이유로 질문을 서술형 텍스트로 렌더링하는 것은 버그입니다. 사용자 결정이 필요한 질문은 반드시 도구를 실행하거나 명확하게 폴백해야 합니다.

단계 0: 모드 감지

스킬 인자에서 mode:headless가 있는지 확인합니다. 인자에는 문서 경로, mode:headless, 또는 둘 다 포함될 수 있습니다. mode:로 시작하는 토큰은 플래그이며 파일 경로가 아닙니다 — 인자에서 이를 제거하고 남은 토큰(있는 경우)을 단계 1의 문서 경로로 사용하십시오.

mode:headless가 있으면 나머지 워크플로우를 **헤드리스 모드(headless mode)**로 설정합니다.

헤드리스 모드는 상호작용 모델을 변경하는 것이지 분류 기준을 변경하는 것이 아닙니다. ce-doc-review는 여전히 각 발견 사항이 어떤 티어에 속하는지에 대해 동일한 판단을 적용합니다. 유일한 차이점은 safe_auto가 아닌 발견 사항이 전달되는 방식입니다:

• safe_auto 수정은 소리 없이 적용됩니다 (대화형 모드와 동일)
• gated_auto, manual, 그리고 FYI 발견 사항은 호출자가 처리할 수 있도록 구조화된 텍스트로 반환됩니다 — 차단형 질문 프롬프트나 대화형 라우팅은 없습니다.
• 단계 5는 즉시 "검토 완료"와 함께 반환됩니다 (라우팅 질문이나 최종 질문 없음).

호출자는 원래의 분류가 유지된 발견 사항을 수신하고 그에 대해 무엇을 할지 결정합니다.

호출자는 다음과 같이 스킬 인자에 mode:headless를 포함하여 헤드리스 모드를 호출합니다:

Skill("ce-doc-review", "mode:headless docs/plans/my-plan.md")

mode:headless가 없으면 스킬은 references/walkthrough.md 및 references/bulk-preview.md에 정의된 라우팅 질문, 단계별 진행, 일괄 미리보기 동작과 함께 기본 대화형 모드로 실행됩니다.

단계 1: 문서 가져오기 및 분석

문서 경로가 제공된 경우: 문서를 읽고 계속 진행합니다.

문서가 지정되지 않은 경우 (대화형 모드): 검토할 문서를 묻거나, 파일 검색/glob 도구(예: Claude Code의 Glob)를 사용하여 docs/brainstorms/ 또는 docs/plans/에서 가장 최근 문서를 찾습니다.

문서가 지정되지 않은 경우 (헤드리스 모드): 에이전트를 배치하지 않고 "검토 실패: 헤드리스 모드에서는 문서 경로가 필요합니다. Skill("ce-doc-review", "mode:headless ")로 다시 호출하십시오."라고 출력합니다.

문서 유형 분류

파일 경로가 아니라 내용의 형상을 읽고 문서를 분류하십시오. 경로는 주된 신호가 아닌 참고용 힌트일 뿐입니다 — docs/plans/ 아래에 있는 브레인스토밍 스타일의 문서는 여전히 requirements로 분류되어야 하며, docs/brainstorms/ 아래에 있는 계획 형상의 문서는 plan으로 분류되어야 합니다. 아래의 리뷰어들은 이 분류에 따라 다르게 작동하므로, 계획 형상의 문서를 요구사항 문서로(또는 그 반대로) 오분류하면 노이즈가 많거나 충분히 정밀하지 못한 결과가 생성됩니다.

다음 신호들을 사용하여 결정하십시오:

requirements (무엇을 만들 것인가) 신호:

• actors:, flows:, acceptance_examples:, 또는 브레인스토밍 형상의 값을 가진 status:와 같은 frontmatter 필드
• Acceptance Examples, Actors, Key Flows, User Flows, Outstanding Questions, Resolve Before Planning과 같은 섹션 헤더
• R1, R2, A1, F1, AE1 형태의 번호가 매겨진 식별자 (요구사항, 액터, 흐름, 인수 예시 ID)
• 사용자/비즈니스 문제, 동작, 범위 경계, 성공 기준에 초점을 맞춘 서술
• 구현 단위 없음, 단위별 파일 목록 없음, 단위에 첨부된 테스트 시나리오 없음

plan (어떻게 만들 것인가) 신호:

• type: feat|fix|refactor, origin: docs/brainstorms/...와 같은 frontmatter 필드
• Implementation Units, Output Structure, Key Technical Decisions, Risks & Dependencies, System-Wide Impact와 같은 섹션 헤더
• U1, U2 형태의 번호가 매겨진 식별자 (구현 단위 ID)
• Goal, Files, Approach, Test scenarios, Verification이라는 이름의 단위별 필드
• 생성/수정/테스트할 저장소 상대 경로 파일들
• 기술적 결정, 시퀀싱, 구현자 지향적인 상세 내용에 초점을 맞춘 서술

동률 처리 규칙. 내용 신호가 혼합되어 있거나 희박할 경우 경로를 따릅니다: docs/brainstorms/ → requirements, docs/plans/ → plan. 두 경로 모두 해당하지 않는 경우 지배적인 내용 형상을 권위 있는 것으로 간주합니다. 형상이 진정으로 모호하다면 requirements로 기본 설정하십시오 (더 보수적인 분류이며 계획 관련 타당성 확인을 적게 활성화함).

분류 결과를 하위 에이전트 템플릿의 {document_type} 슬롯을 통해 각 페르소나에게 전달하십시오. 페르소나는 이를 읽고 그에 맞게 분석을 조정합니다.

조건부 페르소나 선택

문서 내용을 분석하여 활성화할 조건부 페르소나를 결정합니다. 다음 신호들을 확인하십시오:

product-lens (제품 렌즈) -- 문서가 무엇을 만들고 왜 만드는지에 대해 논박 가능한 주장을 하거나, 제안된 작업이 즉각적인 문제 해결을 넘어 전략적 무게를 가질 때 활성화합니다. 시스템의 사용자는 최종 사용자, 개발자, 운영자, 유지보수자 또는 다른 청중일 수 있습니다 — 기준은 도메인에 구애받지 않습니다. 다음 두 가지 조건 중 하나를 확인하십시오:

조건 1 — 전제 주장: 문서가 단순히 작업을 설명하거나 알려진 요구사항을 재진술하는 것이 아니라, 지식이 있는 이해관계자가 합리적으로 논박할 수 있는 위치를 취함:

• 서술된 필요성이 자명하지 않거나 논쟁의 여지가 있는 문제 프레임워크
• 대안이 분명히 존재하는 해결책 선택 (암시적 또는 명시적)
• 무엇을 구축하고 무엇을 연기할지 명시적으로 순위를 매기는 우선순위 결정
• 단순한 제약 조건 재진술이나 산출물 설명이 아닌, 특정 사용자 결과를 예측하는 목표 선언

조건 2 — 전략적 무게: 전제가 타당하더라도 제안된 작업이 시스템의 궤적, 사용자 인식 또는 경쟁력 있는 위치에 영향을 줄 수 있음:

• 시스템이 어떻게 인식되는지 또는 무엇으로 알려지게 되는지를 형성하는 변경 사항
• 채택, 온보딩 또는 인지 부하에 영향을 미치는 복잡성 또는 단순성 베팅
• 미래의 방향을 열거나 닫는 작업 (경로 의존성, 아키텍처적 약속)
• 기회비용 시사 — 이것을 만든다는 것은 다른 것을 만들지 않는다는 것을 의미함

design-lens (디자인 렌즈) -- 문서에 다음이 포함된 경우 활성화:

• UI/UX 참조, 프론트엔드 컴포넌트 또는 시각적 디자인 언어
• 사용자 흐름, 와이어프레임, 화면/페이지/뷰 언급
• 상호작용 설명 (폼, 버튼, 네비게이션, 모달)
• 반응형 동작 또는 접근성(accessibility) 참조

security-lens (보안 렌즈) -- 문서에 다음이 포함된 경우 활성화:

• 인증/인가 언급, 로그인 흐름, 세션 관리
• 외부 클라이언트에 노출된 API 엔드포인트
• 데이터 처리, PII(개인 식별 정보), 결제, 토큰, 자격 증명, 암호화
• 신뢰 경계(trust boundary)에 영향을 미치는 타사 통합

scope-guardian (범위 수호자) -- 문서에 다음이 포함된 경우 활성화:

• 여러 우선순위 티어 (P0/P1/P2, 필수/권장/선택 등)
• 많은 요구사항 수 (8개 이상의 개별 요구사항 또는 구현 단위)
• 도전적인 목표, "있으면 좋은 것(nice-to-haves)" 또는 "미래 작업" 섹션
• 명시된 목표와 일치하지 않아 보이는 범위 경계 언어
• 요구사항과 명확하게 연결되지 않는 목표

adversarial (적대적 리뷰) -- 문서가 단순히 구조적 복잡성을 넘어 높은 가치의 도전 표면을 가지고 있을 때 활성화합니다. 서술된 근거가 있는 일반적인 계획은 그 자체로 적대적 신호가 아닙니다 — 전제/가정 검토는 유일한 신호가 "이 계획은 잘 구조화되어 있다"일 때 결정된 질문들을 다시 논의하게 만듭니다. 다음 중 하나라도 해당하면 활성화하십시오:

• 문제 프레임워크, 해결책 선택, 우선순위 결정, 예측된 결과 중 2개 이상의 논박 가능한 주장을 가진 요구사항 문서인 경우 — 전제 정밀 검토는 브레인스토밍 단계의 핵심입니다.
• 문서가 고위험 도메인을 건드리는 경우 — 인증, 결제, 빌링, 데이터 마이그레이션, 개인정보 보호/컴플라이언스, 외부 통합, 암호화 등 (문서 유형이나 규모에 관계없이)
• 문서가 새로운 추상화, 프레임워크 또는 중요한 아키텍처 패턴을 제안하는 경우 (문서 유형에 관계없이)
• 원래의 요구사항 문서(origin:)가 없는 계획인 경우 (새로운 프로젝트의 부트스트랩) — 전제가 상류에서 검증되지 않았습니다.
• 원래의 요구사항 문서보다 범위를 명시적으로 확장하는 계획인 경우 (새로운 액터, 새로운 흐름, 연기되었다가 복원된 기능 등)
• 문서에 명시적인 대안 섹션이나 해결되지 않은 트레이드오프가 포함된 경우 — 적대적 리뷰는 선택된 방향을 스트레스 테스트하는 데 도움이 됩니다.

요구사항 문서에서 파생되었고, 범위를 유지하며, 고위험 도메인이나 새로운 추상화를 도입하지 않는 일반적인 계획 문서에는 적대적 리뷰어를 활성화하지 마십시오. 계획의 구조적 결정(더 많은 단위, 더 많은 근거)은 그 자체로 적대적 신호가 아닙니다 — 그것은 계획이 제 역할을 하고 있는 것입니다.

단계 2: 페르소나 발표 및 배치

리뷰 팀 발표

사용자에게 어떤 페르소나가 검토할 것이고 왜 그런지 알려줍니다. 조건부 페르소나의 경우 근거를 포함하십시오:

다음 팀과 함께 검토합니다:
- ce-coherence-reviewer (항시 활성)
- ce-feasibility-reviewer (항시 활성)
- ce-scope-guardian-reviewer -- 계획에 3가지 우선순위 수준에 걸쳐 12개의 요구사항이 있음
- ce-security-lens-reviewer -- 계획에서 인증 흐름이 포함된 API 엔드포인트를 추가함

에이전트 목록 작성

항시 포함:

• ce-coherence-reviewer
• ce-feasibility-reviewer

활성화된 조건부 페르소나 추가:

• ce-product-lens-reviewer
• ce-design-lens-reviewer
• ce-security-lens-reviewer
• ce-scope-guardian-reviewer
• ce-adversarial-document-reviewer

배치

플랫폼의 하위 에이전트 프리미티브(예: Claude Code의 Agent, Codex의 spawn_agent, Pi의 subagent)를 사용하여 제한된 병렬 처리로 에이전트를 배치합니다. 사용자의 설정된 권한 설정이 적용되도록 mode 파라미터는 생략하십시오. 현재 하니스의 활성 하위 에이전트 제한을 준수하십시오. 선택된 리뷰어를 대기열에 넣고 하니스가 허용하는 만큼만 배치하며, 리뷰어가 완료되면 비어 있는 슬롯을 채우십시오. 활성 에이전트/스레드/동시성 제한 생성 오류는 리뷰어 실패가 아닌 백프레셔(backpressure)로 처리하십시오. 리뷰어를 대기열에 남겨두고 슬롯이 확보된 후 다시 시도하십시오. 리뷰어가 성공적으로 배치된 후 타임아웃/실패하거나 용량 이외의 이유로 배치가 실패한 경우에만 리뷰어를 실패로 기록하십시오.

각 에이전트는 아래 포함된 하위 에이전트 템플릿으로 작성된 프롬프트를 수신하며, 다음 변수들이 채워집니다:

변수	값
{persona_file}	에이전트 마크다운 파일의 전체 내용
{schema}	아래 포함된 발견 사항 스키마 내용
{document_type}	단계 1 분류에서의 "requirements" 또는 "plan"
{document_path}	문서 경로
{origin_path}	문서의 origin: frontmatter 필드 값 (있는 경우), 없으면 리터럴 문자열 none. 전제에 따라 적응하는 페르소나(product-lens, adversarial, scope-guardian)는 이 슬롯을 읽어 기법 억제를 결정합니다 — 직접 frontmatter를 다시 파싱하지 않습니다. 단계 1 읽기 중에 이를 한 번 추출하십시오.
{document_content}	문서 전체 텍스트
{decision_primer}	현재 세션에서의 누적된 이전 라운드 결정 사항, 또는 첫 라운드인 경우 빈 <prior-decisions> 블록. 아래 "결정 프라이머(Decision primer)" 참조.

각 에이전트에게 문서 전체를 전달하십시오 — 섹션별로 나누지 마십시오.

결정 프라이머 (Decision primer)

라운드 1(이전 결정 없음)에서는 {decision_primer}를 다음과 같이 설정합니다:

<prior-decisions>
Round 1 — no prior decisions.
</prior-decisions>

라운드 2 이상(현재 대화형 세션에서 하나 이상의 이전 라운드 이후)에서는 이전 라운드 결정 사항을 누적하여 다음과 같이 렌더링합니다:

<prior-decisions>
Round 1 — applied (N entries):
- {section}: "{title}" ({reviewer}, {confidence})
  Evidence: "{evidence_snippet}"

Round 1 — rejected (M entries):
- {section}: "{title}" — Skipped because {reason}
  Evidence: "{evidence_snippet}"
- {section}: "{title}" — Deferred to Open Questions because {reason or "no reason provided"}
  Evidence: "{evidence_snippet}"
- {section}: "{title}" — Acknowledged without applying because {reason or "no suggested_fix — user acknowledged"}
  Evidence: "{evidence_snippet}"

Round 2 — applied (N entries):
...
</prior-decisions>

각 항목에는 Evidence: 라인이 포함됩니다. 이는 합성 규칙 R29(거부된 발견 사항 억제)와 R30(적용된 수정 사항 검증) 모두 증거 부분 문자열 중복 확인을 일치 조건의 일부로 사용하기 때문입니다 — 프라이머에 증거 스니펫이 없으면 오케스트레이터가 >50% 중복 테스트를 계산할 수 없어 핑거프린트 일치에만 의존해야 하며, 이는 거부된 발견 사항을 다시 노출하거나 너무 공격적으로 억제하게 됩니다. {evidence_snippet}은 발견 사항의 첫 번째 증거 인용문이며, 약 120자로 잘리고(경계에서 온전한 단어 보존) 내부 따옴표는 이스케이프 처리됩니다. 발견 사항에 여러 증거 항목이 있는 경우 첫 번째 항목을 사용하십시오. 나머지는 실행 아티팩트에 남아 있으며 중복 확인에는 필요하지 않습니다.

현재 세션의 모든 라운드에 걸쳐 누적하십시오. Skip, Defer, Acknowledge 작업은 모두 억제 목적상 "거부됨"으로 간주됩니다 — 각각은 사용자가 해당 발견 사항이 이번 라운드에서 조치할 가치가 없다고 결정했음을 나타냅니다 (Acknowledge는 수정 가드가 없는 변형입니다: 사용자가 suggested_fix가 없는 발견 사항을 보고 명시적으로 건너뛰거나 연기하지 않고 대신 승인 기록을 선택한 것입니다. 라운드 간 억제 측면에서 이는 Skip과 의미론적으로 동일합니다). 적용된 발견 사항은 적용된 리스트에 남아 라운드 N+1 페르소나가 수정 사항이 반영되었는지 확인할 수 있도록 합니다 (references/synthesis-and-presentation.md의 R30 참조).

세션 간 지속성은 범위를 벗어납니다. 동일한 문서에 대해 ce-doc-review를 새로 호출하면 이전 세션에서 발견 사항을 문서의 "미결 질문" 섹션으로 연기했더라도 이전 결정이 없는 새로운 라운드 1로 시작합니다.

오류 처리: 에이전트가 실패하거나 타임아웃되면 완료된 에이전트의 발견 사항으로 진행하십시오. "적용 범위(Coverage)" 섹션에 실패한 에이전트를 기록하십시오. 단일 에이전트 실패로 인해 전체 검토를 중단하지 마십시오.

배치 제한: 최대치(7개 에이전트)라도 제한된 병렬 배치를 사용하십시오. 하니스 캡이 선택된 팀 규모보다 낮으면 나머지는 대기열에 넣고 활성 리뷰어가 완료됨에 따라 실행하십시오.

단계 3-5: 합성, 프레젠테이션 및 다음 작업

모든 배치된 에이전트가 반환되면, 합성 파이프라인(검증, 앵커 기반 게이트, 중복 제거, 페르소나 간 합의 홍보, 모순 해결, 자동 홍보, FYI 하위 섹션을 포함한 3개 티어 라우팅), safe_auto 수정 적용, 헤드리스 봉투 출력, 라우팅 질문으로의 핸드오프를 위해 references/synthesis-and-presentation.md를 읽으십시오.

4가지 옵션 라우팅 질문 및 발견 사항별 단계별 진행(대화형 모드)에 대해서는 references/walkthrough.md를 읽으십시오. 최선의 판단으로 자동 해결, 미결 질문에 추가, 단계별 진행 중 나머지는 최선의 판단으로 자동 해결에서 사용되는 일괄 작업 미리보기에 대해서는 references/bulk-preview.md를 읽으십시오. 에이전트 배치가 완료되기 전에는 이 파일들을 로드하지 마십시오.

---

포함된 참조

하위 에이전트 템플릿 (Subagent Template)

@./references/subagent-template.md

발견 사항 스키마 (Findings Schema)

@./references/findings-schema.json