TL;DR

Autoresearch는 Claude Code·OpenCode·OpenAI Codex 환경에서 동작하는 자율 반복 실험 스킬로서 목표·범위·기계적 검증을 설정한 뒤 단일 변경을 반복 적용해 누적 개선을 달성한다. 내부적으로는 변경 전 커밋, 기계적 검증 실행, 개선 시 유지·악화 시 즉시 git revert의 루프를 돌리고 모든 반복을 TSV로 기록해 /autoresearch:evals로 추세 분석이 가능하다. v2.1에서 아키텍처를 분리해 호출 토큰을 약 95% 절감했고 v2.2에서 자연어 목표를 자동 분류해 오케스트레이션을 수행하는 기능이 추가되어 반복 실험의 비용 효율성과 자동화 수준을 동시에 높였다. 한편 플랫폼 스킬 방식과 기계적 검증 의존성으로 인해 실행 환경에 Claude Code·OpenCode·Codex 같은 호스트와 명확한 검증 명령이 준비되어 있어야 효과를 발휘한다.

주요 기능

• 목표 기반 루프를 통해 현재 상태와 git 히스토리를 읽고 단일 변경을 수행한 뒤 검증 명령을 실행해 결과에 따라 유지하거나 되돌리는 전형적의 자동화 루프를 제공한다. 각 반복은 하나의 원자 변경만 허용하고 변경 전 커밋을 수행하므로 실패 시 정확한 원인 추적이 가능하다. 모든 반복 결과는 TSV로 기록되어 후속 분석과 /autoresearch:evals로의 입력으로 사용된다.
• 플랫폼 포팅을 위해 Claude Code, OpenCode, OpenAI Codex용 포맷과 설치 경로를 제공하며 설치 스크립트와 수동 복사 방법을 모두 지원한다. OpenCode와 Codex 환경에서는 명령명 표기 방식이 플랫폼 규칙에 맞춰 자동 변환되므로 동일한 워크플로를 여러 호스트에서 재현할 수 있다. 이식성은 스킬 형태 파일(.claude/.opencode/.agents)과 변환 스크립트로 구현되어 있다.
• 안전 훅과 구성 가능한 Guard 메커니즘으로 위험 명령 접근, 자격 증명 노출, 강제 푸시·파일 삭제 같은 위험을 사전 차단하며 기본적으로 모든 훅이 활성화된 상태로 배포된다. 훅은 세션 시작, 도구 사용 전후, 반복 스텝 삽입 시점 등 여러 이벤트에서 동작하여 컨텍스트를 제한하고 민감 파일 접근을 차단한다. 훅 설정은 환경 변수와 .ckignore 파일로 세부 조정이 가능하다.
• 오케스트레이터 모드는 자연어 목표를 받아 목표 분류·성공 판정식 생성·체인 실행을 자동으로 수행하므로 수동 체이닝 없이 전체 파이프라인을 자동화할 수 있다. plan 명령은 자연어 목표를 기계적 검증 가능 구성으로 변환하고 handoff.json을 생성하여 이후 명령으로 연속 전달이 가능하다. 이 방식은 비숙련 사용자도 빠르게 반복 파이프라인을 기동하도록 설계되어 있다.

어떻게 동작하는가

에이전트는 초기 설정에서 범위와 기계적 검증 명령을 확정하고 현재 상태와 git 히스토리를 읽어 반복 루프를 시작한다. 각 반복에서 하나의 집중된 변경을 수행하고 변경 전 커밋을 만든 뒤 지정된 검증 명령을 실행하여 수치 기반 결과를 확인한다. 검증 결과가 개선이면 변경을 유지하고, 악화면 즉시 git revert로 되돌리며 모든 시도는 TSV 로그에 기록되어 후속 분석과 재현에 사용된다.

해결 문제

수동으로 고안·검증·롤백하던 반복 실험 절차를 자동화하여 작은 변경의 빠른 반복과 누적 개선을 가능하게 한다. 기계적 검증·자동 롤백·git 기반 기록을 결합해 실험의 가역성과 추적성을 확보하므로 대규모 실험에서 인적 실수를 줄인다. 또한 목표→구성→루프 체인을 자동화해 비코드 도메인까지 측정 가능한 작업을 확장할 수 있게 한다.

지금 주목받는 이유

v2.2.0에서 자연어 목표를 받아 자체 오케스트레이터로 자동 실행하는 기능이 추가되어 사용성 측면에서 도입 장벽을 낮추었다. v2.1.0에서 모놀리식 스킬을 분리해 호출 토큰을 약 95% 줄이는 아키텍처 개선이 비용·지연 측면의 관심을 끌었다. 또한 GitHub 상의 높은 스타 수(5300개)와 포크(392개)가 커뮤니티 관심을 반영한다.

차별점

