pi-autoresearch: 코딩 에이전트가 지표를 측정하며 스스로 최적화를 반복하는 pi 확장

9bow · 7월 30, 2026, 11:30오전

pi-autoresearch 소개

pi-autoresearch는 터미널에서 동작하는 AI 코딩 에이전트 pi에 자율 최적화 루프를 붙여 주는 확장입니다. 아이디어를 하나 적용하고, 벤치마크로 측정하고, 개선된 것은 남기고 나빠진 것은 되돌리고, 이 과정을 사람이 멈추라고 할 때까지 반복하는 흐름을 도구와 워크플로로 제공합니다. 프로젝트는 스스로를 karpathy/autoresearch에서 영향을 받았다고 밝히고 있으며, 최적화 대상이 무엇이든 같은 구조가 적용된다는 점을 전제로 설계되어 있습니다.

이 확장이 겨냥하는 문제는 "무엇을 바꿀지"가 아니라 "바꾼 것이 정말 나아졌는지"입니다. 성능 개선 작업에서 사람이 지치는 지점은 아이디어를 떠올리는 쪽이 아니라, 매번 같은 벤치마크를 돌리고 숫자를 적어 두고 커밋과 되돌리기를 반복하는 쪽입니다. pi-autoresearch는 그 반복을 도구 호출로 만들고, 결과를 프로젝트 안의 파일에 계속 쌓아 에이전트가 문맥을 잃어도 이어서 일할 수 있게 합니다.

측정 대상은 도메인을 가리지 않습니다. 저장소가 예시로 드는 조합은 테스트 실행 시간(초, 낮을수록 좋음), 번들 크기(KB), LLM 학습 지표(val_bpb), 빌드 시간, Lighthouse 성능 점수입니다. 본 게시물에서는 pi-autoresearch의 루프 구조, 확장과 스킬의 역할 분담, 세션이 재시작을 견디는 방식, 잡음과 실제 개선을 구분하는 신뢰도 점수, 그리고 실험 결과를 검토 가능한 브랜치로 정리하는 절차를 정리합니다.

pi-autoresearch의 자율 실험 루프

루프 한 바퀴는 코드 수정에서 시작합니다. 에이전트가 아이디어를 적용하고 커밋한 뒤 run_experiment로 벤치마크 명령을 실행하면, 도구가 벽시계 시간을 재고 출력을 수집합니다. 그다음 log_experiment가 결과를 기록하면서 자동으로 커밋하고 위젯과 대시보드를 갱신합니다. 마지막으로 결과를 채택하거나 되돌리고, 곧바로 다음 바퀴로 넘어갑니다. 사람이 끼어들지 않으면 이 순환은 멈추지 않습니다.

세션 설정은 init_experiment가 한 번만 처리합니다. 이름과 지표, 단위, 그리고 지표가 높을수록 좋은지 낮을수록 좋은지의 방향을 여기서 정합니다. 실행 중에는 Escape로 언제든 끼어들어 요약을 요청할 수 있고, /autoresearch off로 모드를 벗어나면 자동 재개가 멈추지만 기록 파일은 그대로 남습니다.

작업이 실제로 어떻게 쌓이는지는 저장소가 공개한 위젯 화면에서 확인할 수 있습니다. 아래 화면은 49회 실행 중 47회를 채택하고 2회를 되돌린 세션으로, 기준선 7,374μs에서 시작해 46번째 실행에서 4,331μs까지 내려온 상태(-41.3%)를 보여 줍니다.

표의 각 행에는 커밋 해시와 지표값, 상태(채택 또는 되돌림), 그리고 그 실행에서 무엇을 시도했는지를 적은 설명이 함께 놓입니다.

pi-autoresearch의 확장과 스킬 분담

pi-autoresearch는 도구를 제공하는 확장과 도메인 지식을 담는 스킬을 분리합니다. 확장은 어떤 최적화 대상에도 공통으로 쓰이는 기반이고, 스킬은 이번 세션에서 무엇을 어떻게 재는지를 결정합니다. 이 분리 덕분에 확장 하나가 여러 도메인을 그대로 지원합니다.

┌──────────────────────┐     ┌──────────────────────────┐
│  Extension (global)  │     │  Skill (per-domain)       │
│                      │     │                           │
│  run_experiment      │◄────│  command: pnpm test       │
│  log_experiment      │     │  metric: seconds (lower)  │
│  widget + dashboard  │     │  scope: vitest configs    │
│                      │     │  ideas: pool, parallel…   │
└──────────────────────┘     └──────────────────────────┘

스킬은 세 가지가 제공됩니다. autoresearch-create는 목표와 명령, 지표, 범위에 해당하는 파일을 묻거나 문맥에서 추론한 뒤 브랜치를 만들고 세션 파일을 작성하고 기준선을 측정해 곧바로 루프를 시작합니다. autoresearch-finalize는 실험이 뒤섞인 브랜치를 논리적 변경 단위별로 독립 브랜치로 갈라 줍니다. 선택 사항인 autoresearch-hooks는 반복 경계에서 실행할 스크립트를 작성하도록 돕고, 저장소의 skills/autoresearch-hooks/examples/에 외부 검색, 학습 기록, 알림, 아이디어 순환 등 열 개의 참조 스크립트가 함께 들어 있습니다.

pi-autoresearch의 세션 파일 구조

세션과 관련된 파일은 작업 디렉토리 최상위의 .auto/ 폴더 한 곳에 모입니다. 되돌리기를 반복하는 루프에서 보존해야 할 대상을 폴더 하나로 좁히기 위한 선택입니다.

