Research harness (연구 하네스)

긴 실험 작업에서 모델이 망가지는 경우는 드뭅니다. 망가지는 것은 그 주변 공간입니다: 조용히 변경된 분할, 수기로 입력된 숫자, 훈련 세트로 새어 들어간 테스트 세트, 이미 실패한 아이디어의 여섯 번째 변형, 계정을 잠그는 폴링 루프. 이 스킬은 이러한 규칙들을 산문이 아닌 파일, 코드, 훅으로 옮겨, 에이전트 엔지니어링의 하네스/루프/그래프 프레임워크를 따릅니다.

실험에 매핑된 세 가지 계층

Harness (공간)

contract.json: 주장, 프로토콜, 게이트, 컴퓨팅 규칙. 동결됨.
CLAUDE.md: 프로젝트의 짧은 지도, 매뉴얼이 아님.
frozen/: 분할 목록, eval.py, 복사된 기준 수치. 해시 잠금 및 읽기 전용.
harness/launch.py: 실행을 시작하는 유일한 방법. GPU 허용 목록 및 유휴 규칙을 적용하고 분리형 작업을 시작합니다.
traces.jsonl: 이벤트당 한 줄.
state.json: 게이트의 결정.
lessons.md: 두 번 수정 비용이 발생한 실수.

Loop (시간)

L1 검증 루프: frozen/eval.py가 모든 실행을 평가합니다. 메트릭의 유일한 출처입니다.
종료는 코드가 결정 (harness/gate.py):
- PASS: 후보가 기준을 차이만큼 능가합니다.
- BUDGET_EXIT: 최대 변형 수에 도달.
- STALL_EXIT: N 라운드 동안 개선 없음.
- REPRO_FAIL: 기준선 재구현이 논문과 너무 차이납니다.
모델은 스스로 "완료"를 선언하지 않습니다.
L4 변경 대기: 각 작업은 runs/<id>/DONE을 마지막으로 씁니다. 반복 폴링이 아닌 하나의 백그라운드 와처로 해당 파일을 기다립니다.

Graph (경로) 의도적으로 작게 유지: 분할 → 동결 → 특징 → 기준 실행 (기준선 재구현) → 후보 변형 → 게이트 → 최종 보고. 각 화살표는 파일 계약입니다 (분할 TSV, 특징 DONE.json, 실행의 scores/).

프로젝트 설정

template/을 서버의 프로젝트로 복사합니다. 작업 코드를 src/에 복사합니다 (examples/aigi/는 AI 생성 이미지 탐지를 위한 완전한 작업 예제입니다).
template/contract.example.json에서 contract.json을 작성합니다:
- claim: 숫자가 포함된 한 문장;
- protocol: 소스 논문이 정의한 대로 정확히 작성; 명시되지 않은 모든 세부사항과 선택한 내용을 open_questions에 나열;
- gate: 참조 태그, 논문 값, 여유분, 예산;
- compute: Python 경로, 노드/GPU 허용 목록, 유휴 규칙.
paths.json (데이터셋 루트)을 작성하고 기준 수치를 frozen/baselines.json에 복사합니다. PDF에서 스크립트로 파싱하여 평균을 다시 확인하고, 절대 손으로 다시 입력하지 마십시오.
동결: python harness/freeze.py add contract.json frozen/eval.py frozen/baselines.json.
launch.py를 통해 분할을 생성하고, 매니페스트 개수를 읽은 다음 분할을 동결합니다.
Claude Code를 실행하는 머신에 가드 훅을 설치합니다:
- hooks/research_guard.py를 <project>/.claude/hooks/로 복사;
- <project>/.claude/research_guard.json을 작성하고, 원격 프로젝트 디렉토리 이름을 project_markers 항목으로 사용;
- hooks/settings.snippet.json을 <project>/.claude/settings.json에 병합.

운영 규칙

