연구 리뷰 (모듈형 및 결합 리뷰 게이트)
계획(Plan), 코딩(Coding), 테스트(Test)는 독립형 또는 결합형으로 실행할 수 있습니다:
- 계획만 세웠다면 **모드 A (계획 리뷰)**를 실행하세요.
- 코드를 작성하고 즉시 테스트를 작성/실행했다면(자연스러운 흐름) **모드 B+C 결합 (코드 및 테스트 결합 리뷰)**를 단일 병렬 리뷰 라운드로 실행하세요—두 개의 별도 리뷰 라운드를 연속해서 소모하지 마십시오.
- 코드만 작성하고 테스트는 작성하지 않았거나, 기존 코드에 대한 테스트만 작성/실행했다면 모드 B 또는 모드 C를 독립형으로 실행하세요.
1. 리뷰어 서브에이전트 디스패치 (spawn_subagent)
- 기본 리뷰어 (
channel=mcli):spawn_subagent를 동시에 호출하여 두 개의 병렬 리뷰어를 실행하고get_command_or_subagent_output을 통해 둘 다 완료될 때까지 기다립니다:- 서브에이전트 1:
model: "deepseek-v4.1-flash"(mcli 채널) - 서브에이전트 2:
model: "glm-5.3"(mcli 채널)
- 서브에이전트 1:
- 사용자 재정의: 사용자가 다른 모델(예:
kimi-k3.1-pro,MiniMax-M3.1-Flash,deepseek-v4-pro, 또는friday/*/catpaw-ide/*슬러그)을 지정하면, 사용자가 지정한model슬러그를spawn_subagent에 전달하세요. - 증분 마무리 (
resume_from) :- 발견 (1라운드): 최소 아티팩트(계획,
git diff, 테스트 코드 + 실행 stdout/stderr)와 주요 파일 경로만으로 새 서브에이전트를 생성하세요—절대 대화 기록을 전달하지 마십시오. - 마무리 (2라운드 이상, 수정 또는 추가 테스트가 필요한 경우): 각 리뷰어에 대해
resume_from: "<subagent_id>"를 사용하여spawn_subagent를 호출하고, 활성 발견 사항과 수정/테스트 델타만 전달하여 변경되지 않은 파일을 다시 읽지 않고 업데이트를 검증하도록 하세요.
- 발견 (1라운드): 최소 아티팩트(계획,
2. 핵심 역할 경계
- 메인 에이전트가 먼저 검증 수행: 리뷰어를 디스패치하기 전에 빠른 구문/스모크 테스트를 실행하는 것이 좋습니다. 리뷰어가 깨진 구문에 시간을 낭비하지 않도록 하세요. 정확한 테스트 명령과 출력을
메인 에이전트 검증 증거로 전달하세요. - 엄격한 읽기 전용 리뷰어: 리뷰어 서브에이전트에게 파일을 읽거나 grep만 하고, 중요도 순으로
file:line증거와 함께 발견 사항을 보고하고, 입증되지 않은 엣지 케이스가 있을 경우- Validation request: <정확한 검사>를 내보내도록 지시하세요. 리뷰어는 절대 파일을 편집하거나 명령을 실행하지 않습니다. - 메인 에이전트 중재: 모든 실행된 리뷰어가 완료될 때까지 기다린 후 편집하세요. 후보 버그를 독립적으로 재현하고, 유효한
Validation request를 실행하며, 구체적인 코드 또는 수학적 증거를 바탕으로 중재(수락/거부)하세요.
모드 A: 계획 리뷰 (독립형)
- 준비: 목표, 수정할 파일, 텐서 형태/데이터 흐름, 그리고 명시적 가정(학습 의미론, 보상 척도 또는 기준선 공정성에 영향을 미치는 명시되지 않은 선택)을 명시하세요.
- 리뷰어에 프롬프트:
"이 연구 계획을 읽기 전용으로 리뷰하세요. 파일을 편집하거나 명령을 실행하지 마십시오. 명시되지 않은 가정에 이의를 제기하고, 데이터/레이블 누수, 기준선 불공정성, 분산/롤아웃 병목 현상을 확인하세요.
Review coverage: FULL|PARTIAL - <검사한 파일>을 명시하고Review verdict: APPROVED|FINDINGS로 끝내세요. [계획 및 주요 파일 경로 삽입]"
모드 B: 코딩 리뷰 (독립형 — 테스트가 아직 작성되지 않은 경우)
- 준비: 요구사항/계획 요약과
git diff를 수집하세요. - 리뷰어에 프롬프트: 변경된 파일과 직접 호출자를 읽기 전용으로 검사하여 조용한 연구 버그를 찾도록 지시하세요:
- 마스킹 및 정렬: SFT/RL 프롬프트 대 응답 토큰 마스크의 1 오프셋 오류, 패딩 측 불일치, EOS/잘림 처리.
- 텐서 형태 및 브로드캐스팅: 의도하지 않은 브로드캐스팅(예:
(B, 1)대(B,)), 차원 축소 오류(시퀀스 대 배치에 대한mean/sum). - 그래디언트 및 상태 위생: 잘못 배치된
detach()/no_grad(), KL 방향, 이점 정규화 범위, 롤아웃 전반에 걸친 에이전트 환경 상태 재설정 누락. Review coverage와Review verdict: APPROVED|FINDINGS를 요구하세요.
모드 C: 테스트 리뷰 (독립형 — 기존 코드에 대한 테스트 추가/감사 시)
- 준비: 테스트 파일 경로, 대상 모듈 경로, 실제 테스트 실행 stdout/stderr를 수집하세요.
- 리뷰어에 프롬프트:
"이 테스트와 그 실행 결과를 읽기 전용으로 감사하세요. 파일을 편집하거나 명령을 실행하지 마십시오. 핵심 수학/텐서 불변성과 엣지 케이스를 진정으로 검증했습니까, 아니면 실제 로직을 모킹하거나 통과하기 위해 주장을 약화시켰습니까? 엣지 케이스가 테스트되지 않은 경우
- Validation request: ...를 내보내세요.Review coverage를 명시하고Review verdict: APPROVED|FINDINGS로 끝내세요."
모드 B+C: 코딩 및 테스트 결합 리뷰 (메인 에이전트가 한 번에 코딩하고 자체 테스트한 경우)
- 준비: 요구사항/계획 요약, 구현 + 테스트
git diff,메인 에이전트 검증 증거(실행된 정확한 테스트 명령과 그 stdout/stderr)를 패키징하세요. - 리뷰어에 프롬프트:
"구현 diff와 메인 에이전트의 자체 테스트를 읽기 전용 결합 리뷰하세요. 파일을 편집하거나 명령을 실행하지 마십시오.
- 코드 확인: 변경된 파일과 직접 호출자에서 조용한 연구 버그를 찾으세요(토큰 마스크 1 오프셋, 패딩/EOS 정렬, 의도하지 않은 텐서 브로드캐스팅
(B,1)대(B,), 잘못된 차원 축소, 잘못 배치된detach()/no_grad(), KL/이점 수학, 재설정되지 않은 롤아웃 상태). - 자체 테스트 감사: 메인 에이전트의 테스트가 이러한 불변성과 엣지 케이스를 진정으로 검증하는지, 아니면 확증 편향(해피 패스만 테스트, 핵심 로직 모킹, 약한 주장)이 있는지 확인하세요. 누락된 엣지 케이스 테스트에 대해
- Validation request: <정확한 검사>를 내보내세요.Review coverage: FULL|PARTIAL - <검사한 파일>을 명시하고Review verdict: APPROVED|FINDINGS로 끝내세요."
- 코드 확인: 변경된 파일과 직접 호출자에서 조용한 연구 버그를 찾으세요(토큰 마스크 1 오프셋, 패딩/EOS 정렬, 의도하지 않은 텐서 브로드캐스팅
- 중재 및 마무리: 수락된 코드 버그를 수정하고 유효한
Validation request를 이행하세요. 중요 변경 사항이 발생한 경우 두 리뷰어 모두에resume_from을 사용하여 델타를 검증하세요.
3. 경량 원장 (docs/review-log.md)
각 리뷰 게이트가 완료된 후, 현재 프로젝트의 docs/review-log.md에 간결한 5~10줄 영어 항목을 추가하세요(파일이 없으면 생성). 이렇게 하면 컨텍스트 압축 과정에서 subagent_id 핸들을 유지하고 실험 감사 추적성을 유지합니다:
## [YYYY-MM-DD] <짧은 작업 제목> (<모드 A / B / C / B+C>)
- **가정 / 범위**: <주요 설계 가정 및 수정된 파일에 대한 1줄 요약>
- **리뷰어**: `deepseek-v4.1-flash` (`id: <subagent_id>`), `glm-5.3` (`id: <subagent_id>`)
- **중재**:
- `[ACCEPTED]` `<file:line>` — <간결한 버그/결함 및 수정 방법>
- `[REJECTED]` `<file:line>` — <리뷰어 발견 사항이 잘못된 긍정인 이유(수학/코드 증거 포함)>
- **판결 및 증거**: `APPROVED` (<1줄 테스트/스모크 검증 결과>)