r3xsean/code-loop

최대 3라운드에 걸쳐 다른 모델과 코드 변경 사항을 검토합니다: 리뷰어가 변경 사항을 읽고, 브레이커가 테스트로 이를 깨뜨리려고 시도합니다. 각 수정은 발견된 문제를 해결하는 가장 작은 단위로 유지하고, 잘못된 발견 사항에 대해서는 증거를 제시하며 반박합니다.

1. 리뷰어와 브레이커 브리핑

리뷰어와 브레이커는 사용자가 지정한 패밀리(sol, opus, …) 중 orchestrator_capabilities에 있는 최신 모델이며, 사용자가 지정한 노력 수준으로 설정됩니다. 다른 모델 옵션은 설정하지 마십시오. 제공자만(gpt, claude) 지정하는 것은 패밀리를 명명하지 않습니다. 패밀리나 노력 수준이 누락된 경우 이를 요청하고 답변이 있을 때까지 다른 작업을 하지 마십시오.

기준(base)을 고정합니다: 호출자가 전달한 것을 사용하고, 그렇지 않으면 git merge-base HEAD <remote>/<default-branch>를 사용합니다. 여기서 리모트는 변경 사항이 병합되는 대상(upstream, 포크의 경우)이거나, 변경 사항이 커밋되지 않은 경우에만 HEAD입니다. 변경 사항을 포함하는 검사(checks)를 리포지토리의 검증 스킬(있는 경우 .agents/skills/verify/)을 통해 실행하고, 라운드 1 전에 실패한 항목을 수정합니다. 수정이 실행된 리비전(커밋되지 않은 변경 사항 포함)을 기록합니다.

모든 라운드는 새로운 delegate_task로 시작합니다. 반박 및 이후 라운드는 종료된 리뷰어에 대한 후속 메시지가 아닌 새 브리핑에 포함됩니다. 타임아웃이나 오류는 승인이 아닙니다: 실패한 에이전트를 한 번 다시 시작합니다.

변경 사항(diff)이 주석, 문서 또는 서식만 변경하는 경우 루프를 실행하지 않고 최종 메시지에 그렇게 명시합니다. 라운드 1에서는 리뷰어와 브레이커를 병렬로 시작하며, 브레이커는 isolation: "worktree"로 시작합니다. 변경 사항이 실행되는 코드를 변경하지 않는 경우 브레이커를 건너뜁니다. 경량 실행(see-it-through 티어가 전달되는 경우)에서는 라운드 1에 브레이커를 시작하지 않습니다. 리뷰어가 응답하면, 해당 응답의 'Not verified' 라인에 테스트로 해결할 수 있는 조건이 있는 경우에만 해당 조건으로 범위가 제한된 브레이커를 시작합니다.

두 브리핑 모두 다음 헤더로 시작합니다:

Repo: <절대 경로>  Base: <sha>  Out of scope: <범위>
Standards: <리포지토리의 규칙 파일 (예: AGENTS.md 또는 CONTRIBUTING.md); 또는 없음>
Setup: <모든 셸이 먼저 실행해야 하는 것 (예: 고정된 툴체인 스크립트) 및 새로운 체크아웃에 필요한 것 (예: 설치); 또는 없음>
Checks: <결과>  Running now: <아직 진행 중인 검사; 또는 없음>
Request: <사용자의 요청 또는 브리핑 (그대로) 또는 그 절대 경로>
Approach: <승인된 접근 방식 또는 그 절대 경로; 또는 없음>. 이 접근 방식의 주장은 작성자의 것입니다: 변경 사항(diff)이 의존하는 주장을 확인하십시오.
Acceptance: <변경 전에 작성된 승인 검사를 보유한 커밋 또는 패치; 또는 없음>
Diff: git diff <base>; 또한 git status --short에서 추적되지 않은 파일을 읽습니다.
Conditions: diff를 읽기 전에 Request로부터 승인 조건을 작성하십시오: 성공, 실패, 취소 및 재시도 시 사용자가 보거나 얻을 수 있는 것; 부분 실패 후 (메모리, 디스크 및 화면에 남아 있는 것); 반복 시 또는 이전 시도가 최신 시도보다 나중에 완료되는 경우; await가 사용자가 진행한 후에 반환되는 경우; 결과를 표시하는 모든 표면(캐시된 데이터 포함)에 대해; 그리고 변경 사항이 남길 수 있는 모든 상태에서 빠져나올 수 있는 방법. 변경된 코드가 해당 케이스에 도달하는 경우에만 한 조건을 작성하십시오: 의도된 경로, 변경된 코드의 다른 모든 호출자를 통해, 그리고 변경 사항이 이제 신뢰하는 상태의 다른 모든 작성자를 통해 (둘 다 검색).

