External review loop

외부 리뷰 루프 (External Review Loop)

각 단계 산출물마다 codex·gemini에게 리뷰를 요청 → 이슈를 직접 검증 → 확인분만 수정하는 마감 게이트. 일반화 정본 — 어떤 프로젝트·어떤 산출물 유형(설계서/코드/문서)에도 적용.

왜 외부 리뷰인가: 내부 생성-검증/QA는 같은 세션·같은 컨텍스트라 동일한 맹점을 공유한다. 외부 독립 AI는 다른 관점으로 결함을 잡는다.

왜 전건 직접 판정인가: 외부 리뷰어는 설계 결정·동결 계약·기수정 이력·실측 수치를 모른다. 보고 이슈의 상당수(선례 30~40%)는 기각 대상 — 무비판 반영은 계약 파괴·과설계·재작업을 만든다. 판정 권위 = 오케스트레이터(실코드/실문서 대조). 위임 금지.

트리거

• 사용: "외부 리뷰", "codex/gemini 리뷰", "리뷰 게이트", "설계서 리뷰", "코드 리뷰해서 검증·수정", "이슈 검증하고 수정", "단계 산출물 리뷰" — 단계 산출물(설계서/코드/문서)의 마감 게이트로 요청될 때. 사용자가 이슈 목록을 직접 제출하는 수동 리뷰도 포함(Step 4~7 적용).
• 비사용(near-miss): 같은 세션의 내부 자체 검토·생성-검증·QA(독립 관점이 아니므로 별개 게이트). 외부 리뷰어 호출 없이 바로 고치는 단순 수정. 판정·마감 게이트가 필요 없는 단발 질의. 리뷰 없이 코드만 훑어보는 일반 코드 읽기.

입력 (호출 시 채울 플레이스홀더)

• {산출물}: 리뷰 대상 경로 — 설계서/코드 디렉토리/문서 (예: docs/design/auth.md 또는 변경 파일 목록)
• {단계ID}: 임의 단계 식별자 (예: design-auth, P2-1, feat-login)
• {커밋id}: 해당되면 git rev-parse HEAD, 아니면 생략(설계서 리뷰 등)
• {게이트명령}: 프로젝트 테스트/린트 게이트 (예: make gates / npm test && tsc --noEmit / 없으면 생략)

절차

Step 1 — 리뷰 요청 프롬프트 구성

2종 분담: codex = 일반/정합성 리뷰, gemini = 성능·안정성 리뷰. 산출물 유형에 맞게 "소스코드" → "설계서/문서"로 치환.

# 일반 (codex)
리뷰 대상 : {산출물}
관련 commit id : {커밋id}   # 없으면 생략
위 산출물과 관련 자료를 리뷰·검토하여 발생 가능한 이슈를 모두 찾아 보고해줘.
<이슈 작성 방법>
1. [{이슈레벨}] {이슈 타이틀}
- 현황: {현황/상황}
- 이슈: {상세}
- 권고: {해결·대응 방안}
</이슈 작성 방법>

gemini 프롬프트는 동일 틀 + "성능/속도·안정성 중심으로" 한 줄 추가.

Step 2 — 병렬 비대화 실행

프로젝트 루트에서 두 CLI를 백그라운드 병렬·읽기전용 실행. 프롬프트·출력 모두 _workspace/reviews/에 보존(감사 추적 — /tmp 금지).

mkdir -p _workspace/reviews
# 주의: codex exec는 stdin 열려 있으면 "Reading additional input from stdin..." 무한 대기
#       → 반드시 < /dev/null 로 stdin 폐쇄
codex exec --sandbox read-only "$(cat _workspace/reviews/{단계ID}_prompt_general.md)" < /dev/null \
  > _workspace/reviews/{단계ID}_codex.md 2>&1 &
gemini -p "$(cat _workspace/reviews/{단계ID}_prompt_perf.md)" < /dev/null \
  > _workspace/reviews/{단계ID}_gemini.md 2>&1 &
# gemini 긴 프롬프트 대안: cat prompt.md | gemini -p "위 요청대로 리뷰하고 지정 형식으로 보고하라"