숫자는 result.json 또는 게이트 라인에서만 가져옵니다. 인용하고, 채팅에서 메트릭을 계산하거나 다시 입력하지 마십시오. eval.py가 쓴 파일에 숫자가 없다면 아직 존재하지 않는 것입니다.
launch.py를 통해서만 실행을 시작합니다. 재사용된 실행 ID, 변경된 동결 파일 및 사용 중인 GPU를 거부하고, 각 실행에 대한 코드 해시를 기록합니다.
하나의 실행, 하나의 질문. 실행 ID와 태그를 사용하여 테스트 대상을 명시합니다 (gfre_repro_s0, ml_l12-24_k256). 후보 아이디어의 변형은 게이트의 candidate_tag를 공유합니다. 디버깅이나 스모크 테스트 등 다른 모든 것은 다른 태그를 사용하여 예산을 소모하지 않도록 합니다.
게이트를 존중합니다.
- CONTINUE는 다른 변형을 시도할 수 있음을 의미합니다.
- BUDGET_EXIT, STALL_EXIT 및 REPRO_FAIL은 중지하고 증거를 사람에게 가져오라는 의미입니다. 아이디어를 여섯 번 패치하지 마십시오.
동결된 프로토콜은 프로젝트 중간에 변경되지 않습니다. 변경해야 하는 경우 (분할의 버그, 저자에게서 배운 프로토콜 세부사항), 사람이 FROZEN.sha256을 편집하고 새 동결을 시작합니다. 이전 결과는 자체 기록과 함께 results.jsonl에 남습니다.
단일 백그라운드 와처로 DONE 파일을 기다립니다. 루프 내의 모든 ssh 호출은 -o BatchMode=yes를 사용하고 종료 코드 255에서 중지됩니다.
각 실행 후에는 status.py 출력을 읽고, 원시 로그는 읽지 마십시오. log.txt는 실패 시에만 엽니다.
실수가 반복되면 lessons.md에 한 줄을 추가하고, 가능하면 검사 ( src/의 assert, 훅 규칙, 매니페스트 검사)로 전환합니다.

검토자 통과 (PASS를 신뢰하기 전)

렌즈당 하나의 검토자 하위 에이전트를 생성합니다. 각 에이전트에게 코드와 파일을 제공하고, 여러분의 결론은 제공하지 마십시오:

누수: train, val, test 파일이 겹칩니까? 제외된 패턴이 정말 제외됩니까? 테스트 레이블이 훈련 코드에 도달합니까?
프로토콜: 분할, 테스트 세트, 임계값 및 메트릭이 소스 논문 및 contract.json과 일치합니까? open_questions 선택 사항이 공개되었습니까?
공정한 비교: 기준 재구현이 허용 오차 내에 있습니까? 복사된 기준 수치가 동일한 프로토콜에서 가져온 것입니까? 다시 실행된 기준선이 표시되어 있습니까?

검토자는 그것이 변경하는 결정만큼만 가치가 있습니다. 각 렌즈는 구체적인 파일/라인 증거를 반환하거나 아무것도 반환하지 않습니다.

파일

template/                 새 프로젝트에 복사
  CLAUDE.md               지도 (제목 편집)
  contract.example.json   주장 / 프로토콜 / 게이트 / 컴퓨팅
  lessons.md
  harness/                launch.py job.sh gate.py status.py freeze.py check_frozen.py trace.py common.py
  frozen/eval.py          이진 탐지 평가자 (테스트 세트별 임계값에서 ACC + AP)
hooks/                    research_guard.py + 예제 구성 + 설정 스니펫
examples/aigi/            AI 생성 이미지 탐지: GenImage + CNNDetection 분할, CLIP 특징 캐싱,
                          GFRE 스타일 재구성 탐지기, GFRE 테이블 파서

크레딧: 하네스/루프/그래프 프레임워크는 @0xwhrrari의 "Harness, Loop and Graph" (2026년 11월)를 따릅니다.

research-harness