drivelineresearch/autoresearch-claude-code

개요

autoresearch‑claude‑code 는 Anthropic의 Claude Code 또는 OpenAI의 Codex 에이전트로 자동 리서치 루프를 실행할 수 있는 Python 기반 실험 프레임워크입니다. 에이전트에게 구체적인 목표(예: "테스트 스위트 런타임 줄이기"), 고정 벤치마크, 수정할 수 있는 소스 파일 목록을 제공합니다. 프레임워크는 임시 Git 브랜치를 만들고, 에이전트를 턴마다 실행하며, 각 변경의 영향을 측정하고, 통계적으로 유의미한 개선을 보이는 편집만 자동으로 커밋하면서 사용자 정의 예산(최대 실행, 시간 또는 계산) 내에 유지합니다. 모든 상태는 JSONL 파일에 저장되며 검사하거나 롤백할 수 있습니다.

대상 독자

코드 생성 에이전트가 기존 코드베이스를 얼마나 잘 최적화할 수 있는지 평가하려는 연구자 또는 엔지니어.
사용자 지정 서버나 MLOps 파이프라인을 구축하지 않고 재현 가능하고 예산이 제한된 "자기 개선" 루프가 필요한 팀.
구체적인 소프트웨어 작업에서 Claude Code 또는 Codex의 실제 영향을 측정하는 데 관심이 있는 모든 사람.

핵심 개념

개념	기능
목표 정의	짧은 자연어 명령(예: `테스트 스위트 런타임 최적화`)이 에이전트에게 최적화할 대상을 알려줍니다.
벤치마크	숫자 메트릭을 반환하는 결정적 스코어러 스크립트(예: 테스트 러너).
예산	턴 수, 총 벽시계 시간, 선택적으로 Codex 호출에 대한 제한.
노이즈 처리	프레임워크는 기준 실행에서 측정 노이즈를 보정하고 노이즈 플로어를 넘어 메트릭을 개선하는 변경만 수락합니다.
원자적 상태	모든 실험 메타데이터는 JSONL에 원자적으로 기록됩니다. 동시 쓰기는 손상을 방지하기 위해 잠깁니다.
일시 중지 / 재개	센티널 파일(`.autoresearch‑off`)로 루프를 일시 중지할 수 있습니다. 시스템은 마지막 유효한 체크포인트에서 재개할 수 있습니다.
잠긴 스코어러	`--protect`로 나열된 파일은 각 턴마다 해시됩니다. 에이전트는 이를 수정할 수 없으므로 평가 스크립트의 우발적 손상을 방지합니다.

설치(빠른 시작)

# 리포지토리 클론
gh repo clone drivelineresearch/autoresearch-claude-code
cd autoresearch-claude-code

# Claude 스킬(기본) 또는 Codex 스킬 설치
./install.sh --claude   # ~/.agents/skills/autoresearch 아래에 Claude 후크 설치
# 또는
./install.sh --codex    # Codex 스킬 설치
# 또는 둘 다 설치
./install.sh --all

스크립트는 심볼릭 링크를 만듭니다. 링크가 유효하게 유지되도록 체크아웃을 유지하세요. 해당 ./uninstall.sh 플래그로 제거합니다.

루프 실행(Claude 예시)

초기화 – 대상 프로젝트에서 스킬 명령을 실행합니다:
```
$ autoresearch optimize test suite runtime with at most 20 runs
```
에이전트는 autoresearch 워크트리를 만들고 기준을 기록한 다음 검토를 기다리며 일시 중지합니다.
검토 – status 또는 report를 확인하여 기준 메트릭을 확인합니다.

재개 – 자동 루프를 시작합니다:

python3 ~/.agents/skills/autoresearch/scripts/claude_loop.py \
  --max-turns 20 --max-seconds 3600 --protect path/to/scorer.py

스코어러가 의존하는 파일에 따라 --protect를 조정합니다.

모니터링 – 루프는 턴 요약을 출력합니다. .autoresearch‑off를 만들어 중단할 수 있습니다.
결과 – 예산이 소진된 후 autoresearch report는 유지된 커밋과 최종 메트릭을 보여줍니다.

동일한 워크플로는 Codex에서도 작동하며 codex_loop.py 스크립트와 Codex IDE 내의 autoresearch CLI를 사용합니다.

사용 사례 예시

리포지토리에는 야구 패스트볼 속도를 예측하는 OpenBiomechanics 데모가 포함되어 있습니다. 다음을 보여줍니다:

METRIC name=R2를 출력하는 사용자 지정 스코어러를 정의하는 방법.
uv sync --extra …를 통해 선택적 백엔드(torch, boost, tabpfn 등)를 연결하는 방법.
전체 검색 기록을 기록하는 재현 가능한 실행(./autoresearch.sh 42).

개발 및 테스트

핵심 단위 테스트는 Python 표준 라이브러리만 필요합니다: python -m unittest discover -s tests -v.
예제 테스트는 과학 패키지가 필요합니다. uv sync --project examples 후에 실행할 수 있습니다.
셸 스크립트는 shellcheck로 린트됩니다.
CI는 Linux/macOS에서 실행되며 핵심 및 예제 스위트를 모두 검증합니다.

제한 사항 및 주의 사항

노이즈 모델은 단순하며 개선이 측정된 기준 분산을 초과하는지만 확인합니다. 통계적 유의성 테스트를 제공하지 않습니다.
프레임워크는 에이전트를 샌드박스하지 않습니다. "잠긴 스코어러" 해시와 Git 브랜치 격리에 의존하여 원래 코드를 안전하게 유지합니다.
예산은 턴과 초로 계산되며 토큰 사용량이나 금전적 비용이 아닙니다.
OpenBiomechanics 예제의 역사적 R² 점프(0.44 → 0.78)는 데이터 누출을 사용했습니다. 리포지토리는 이것이 검증된 주장이 아니라고 명시합니다.
Claude Code와 Codex만 지원됩니다. 새 에이전트를 추가하려면 스킬 래퍼와 후크 스크립트를 작성해야 합니다.

라이선스

MIT – 코드를 자유롭게 사용, 수정, 재배포할 수 있습니다.

결론: autoresearch-claude-code는 엄격한 예산 및 안전 제약 하에서 Claude Code 또는 Codex가 코드베이스를 반복적으로 개선하도록 하는 즉시 사용 가능한 재현 가능한 루프를 제공하며, 내장 로깅, 일시 중지/재개, 기준 노이즈 처리를 갖추고 있습니다.