리뷰어 브리핑(헤더 다음):

Review only: 읽고 추적만 하십시오. 편집, 커밋, 푸시, 댓글, 하위 에이전트 시작 또는 테스트나 빌드 작성/실행을 하지 마십시오.
Conditions가 지시하는 대로 승인 조건을 작성한 다음, Approach 내에서 어떻게 변경할지 작성하십시오. 최종 응답을 두 가지 모두 그대로 시작하십시오. VERDICT 라인이 뒤따릅니다.
변경 사항의 문제를 찾으십시오. 각 조건을 코드를 따라 사용자가 보거나 얻는 결과까지 추적하십시오. 귀하의 접근 방식은 diff가 실패하는 조건을 충족하거나, 더 적은 코드로 모든 조건을 충족하는 경우에만 발견 사항입니다.
발견한 각 버그에 대해 해당 클래스를 명명하고 diff의 나머지 부분과 해당 호출자에서 동일한 실수를 찾으십시오. 여기에는 변경 사항이 다르게 처리하는 형제 케이스가 포함됩니다. 클래스당 하나의 발견 사항을 보고하고 모든 위치를 나열하십시오.
Standards 파일에 대해 변경 사항을 확인하십시오. 해당 발견 사항에 [standards] 태그를 지정하고, 린터 및 타입 검사가 적용하는 사항은 건너뛰십시오.
어떤 조건도 필요로 하지 않는 코드 또는 가드, 리포지토리나 플랫폼이 이미 제공하는 새로운 코드, 그리고 Standards 또는 주변 코드의 규칙에서 벗어난 코드를 사소한 것으로 표시하십시오. 단순히 선호하는 스타일은 표시하지 마십시오.
변경 사항이 상태에 대한 경쟁 소유권, 두 곳에서 내려진 결정, 호출자가 기억해야 할 의무, 또는 호출자가 우회할 수 있는 경계를 도입하는지 확인하십시오. 해당 사항에 [structure] 태그를 지정하고, 코드와 그 결과를 명명하며, 아래 정의에 따라 등급을 매기십시오. 그러한 결과가 없는 다른 설계는 사소한 것입니다. 더 큰 재설계는 가장 작은 수정으로 해결할 수 없는 이유가 있는 경우에만 발견 사항입니다.
Acceptance의 검사를 수정하여 약속된 것을 증명하지 못하게 하는 것은 '해야 함'입니다.
blocker = 의도된 케이스가 잘못되었습니다. should = 이 변경 사항이 지원되는 작업이나 입력(사용자 작업, 디스크의 파일, I/O 실패, 사용자가 만든 파일)이 도달할 수 있는 문제를 야기하며, 이를 실행하거나 코드를 통해 추적하여(diff가 건드리지 않은 호출자를 포함하여) 보여줍니다. 변경 사항이 추가한 테스트가 증명하는 동작 없이 통과할 수 있다면 이것은 '해야 함'입니다.
nit = 스타일, 작은 성능, 다듬기. pre-existing = 기준(base)에서 동일한 실패가 발생하며, 테스트 또는 추적으로 보여지고, 변경 사항이 도달하기 더 쉽게 만들지 않거나 기존 주장과 모순되지 않습니다.
VERDICT: APPROVE 또는 CHANGES, 그 다음 발견 사항당 한 줄:
S1 [blocker|should|nit|pre-existing] <파일>:<라인> <주장>. Fix: <가장 작은 수정>
그 다음 Checked: 조건당 한 줄: <파일>:<라인> 및 해당 라인이 확립하는 것.
그 다음 Not verified: 확인할 수 없었던 것과 그 이유; 또는 없음.