• 원저자의 Karpathy Autoresearch 원칙을 일반 도메인(코드, 마케팅, 영업 등)으로 확장해 Claude Code, OpenCode, Codex 같은 플랫폼에서 실행 가능한 스킬 형태로 제공하는 점이 핵심 차별점이다. 플랫폼별 포맷(.claude, .opencode, .agents)과 변환 스크립트를 제공해 동일한 반복 철학을 여러 실행 환경에서 재현할 수 있다. 이로써 특정 플랫폼 종속의 제약을 낮추고 다양한 워크플로에 적용할 수 있다.
• v2.1.0 아키텍처 재구성으로 모놀리식 SKILL.md를 얇은 라우팅 파일과 자체 포함 명령 파일들로 분리하여 토큰 사용량을 대폭 줄인 점이 기술적 차이이다. 각 명령 파일이 94–120라인으로 축소되어 호출 시 검증에 필요한 토큰을 95% 절감했고 이로 인해 반복 실행 비용과 지연이 크게 줄었다. 토큰 효율성 개선은 대량 반복 실험을 경제적으로 가능하게 한다.
• 오케스트레이터 모드는 자연어 목표를 받아 자동으로 성공 판정식을 생성하고 적절한 명령 체인을 선택해 완전 자동 루프를 실행하므로 수동 체이닝 없이도 복합 작업을 끝까지 수행할 수 있다. /autoresearch:plan과 handoff.json 체인은 구성의 자동 검증과 파이프라인 연계를 보장하며 체이닝 옵션으로 세부 제어가 가능하다. 이 자동화 수준은 단일 도구에서 목표 해석부터 실행·검증·로그까지 연속적으로 처리한다.
• 보안·안전 측면에서 9개의 기본 훅과 Guard 패턴을 포함해 민감한 파일 접근과 위험 명령을 사전 차단하며 반복 중에도 Guard 명령이 실패하면 변경을 재작업하도록 설계되어 있다. 훅은 기본 활성화 상태이며 환경 변수로 개별 비활성화가 가능하고 .ckignore로 컨텍스트 범위를 조정할 수 있다. 이 구조는 자율 실행 환경에서의 안전성과 CI/CD 통합을 모두 고려한다.

사용 사례

• 테스트 커버리지·번들 크기·성능 지표처럼 측정 가능한 목표를 설정하고 단일 변경을 반복해 자동으로 개선점을 찾아내는 CI 보조 워크플로로 활용할 수 있다. Verify와 Guard를 함께 설정하면 개선 시 기존 테스트를 유지하는지를 자동으로 확인하며 실패 시 즉시 되돌려 회귀를 방지한다. TSV 로그와 /autoresearch:evals를 통해 반복 추세와 정체 구간을 감지할 수 있다.
• 코드베이스 보안 점검을 읽기 전용으로 자동화해 STRIDE·OWASP 체크와 적대적 페르소나 기반 레드팀을 수행한 뒤 구조화된 리포트를 생성하는 보안 감사 파이프라인으로 활용할 수 있다. 보안 명령은 기본적으로 읽기 전용이며 --fix 플래그로 확인된 심각도에 한해 자동 수정 옵션을 제공한다. 결과는 보안 디렉터리에 구조화되어 CI 파이프라인에 연동 가능하다.
• 문서 생성·정리·업데이트 워크플로에서 코드 스카우트→문서 생성→검증→수정 루프를 자동으로 돌려 API 레퍼런스·아키텍처 다이어그램·테스트 가이드를 생성하거나 갱신하는 데 쓸 수 있다. learn 명령은 init/update/check 모드를 제공해 초기 생성과 주기적 갱신을 모두 지원한다. 생성물은 git diff 기반으로 선택적 업데이트가 가능해 문서 품질을 유지한다.

시작하기

설치 옵션으로 npx를 통한 Claude Code 설치, 플랫폼 마켓플레이스 플러그인 설치, 또는 레포를 클론해 수동 복사하는 방법을 모두 제공한다. 제공된 ./scripts/install.sh 스크립트는 Claude Code·OpenCode·Codex용 설치를 자동화하며 플랫폼별 플래그(--claude, --opencode, --codex)를 지원한다. 설치 후에는 Claude Code 세션을 재시작해야 참조 파일이 올바르게 해석되어 모든 명령을 사용할 수 있다.

요구사항

• 실행을 위해 Claude Code, OpenCode 또는 OpenAI Codex 같은 호스트 플랫폼이 필요하며 해당 플랫폼의 스킬/플러그인 설치 권한이 있어야 한다. 레포와 설치 스크립트는 표준 git과 POSIX 쉘 환경을 전제로 하며 설치 스크립트 사용 시 로컬 셸 접근 권한이 요구된다. 자동 검증과 롤백을 위해 프로젝트 내에서 git이 초기화되어 있고 테스트·벤치마크 명령을 실행할 수 있어야 한다.

벤치마크