• Bash run_in_background + timeout 600s. 완료 통보까지 다른 작업 가능.
• 실패/타임아웃 → 1회 재시도 → 재실패 시 해당 도구 누락을 결과서에 명시하고 단일 출처로 진행(루프 차단 금지).

Step 3 — 이슈 통합

두 출력에서 이슈 추출 → 중복 병합(동일 대상·동일 결함 = 1건, 출처 병기) → 번호 재부여. 0건이면 "외부 리뷰 — 이슈 0건(codex·gemini)" 기록 후 종료.

Step 4 — 전건 판정 (오케스트레이터 직접 — 위임 금지)

이슈마다 실코드/실문서 대조(grep/Read) 후 판정. 핵심 확인은 직접, 대량 확인만 에이전트 보조.

판정	기준	처리
확인	결함 재현/실재 확인	Step 5 수정
부분 확인	지적은 실재하나 권고가 과잉/계약 위배	비파괴 범위만 수정 + 잔여 기각 근거
이월(DEFERRED)	타당하나 본 단계 범위 외/후순위	백로그 위치 명기 — 기각과 구분
기각	아래 사유표	근거 명시(코드/정본 인용) — 삭제 금지

기각 사유표(일반화 선례):

• 동결 계약 위배: API 응답/필드/시그니처 변경 — 동결본 breaking. 백로그로
• 설계 정본 명시 결정: 계획서·DEC에 명시된 의도 — 유지, additive 보강만
• 기구현 오판: 리뷰어가 호출 형태만 보고 오판 — 코드 인용 반박
• YAGNI/과설계: 규모 대비 과잉 — 백로그
• 리뷰어 자인 비병목: 실측 수치로 "병목 아님" 명시된 항목
• 기존 설계와 상충: 멱등·격리 등 기결정과 충돌 — 상충 분석 명기

Step 5 — 확인분 TDD 수정

../my-harness/references/tdd-doctrine.md 규율을 따른다(Red→Green→Refactor, 구조/행위 커밋 분리).

• 다중 에이전트 병렬 시 파일권 명시 분리(병렬 충돌 = 1차 실패 주원인)
• 건별 RED(결함 재현) → GREEN → 에이전트는 git commit·브랜치 금지 → status 기록(_workspace/status/)
• 불변 조건: 동결 계약 breaking 0, 산출물 계약 위반 0

Step 6 — 통합 게이트

{게이트명령} 실행 → PASS 확인. 게이트가 없으면(설계서 등) 정본 정합성 재확인으로 대체.

• 테스트 DB/리소스 간섭 가능 게이트는 동시 실행 금지 — 충돌 시 단독 재실행.

Step 7 — 기록·커밋

1. 결과서에 ## 외부 리뷰 반영 ({일자} — {단계ID} 대상 {k}건) § 추가 — 판정표(확인/부분/이월/기각 + 근거)·게이트 수치·출처(codex/gemini)
2. fix: 외부 리뷰 {k}건 — {요지} 단일 커밋(Co-Authored-By 포함). 순서: 게이트 PASS → 승인 관문 → 커밋. 승인 관문 기본은 사용자 대기, _workspace/.autonomous 마커 존재 시 자동 통과. push는 자율이어도 기본 대기(_workspace/.autonomous-push 마커 시만 자동).

재진입

• 동일 단계 2차 리뷰(사용자 재제출 포함): 기수정 항목은 재작업 금지 — 수정 커밋 코드 인용 + 게이트 재실행으로 "기수정 확인" 응답
• 리뷰가 수정 전 코드 기준이면(시점차) 동일 처리

테스트 시나리오

• 정상: 설계서 커밋 → codex 8건+gemini 3건 → 중복 1 병합 → 10건 판정(확인 6/부분 2/이월 1/기각 1) → 확인분 TDD 수정 → 게이트 PASS → 결과서 §·fix 커밋
• 에러: gemini 타임아웃 ×2 → "gemini 미수집" 명시, codex 단독 진행 — 루프 완료
• 후속: 사용자가 동일 목록 재제출 → 재진입 절차대로 기수정 확인만으로 응답