Claude Autoresearch: 메트릭 기반 자율 반복으로, 측정 가능한 모든 작업을 개선하는 Claude Code 스킬

읽을거리&정보공유
, , , , ,
1

Claude Autoresearch: 메트릭 기반 자율 반복으로, 측정 가능한 모든 작업을 개선하는 Claude Code 스킬
Claude Autoresearch: 메트릭 기반 자율 반복으로, 측정 가능한 모든 작업을 개선하는 Claude Code 스킬1041×381 32.4 KB

Claude Autoresearch 소개

Claude Autoresearch는 Claude Code 위에서 동작하는 스킬(skill) 패키지로, 사람이 정한 단일 지표(metric)를 향해 코드·문서·설정을 자율적으로 반복 수정하도록 설계되어 있습니다. 출발점은 Andrej Karpathy가 공개한 autoresearch(:pytorch::kr: 한국어 소개 글)로, 약 630줄의 파이썬 스크립트가 하룻밤 사이 100회 가까운 실험을 돌려 ML 모델을 점진적으로 개선한 사례에서 핵심 아이디어를 가져왔습니다.

Andrej Karpathy의 원본 autoresearch가 ML 학습 루프에 한정되어 있었다면, Claude Autoresearch는 같은 원리(제약된 범위 + 기계적 지표 + 자율 반복)를 코드, 콘텐츠, 마케팅, 영업, 운영 등 측정 가능한 숫자가 있는 모든 작업으로 확장합니다. 사용자는 목표(Goal), 범위(Scope), 지표(Metric), 검증 명령(Verify) 네 가지만 정의하고, 이후 한 번의 반복(iteration)에서 한 가지 변경만 수행한 뒤 지표가 좋아지면 유지, 나빠지면 git으로 자동 되돌리는 루프를 끝까지 돌립니다.

Claude Autoresearch 동작 소개
Claude Autoresearch 동작 소개1408×768 230 KB

저장소는 6개의 슬래시 명령(/autoresearch, /autoresearch:plan, /autoresearch:security, /autoresearch:ship, /autoresearch:debug, /autoresearch:fix)과 이들을 정의한 단일 SKILL.md, 그리고 단계별 reference 문서들로 구성되어 있습니다. 플러그인 마켓플레이스 매니페스트(.claude-plugin/marketplace.json)도 함께 제공되어 Claude Code의 /plugin install 명령으로 한 번에 설치할 수 있습니다.

Claude Autoresearch의 루프 구조

Claude Autoresearch는 한 번의 반복을 다음 8단계로 정의합니다:

LOOP (FOREVER or N times):
  1. Review current state + git history + results log
  2. Pick the next change (based on what worked, what failed, what's untried)
  3. Make ONE focused change
  4. Git commit (before verification)
  5. Run mechanical verification (tests, benchmarks, scores)
  6. If improved → keep. If worse → git revert. If crashed → fix or skip.
  7. Log the result
  8. Repeat. Never stop until you interrupt (or N iterations complete).

이 루프 앞에는 일회성 셋업 단계가 있습니다. Claude가 범위 내 파일을 모두 읽어 컨텍스트를 확보하고, 사용자에게 기계적 지표를 끌어내거나 추출한 뒤, 수정 가능한 파일과 읽기 전용 파일을 구분하고, 마지막으로 현재 상태에서 검증 명령을 실행해 0번째(baseline) 측정치를 남깁니다. 모든 후속 반복은 이 baseline과의 차이로 평가됩니다.

루프 자체는 8개의 규칙으로 압축됩니다. 프로젝트에서 소개하고 있는 규칙들은 다음과 같습니다:

# 규칙
1 완료될 때까지 반복 — 무제한: 영원히. 제한됨: N번 실행 후 요약
2 쓰기 전에 읽기 — 수정하기 전에 전체 문맥 이해하기
3 반복당 하나의 변경 — 원자적 변경. 문제가 발생하면 원인을 바로 알 수 있음
4 기계적 검증만 수행 — 주관적인 "좋아 보임" 배제. 지표(Metrics)를 활용할 것
5 자동 롤백 — 실패한 변경 사항은 즉시 되돌리기
6 단순함의 승리 — 동일한 결과 + 더 적은 코드 = 유지(KEEP)
7 Git은 기억이다 — 유지하기로 한 모든 변경 사항은 커밋할 것
8 막혔을 때는 더 깊이 생각하기 — 다시 읽기, 아깝게 실패한 시도들 결합하기, 파격적인 변경 시도하기

저자는 결과 추적을 위해 한 번 반복 시 = TSV 한 줄 기록을 남기도록 강제합니다. 각 행에는 반복 번호, 커밋 해시, 측정 지표, baseline 대비 delta, 상태(baseline/keep/discard), 그리고 한 줄짜리 변경 설명이 들어갑니다. 10회마다 누적 요약이 출력되고, 유계(bounded) 루프는 종료 시 baseline에서 현재 최고치까지의 요약을 함께 보고합니다.

Claude Autoresearch가 제공하는 6개 슬래시 명령

Claude Autoresearch 소개
Claude Autoresearch 소개1536×1024 255 KB

/autoresearch가 무한 루프의 기본 진입점이라면, 나머지 명령들은 목적이 분명한 변형들입니다:

  • /autoresearch:plan: 목표를 평문으로 입력하면 위저드가 범위·지표·방향·검증 명령을 단계별로 정리한 뒤 검증 명령을 dry-run하여 실제로 숫자가 나오는지 확인합니다. README는 "범위는 파일로 해석되어야 하고, 지표는 숫자를 출력해야 하며, 검증 명령은 dry-run을 통과해야 한다"는 세 가지 게이트를 명시합니다.

  • /autoresearch:security: STRIDE 위협 모델, OWASP Top 10, 그리고 4명의 적대적 페르소나(red-team)를 사용해 자율 보안 감사를 수행합니다. 기본은 읽기 전용이며 모든 결과에는 코드 증거(file:line + 공격 시나리오)를 요구합니다. --diff(변경된 파일만), --fix(Critical/High 자동 수정), --fail-on <severity>(CI 게이트) 플래그를 지원합니다.

  • /autoresearch:ship: 코드 PR, 배포, 블로그, 마케팅 이메일, 세일즈 자료, 연구 논문, 디자인 산출물 등 9가지 유형을 자동 감지해 8단계(Identify → Inventory → Checklist → Prepare → Dry-run → Ship → Verify → Log)로 출시 흐름을 가이드합니다. 모든 체크리스트 항목이 기계적으로 검증 가능한 형태여야 한다는 점이 핵심입니다.

  • /autoresearch:debug (v1.3.0): 증상을 수집하고 오류 표면을 매핑한 뒤, 반증 가능한 가설을 하나씩 세워 검증·기각·보류로 분류합니다. README는 7가지 조사 기법(이진 탐색, 차분 디버깅, 최소 재현, 실행 추적, 패턴 검색, 거꾸로 추적, 러버덕)을 명시합니다.

  • /autoresearch:fix (v1.3.0): 깨진 상태를 받아 한 번에 하나씩 고치며, 오류 수가 0이 되면 무계 모드에서도 자동 종료합니다. --from-debug 플래그로 :debug 세션의 발견을 그대로 이어받을 수 있습니다.

추가로 모든 명령은 Guard: 옵션을 받아들입니다. Verify가 "목표 지표가 개선됐는가"라면, Guard는 "다른 게 깨지지 않았는가"입니다. 지표가 좋아져도 Guard가 실패하면 변경은 최대 2회까지 재시도된 뒤 폐기됩니다. README에 따르면 Guard 기능은 JetBrains의 @pronskiy가 PR #7로 기여했습니다.

Claude Autoresearch의 설치와 사용

저장소가 제공하는 권장 설치는 플러그인 마켓플레이스 등록을 통한 설치입니다. ~/.claude/plugins/known_marketplaces.json 에 아래 항목을 추가하고 Claude Code를 재시작한 뒤 /plugin install autoresearch@autoresearch 를 실행하면 6개 명령이 모두 활성화됩니다.

{
  "autoresearch": {
    "source": { "source": "github", "repo": "uditgoenka/autoresearch" },
    "installLocation": "<HOME>/.claude/plugins/marketplaces/autoresearch",
    "lastUpdated": "2026-03-16T00:00:00.000Z"
  }
}

플러그인을 쓰지 않는다면 저장소를 클론해 스킬과 명령 디렉토리를 직접 복사해도 됩니다.

git clone https://github.com/uditgoenka/autoresearch.git

# 프로젝트별 설치
cp -r autoresearch/skills/autoresearch   .claude/skills/autoresearch
cp -r autoresearch/commands/autoresearch .claude/commands/autoresearch

# 또는 글로벌 설치
cp -r autoresearch/skills/autoresearch   ~/.claude/skills/autoresearch
cp -r autoresearch/commands/autoresearch ~/.claude/commands/autoresearch

가장 단순한 사용 예시는 테스트 커버리지를 끌어올리는 시나리오입니다. README는 다음을 그대로 보여줍니다.

/autoresearch
Goal: Increase test coverage from 72% to 90%
Scope: src/**/*.test.ts, src/**/*.ts
Metric: coverage % (higher is better)
Verify: npm test -- --coverage | grep "All files"

/loop N /autoresearch 형태로 호출하면 정확히 N번 반복 후 요약을 출력하고 종료합니다. 무계 모드에서는 사용자가 Ctrl+C로 중단할 때까지 루프가 돌며, 커밋이 검증보다 먼저 일어나도록 설계되어 있어 마지막 성공 상태는 항상 git 안에 남습니다.

라이선스

Claude Autoresearch는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용·수정·재배포할 수 있습니다.

:house: Claude Autoresearch 공식 홈페이지

:github: Claude Autoresearch 프로젝트 GitHub 저장소

더 읽어보기



이 글은 GPT 모델로 정리한 글을 바탕으로 한 것으로, 원문의 내용 또는 의도와 다르게 정리된 내용이 있을 수 있습니다. 관심있는 내용이시라면 원문도 함께 참고해주세요! 읽으시면서 어색하거나 잘못된 내용을 발견하시면 덧글로 알려주시기를 부탁드립니다. :hugs:

:pytorch:파이토치 한국 사용자 모임:south_korea:이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일:love_letter:로 보내드립니다! (기본은 Weekly지만 Daily로 변경도 가능합니다.)

:wrapped_gift: 아래:down_right_arrow:쪽에 좋아요:+1:를 눌러주시면 새로운 소식들을 정리하고 공유하는데 힘이 됩니다~ :star_struck:

2

이거 너무 잘 쓰고 있고 잘 워킹하는 것 같습니다.

물론 처음에 방향 모호하게 주면 중간에 피봇하느라 시간을 많이 잡아먹는데요.
명령어 모호하지 않게 사전에 deep interview 여러번 돌려서 잘 정의한다음에 진행하면
목표 달성까지 아주 잘 진행합니다.

단순히 goal 쓰는 것보다도 더 작업 우회를 안해서 좋습니다. (오히려 goal은 자꾸 목적 달성 안했는데 이만하면 충분하다고 계속 그만하자고 하더라고요. 다른 분들은 어떻게 쓰시는지 궁금합니다.)
종료 조건을 더 명시적으로 잘 줘서 그런것일 수도 있습니다.

훅과 같은 결정론적인 장치를 쓰는거 같지 않던데 어떻게 이렇게 잘 동작하는지 신기하네요.

1개의 좋아요