브레이커 브리핑(헤더 다음):

이 변경 사항을 깨뜨리십시오. 커밋, 푸시, 댓글 또는 하위 에이전트를 시작하지 마십시오.
자신의 체크아웃, 즉 시작한 작업 디렉토리에서만 작업하십시오. 이 디렉토리는 <repo>의 HEAD 복사본입니다. 먼저 변경 사항의 커밋되지 않은 부분을 가져오십시오: git -C <repo> diff HEAD | git apply, 그런 다음 git -C <repo> status --short에 나열된 추적되지 않은 파일을 복사하십시오. <repo> 또는 사용자 설정의 파일을 절대 변경하지 말고, 푸시, 게시 또는 알림을 보내는 것을 실행하지 마십시오. 패키지 관리자 캐시는 괜찮습니다. E2E 실행 및 Running now에 나열된 모든 것을 건너뛰고, 테스트에 필요한 것만 컴파일하십시오.
Conditions가 지시하는 대로 승인 조건을 작성하십시오. 각 조건에 대해, 조건이 깨졌을 때 실패할 가장 작은 테스트를 작성하고 실행하십시오. 사용자가 보거나 얻는 것을 기준으로 단언하십시오.
변경 사항이 증명으로 추가하는 E2E 미만의 각 테스트에 대해, 잡아야 할 가드를 해제하거나 전제 조건을 깨뜨린 후 실행한 다음 코드를 복원하십시오.
COULDN'T TEST는 이 수준에서 도달할 수 없는 조건(예: E2E가 필요한 조건)에만 해당합니다. 느린 큐나 자신의 잘못된 설정은 해당되지 않습니다: 테스트를 하나의 작업으로 배치하고, 취소하지 않고 기다린 다음 설정을 수정하십시오.
응답하기 전에 기존 테스트가 다루지 않는 조건을 다루는 통과 테스트의 패치를 <keep path>에 작성하고, 추가한 다른 모든 것을 삭제하십시오.
응답, 조건당 한 줄: B1 HELD <조건> — <명령어>; B2 BROKE <조건> — <명령어> 및 실패 출력; 또는 B3 COULDN'T TEST <조건> — 이유. 그 다음 증명 테스트당 한 줄: P1 FAILS <테스트> (<가드> 해제 시); 또는 P2 STILL PASSES <테스트> (<가드> 해제 시). 그 다음: Kept: <keep path> 및 각 테스트가 다루는 조건; 또는 없음.

<keep path>를 선택하십시오: 두 체크아웃 외부의 절대 경로.

2. 발견 사항에 응답

리뷰어 브리핑의 정의에 따라 각 발견 사항을 직접 평가하고, 어떤 레이블이 붙었는지와 관계없이 평가하십시오. 각 BROKE 및 STILL PASSES 라인을 발견 사항으로 처리하십시오.

• 동의: 먼저, 의미 있는 테스트가 실용적일 때는 현재 코드에서 실패하는 테스트로 재현하고, 그렇지 않으면 직접 재현(명령어 및 출력)과 그 한계를 기록하십시오. 사실에 대한 주장(예: CI가 실행하는 것 또는 기준이 하는 것)은 출처에 대해 확인하십시오. 그런 다음 변경된 코드의 형제 케이스와 호출자에서 발견 사항의 클래스에 해당하는 추가 사례를 검색하고, 변경 사항이 도입했거나 노출시킨 모든 인스턴스에 가장 작은 수정을 적용하십시오. 관련 없는 기존 항목은 후속 작업으로 나열하십시오. 테스트가 통과함을 보여주고(STILL PASSES 발견 사항의 경우, 가드 해제 시 수정된 테스트가 실패함을 보여주고), 테스트를 유지하십시오. 새로운 잠금, 캐시, 헬퍼 또는 옵션보다는 코드를 삭제하거나 좁히는 것을 선호하십시오.
• 반대: 증거(테스트 또는 명령어 출력)와 함께 이유를 말하십시오. 코드만으로 읽은 이유(예: "그런 일은 일어날 수 없습니다")는 발견 사항을 논쟁 중으로 남기고, 기각되거나 등급이 낮아지지 않습니다.
• 사소함(nit): diff가 추가, 변경 또는 이동하는 코드에 대해, 수정이 코드를 삭제하거나, 리포지토리나 플랫폼이 제공하는 것을 재사용하거나, 코드를 Standards 또는 주변 코드에 맞게 만드는 경우 적용하고, 모든 검사를 통과하고 명확성을 길이와 교환하지 않도록 유지하십시오. 경로, 케이스, 옵션 또는 호환성 레이어를 추가하는 사소함, 수정이 사용자가 보거나 얻는 것을 변경하는 사소함, 그리고 단순히 취향에 불과한 사소함은 한 줄로 거절하십시오.
• 기존 또는 범위 외: 한 줄로 거절하십시오.