파일	역할
`.auto/prompt.md`	목표와 지표, 범위 파일, 시도한 내용을 담은 세션 문서
`.auto/measure.sh`	사전 점검과 작업 실행을 거쳐 `METRIC name=number` 줄을 출력하는 벤치마크 스크립트
`.auto/log.jsonl`	모든 실행을 한 줄씩 덧붙이는 기록
`.auto/checks.sh`	선택 사항. 테스트·타입·린트 같은 정확성 점검
`.auto/hooks/`	선택 사항. 반복 전후에 실행되는 스크립트

이 구조가 노리는 효과는 세션의 지속성입니다. .auto/log.jsonl은 재시작을 견디고, .auto/prompt.md는 무엇을 시도했고 어디가 막다른 길이었는지를 담아 문맥이 초기화된 뒤에도 새 에이전트가 이어받을 수 있게 합니다. 기록이 브랜치별로 분리되므로 브랜치마다 별도 세션을 갖습니다.

긴 루프에서 특히 중요한 부분은 자동 압축(compaction)과의 관계입니다. pi가 오래된 대화를 요약해 압축하면, 그로 인해 생기는 유휴 상태를 pi-autoresearch가 감지해 에이전트에게 .auto/prompt.md와 .auto/log.jsonl의 끝부분, .auto/ideas.md, git log를 다시 읽으라고 재요청합니다. 요약에서 살아남은 내용에 의존하지 않고 파일을 원본으로 삼아 다시 채우는 방식입니다.

pi-autoresearch의 신뢰도 점수

벤치마크가 흔들리는 대상, 예를 들어 학습 지표나 Lighthouse 점수에서는 개선처럼 보이는 값이 실제로는 잡음일 수 있습니다. pi-autoresearch는 한 세션에서 3회 이상 실험이 쌓이면 신뢰도 점수를 계산해 이 구분을 돕습니다.

계산 방식은 현재 구간에 있는 모든 지표값의 중위 절대 편차(Median Absolute Deviation)를 잡음 추정값으로 쓰고, 최고 개선폭을 그 값으로 나눈 비율을 점수로 삼습니다. 점수 2.0배는 최고 개선폭이 잡음 수준의 두 배라는 뜻입니다.

신뢰도	표시	의미
2.0배 이상	초록	개선이 실제일 가능성이 높음
1.0~2.0배	노랑	잡음보다는 크지만 판단이 애매함
1.0배 미만	빨강	잡음 범위 안이므로 재실행 고려

점수는 위젯과 전체 화면 대시보드, log_experiment 출력에 표시되고 실행마다 .auto/log.jsonl에 저장됩니다. 다만 이 점수는 참고용이며 자동으로 결과를 버리지 않습니다. 신뢰도가 낮으면 재실행을 권하되 채택과 폐기의 최종 판단은 에이전트가 합니다.

정확성 쪽 안전장치는 .auto/checks.sh입니다. 이 파일을 두면 벤치마크가 정상 종료한 뒤마다 테스트와 타입 검사가 실행되고, 실패한 실험은 checks_failed 상태로 기록되며 커밋 없이 변경이 되돌려집니다. 점검에 걸린 시간은 주 지표에 반영되지 않고, 기본 300초의 별도 제한 시간을 가집니다. 파일이 없으면 루프는 이전과 똑같이 동작합니다.

pi-autoresearch 설치와 사용 절차

설치는 pi의 패키지 설치 명령 한 줄입니다.

pi install npm:pi-autoresearch

사전 준비물은 pi 설치와 사용할 LLM 제공자의 API 키입니다. 설치 후에는 스킬을 호출해 세션을 시작합니다.

/skill:autoresearch-create

진행 상황은 편집기 위에 항상 보이는 위젯, Ctrl+Shift+F로 열리는 전체 화면 대시보드, 그리고 /autoresearch export로 열리는 브라우저 대시보드에서 확인합니다. 실험이 끝난 뒤 /skill:autoresearch-finalize를 호출하면 에이전트가 .auto/log.jsonl을 읽어 채택된 실험을 논리적 단위로 묶고, 그 묶음을 사용자에게 확인받은 다음 병합 기준점에서 시작하는 독립 브랜치를 만듭니다. 각 커밋 메시지에는 지표 개선폭이 함께 들어가며, 묶음끼리 파일을 공유하지 않도록 나누기 때문에 브랜치를 따로 검토하고 병합할 수 있습니다.

자율 루프는 토큰을 계속 소모하므로 비용 상한도 함께 안내합니다. 제공자 쪽에서 키별·월별 예산을 설정하는 방법과, .auto/config.json의 maxIterations로 세션당 실험 횟수를 제한하는 방법 두 가지입니다.

{
  "workingDir": "/path/to/project",
  "maxIterations": 50
}

maxIterations에 도달하면 에이전트는 중단하라는 지시를 받고, 새 구간이 초기화될 때까지 실험을 더 실행하지 않습니다. workingDir는 파일 입출력과 명령 실행, git 작업이 이루어질 디렉토리를 세션 작업 경로와 다르게 지정할 때 씁니다.

pi-autoresearch의 라이선스

pi-autoresearch는 MIT 라이선스로 공개되어 있어 개인 및 상업적 목적으로 자유롭게 사용할 수 있습니다.

pi-autoresearch 프로젝트 GitHub 저장소

더 읽어보기

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

파이토치 한국 사용자 모임이 정리한 이 글이 유용하셨나요? 회원으로 가입하시면 주요 글들을 이메일로 보내드립니다! 텔레그램(Telegram)이나 Slack/Discord/Teams/Dooray/GoogleChat 등으로도 새 글 알림을 받으실 수 있습니다.

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