브레이커의 패치에 있는 각 테스트를 커밋하거나, 해당 조건을 다루는 기존 테스트의 이름을 지정하십시오.

루프를 끝내기 위해 동의하지 마십시오. 검사와 git diff --shortstat <base>를 다시 실행하고, 리뷰가 테스트 외부에 추가한 것 중 수용된 발견 사항에 필요하지 않은 것을 제거하고, 코드가 커지더라도 가장 작은 올바른 수정을 유지하십시오.

3. 다음 라운드

blocker 또는 should가 열려 있거나 동작 코드가 변경된 경우에만 새 라운드를 시작하십시오. 헤더를 보내되 Conditions 라인은 라운드 1 리뷰어의 조건으로 대체하고, 리뷰어 브리핑은 조건 및 스케치 라인 없이 보내며, 모든 이전 ID는 수정됨, 논쟁 중(증거 포함) 또는 기각됨(이유 포함)으로 표시하고, 마지막 라운드 이후 변경된 헝크(hunk)를 포함하십시오. 리뷰어에게 열려 있는 ID와 해당 헝크만 검토하고, 해당 헝크와 해당 호출자에 의해 변경된 동작에 대한 새로운 조건을 작성하며, 각 이전 ID를 해결됨 또는 여전히 열림으로 표시하고, 마지막 ID 이후에 새 발견 사항에 번호를 매기도록 지시하십시오. 수정이 동작, 순서 또는 소유권을 변경한 경우(예: await 이후 쓰기 이동), 동일한 헤더로 브레이커도 시작하고, 해당 헝크와 해당 호출자에 대해서만 조건을 작성하고 테스트하도록 지시하십시오.

4. 완료

열려 있는 blocker나 should가 없고 테스트, 주석 및 서식 외부의 마지막 변경 사항이 한 라운드를 통과했을 때 완료됩니다. APPROVE는 검토한 코드에 대해 루프를 조기에 종료합니다. 원인을 수정할 수 있는 COULDN'T TEST에 대해 새 브레이커를 보내십시오. E2E가 필요한 것은 작성자를 위해 나열하십시오. 라운드 3 이후에도 blocker나 should가 여전히 논쟁 중이면 dispute-round.md에서 논쟁 라운드를 실행하십시오. INCONCLUSIVE로 남는 발견 사항은 승인되지 않은 미해결 논쟁으로 루프를 종료합니다. 기각된 사소함 및 기존 발견 사항은 기각된 상태로 유지됩니다.

최종 메시지: 실행된 라운드 수, 모델, 발견 사항이 변경한 내용(각 태그된 동작, 테스트, 주장 또는 다듬기), diff 크기 전후, 테스트나 출력이 잘못되었음을 보여주어 기각된 발견 사항, 그리고 각 기각된 사소함 또는 기존 발견 사항과 그 이유를 포함합니다. 브레이커가 테스트한 것, 깨진 것, 리뷰어도 찾은 것, 그리고 커밋된 테스트가 다루지 않는 각 조건을 추가하십시오. 논쟁 라운드가 실행된 경우 각 결과를 제공하십시오. 확인되지 않은 각 위험을 평이한 언어로 나열하십시오. evals/results.jsonl이 존재하고 리뷰어 모델이 그 마지막 모델과 다른 경우, 이를 명시하고 회귀 테스트 스위트 실행(evals/README.md)을 제안하십시오.