pi-autoresearch: AI 코딩 에이전트를 “실험 반복 엔진”으로 바꾸는 방법

AI 에이전트가 코드를 고치는 시대는 이미 시작됐습니다. 그런데 진짜 재미있는 지점은 “코드를 한 번 생성하는 것”이 아니라, 측정 가능한 목표를 놓고 수십 번 실험하며 스스로 더 나은 방향을 찾게 만드는 것입니다. pi-autoresearch는 바로 그 지점을 정면으로 겨냥한 프로젝트입니다. 터미널에서 동작하는 AI 코딩 에이전트 pi 위에 얹혀, 아이디어를 시도하고, 벤치마크를 돌리고, 개선만 남기고, 퇴행은 되돌리는 루프를 자동화합니다. (GitHub)

 

GitHub - davebcn87/pi-autoresearch: Autonomous experiment loop extension for pi

 

프로젝트 소개

pi-autoresearch는 pi용 확장(extension)입니다. 목적은 단순합니다. “무언가를 더 빠르게, 더 작게, 더 좋게 만들고 싶다”는 목표를 주면, 에이전트가 반복 실험을 수행하도록 인프라를 제공하는 것입니다. README 기준으로 이 프로젝트는 테스트 속도, 번들 크기, 빌드 시간, LLM 학습 지표, Lighthouse 점수 같은 다양한 최적화 대상을 지원하도록 설계되어 있습니다. 저장소 구조를 보면 전역 인프라 역할의 extension, 세션을 시작하고 정리하는 skills, 그리고 finalize 동작 검증용 테스트 스크립트로 구성되어 있습니다. 저장소 메타데이터 기준으로 공개 저장소이며 MIT 라이선스를 사용하고, 구현 언어는 TypeScript 68.8%, Shell 31.2%입니다. (GitHub)

이 프로젝트를 만든 주체는 GitHub 저장소 소유자인 davebcn87이고, 패키지 메타데이터와 README를 보면 @mariozechner/pi-* 계열 패키지들에 의존하는 형태라 pi 생태계 위에서 동작하도록 만들어졌다는 점이 분명합니다. 즉, 독립 실행형 벤치마크 도구라기보다 AI 코딩 에이전트 런타임에 실험 루프 기능을 주입하는 확장 모듈에 가깝습니다. (GitHub)

왜 이 프로젝트가 등장했을까

기존의 AI 코딩 워크플로는 대체로 이런 방식이었습니다. “이 코드 최적화해줘”라고 말하면, 에이전트가 몇 가지 수정을 하고 끝납니다. 문제는 여기서부터입니다. 성능 최적화나 학습 튜닝 같은 일은 한 번의 정답 생성으로 끝나지 않습니다. 작은 수정이 실제로 개선인지, 우연한 측정 잡음인지, 다른 지표를 망가뜨리지는 않았는지 계속 확인해야 합니다. README가 강조하듯 이 프로젝트는 “시도 → 측정 → 유지/폐기 → 반복”을 무한 루프로 돌리게 해 줍니다. (GitHub)

여기서 핵심은 이 저장소가 “도메인 지식”과 “실험 인프라”를 분리했다는 점입니다. README는 extension이 전역 인프라를 담당하고, skill은 어떤 명령을 돌릴지, 어떤 metric을 볼지, 어떤 파일을 건드릴지 같은 도메인별 지식을 담는다고 설명합니다. 이 분리는 꽤 영리합니다. 테스트 최적화든, 모델 학습이든, 빌드 속도 개선이든, 같은 루프 엔진을 재사용할 수 있기 때문입니다. (GitHub)

핵심 기능

1. 실험 세션 초기화

init_experiment는 세션 이름, 핵심 metric 이름, 단위, 그리고 “낮을수록 좋은지 / 높을수록 좋은지”를 설정합니다. 이 설정은 단발성 옵션이 아니라, 이후 모든 결과 기록과 대시보드 표시의 기준이 됩니다. 특히 README와 코드 모두 “최적화 대상이 바뀌면 새 baseline으로 다시 초기화”하는 흐름을 전제로 하고 있습니다. (GitHub)

2. 임의의 명령 실행과 구조화된 metric 수집

run_experiment는 쉘 명령을 실행하고, wall-clock 시간을 재고, 출력 결과를 수집합니다. 더 중요한 부분은 출력에서 METRIC name=value 형식의 구조화된 라인을 파싱한다는 점입니다. 즉, 단순히 “커맨드가 빨랐다”가 아니라 total_µs, bundle_kb, val_bpb 같은 도메인별 지표를 기계적으로 추출할 수 있습니다. 이 구조 덕분에 에이전트는 텍스트 로그 해석에 의존하지 않고 명시적 수치로 판단할 수 있습니다. (GitHub)

3. keep / discard / crash / checks_failed 상태 관리

log_experiment는 실험 결과를 기록하고, keep이면 자동 커밋하고, discard·crash·checks_failed면 변경을 되돌리는 흐름을 제공합니다. 이건 생각보다 큰 장점입니다. 많은 자동화 루프가 “좋아 보이는 변경을 계속 누적하다가 상태가 더러워지는” 문제를 겪는데, 이 프로젝트는 결과 상태를 Git 커밋과 직접 연결해 실험 브랜치를 계속 정리된 상태로 유지합니다. (GitHub)

4. 세션 지속성

README는 autoresearch.jsonl과 autoresearch.md 두 파일을 핵심으로 설명합니다. jsonl은 각 실험 결과의 append-only 로그이고, md는 목표, 범위, 시도한 것, 막힌 지점을 담는 살아있는 문서입니다. 이 설계의 의미는 분명합니다. 에이전트 컨텍스트가 초기화되거나 세션이 끊겨도, 다음 에이전트가 두 파일만 읽으면 이어서 작업할 수 있습니다. 코드에서도 before_agent_start 훅을 통해 autoresearch 모드일 때 관련 파일들을 컨텍스트에 주입하는 흐름이 보입니다. (GitHub)

5. 노이즈를 고려한 confidence score

이 프로젝트가 꽤 진지하게 만들어졌다고 느껴지는 지점은 여기입니다. README에 따르면 3회 이상 실험 후에는 Median Absolute Deviation, 즉 MAD를 이용해 세션 노이즈 바닥을 추정하고, “가장 좋은 개선폭 / 노이즈” 비율로 confidence를 계산합니다. 코드에도 computeConfidence가 실제로 현재 세그먼트의 metric 값들로 median과 MAD를 구한 뒤 baseline 대비 best kept 성능 차이를 비율화하는 구현이 들어 있습니다. 즉, “조금 빨라졌네?”가 아니라 **“이 개선이 벤치마크 흔들림보다 충분히 큰가?”**를 같이 본다는 뜻입니다. (GitHub)

6. 대시보드와 터미널 UX

이 저장소는 단순 백엔드 도구가 아니라 터미널 UX까지 챙깁니다. README에는 항상 보이는 status widget, Ctrl+X로 여닫는 확장 대시보드, Ctrl+Shift+X로 여는 풀스크린 오버레이가 설명되어 있고, 코드에서도 실제로 두 단축키가 등록되어 있습니다. 특히 풀스크린 오버레이는 실행 중인 실험의 elapsed time 스피너까지 보여 주도록 구현되어 있어서, 장시간 루프를 “지금 뭐 하는지 모르겠는 상태”로 두지 않습니다. (GitHub)

프로젝트 아키텍처 분석

이 프로젝트를 서비스 구조 관점에서 보면, 사실상 에이전트용 최적화 오케스트레이터입니다.

구조를 더 세밀하게 보면 세 층으로 나눌 수 있습니다. 첫째, pi 런타임 위에서 동작하는 extension 계층입니다. 여기서 도구 등록, 단축키, 위젯, 명령어, 상태 관리가 이루어집니다. 둘째, autoresearch-create와 autoresearch-finalize 같은 skill 계층입니다. 이들은 실제 세션을 어떻게 구성하고, 마지막에 어떻게 정리할지에 대한 운영 절차를 담습니다. 셋째, 프로젝트 작업 디렉터리에 생성되는 autoresearch.md, autoresearch.sh, autoresearch.jsonl, 선택적 autoresearch.checks.sh 같은 세션 파일 계층입니다. 즉, 런타임 상태와 파일 기반 상태를 함께 써서 에이전트 메모리 한계를 파일 시스템으로 우회하는 구조입니다. (GitHub)

여기서 extension 쪽 구현은 범용적입니다. 코드 주석과 README 모두 이 레이어를 “domain-agnostic infrastructure”로 설명합니다. 반대로 skill은 목표 수집, benchmark script 작성, finalize grouping처럼 특정 운영 지식을 담습니다. 이 경계가 명확해서, 동일한 런타임 위에 다른 실험 스킬을 올리기 좋은 형태입니다. (GitHub)

내부 동작을 개발자 시선으로 풀어보면

실제 흐름은 생각보다 단순합니다.

1. autoresearch-create가 목표와 metric을 정리합니다.
2. autoresearch.sh를 작성해 벤치마크를 표준화합니다.
3. baseline을 측정합니다.
4. 에이전트가 코드를 수정합니다.
5. run_experiment가 벤치마크를 돌립니다.
6. log_experiment가 결과를 남기고, keep이면 커밋, 아니면 되돌립니다.
7. 이력이 jsonl과 md에 쌓입니다.
8. 최종적으로 autoresearch-finalize가 kept 실험들을 논리적 묶음으로 나눠 리뷰 가능한 브랜치로 재구성합니다. (GitHub)

특히 finalize 단계가 흥미롭습니다. 단순히 “좋았던 커밋 모아두기”가 아니라, kept 실험만 골라 merge-base 기준으로 독립 브랜치를 만들고, 서로 파일이 겹치지 않도록 그룹화합니다. 이 규칙은 왜 중요할까요? AI가 만든 최적화 커밋은 대개 잡다한 실험 흔적이 많습니다. 그런데 실제 팀 협업에서는 “리뷰 가능한 단위”가 더 중요합니다. 이 skill은 실험 브랜치를 운영 브랜치로 변환하는 마지막 정리 단계를 맡습니다. 저장소에 tests/finalize_test.sh가 따로 존재하는 것도 이 부분을 꽤 중요하게 본다는 신호입니다. (GitHub)

코드로 보는 사용 방식

가장 기본적인 시작점은 이렇습니다.

pi install https://github.com/davebcn87/pi-autoresearch

설치 후에는 세션을 시작합니다.

/skill:autoresearch-create

이후 에이전트는 목표, 명령, metric, 범위를 물어보거나 문맥에서 추론한 뒤 autoresearch.md와 autoresearch.sh를 만들고 baseline을 실행합니다. README는 이 다음부터 루프가 edit → commit → run_experiment → log_experiment → keep or revert → repeat 순서로 계속된다고 설명합니다. (GitHub)

예를 들어 테스트 실행 시간을 줄이고 싶다면, 벤치마크 스크립트는 이런 식으로 설계할 수 있습니다.

#!/usr/bin/env bash
set -euo pipefail

runs=5
results=()

for i in $(seq 1 $runs); do
  start=$(python - <<'PY'
import time
print(time.time())
PY
)
  pnpm test --run >/tmp/test-output.txt 2>&1
  end=$(python - <<'PY'
import time
print(time.time())
PY
)
  dur=$(python - <<PY
start=$start
end=$end
print(end - start)
PY
)
  results+=("$dur")
done

median=$(printf '%s\n' "${results[@]}" | sort -n | awk 'NR==3')
echo "METRIC test_seconds=$median"

이 프로젝트가 강조하는 포인트는 빠르고 노이즈가 큰 벤치마크라면 여러 번 실행해서 median을 내라는 것입니다. 그래야 confidence score도 초반부터 의미 있어집니다. 즉, 이 저장소는 “벤치마크를 그냥 한 번 돌려라”가 아니라 에이전트가 믿을 수 있는 측정 체계부터 만들라는 철학을 갖고 있습니다. (GitHub)

정확성을 보장하고 싶다면 autoresearch.checks.sh도 둘 수 있습니다.

#!/usr/bin/env bash
set -euo pipefail
pnpm test --run
pnpm typecheck
pnpm lint

README에 따르면 이 파일이 존재하면 passing benchmark 뒤에 자동으로 실행되고, 실패 시 실험은 checks_failed 상태로 기록되며 keep되지 않습니다. 중요한 점은 checks 실행 시간은 primary metric에 포함되지 않는다는 것입니다. 즉, “빠르지만 깨진 최적화”를 자동으로 걸러내는 backpressure 장치입니다. (GitHub)

이 프로젝트가 잘하는 것

제가 이 저장소를 좋게 본 이유는, AI 에이전트의 약점을 꽤 정확히 찌르고 있기 때문입니다.

첫째, 컨텍스트 휘발성을 파일로 보완합니다. autoresearch.md와 autoresearch.jsonl은 단순 로그가 아니라 “에이전트의 외부 기억장치” 역할을 합니다. (GitHub)

둘째, 측정과 버전 관리를 강하게 결합합니다. keep면 커밋, 아니면 revert라는 규칙은 실험 공간을 깨끗하게 유지합니다. (GitHub)

셋째, 노이즈를 고려합니다. MAD 기반 confidence는 단순하지만 실전적인 선택입니다. (GitHub)

넷째, 범용성과 도메인 특화의 균형이 좋습니다. extension은 일반화되어 있고, skill과 autoresearch.sh가 도메인 맥락을 담습니다. (GitHub)

아쉬운 점도 있다

반대로 이 프로젝트가 만능은 아닙니다.

가장 큰 전제는 pi 생태계에 올라타야 한다는 점입니다. package.json의 peerDependencies 자체가 @mariozechner/pi-ai, @mariozechner/pi-coding-agent, @mariozechner/pi-tui에 묶여 있으므로, 범용 Node CLI로 바로 가져다 쓰는 도구는 아닙니다. (GitHub)

또 하나는 벤치마크 스크립트 품질이 성패를 좌우한다는 점입니다. 이 프로젝트는 루프 엔진을 잘 제공하지만, 잘못된 metric을 잡거나 autoresearch.sh를 부실하게 작성하면 에이전트는 열심히 잘못된 방향으로 최적화할 수 있습니다. README가 pre-check, secondary metrics, domain-specific diagnostics를 강하게 권하는 이유도 여기에 있습니다. (GitHub)

언제 쓰면 좋은가

이 저장소는 다음 같은 상황에서 특히 잘 맞습니다.

테스트 러너가 느린데 정확히 어떤 설정을 바꿔야 할지 모를 때, 프론트엔드 번들 크기를 여러 아이디어로 줄여 보고 싶을 때, 빌드 시간을 조금씩 줄이는 미세 최적화를 반복할 때, 혹은 LLM 학습/추론 파이프라인에서 특정 metric을 기준으로 실험을 계속 돌리고 싶을 때입니다. README가 예시로 든 test speed, bundle size, build speed, LLM training, Lighthouse 성능 점수는 이 도구의 사용 범위를 잘 보여 줍니다. (GitHub)

반대로 기능 구현 자체가 목표인 작업, UX 방향성이 먼저 필요한 제품 탐색, metric 정의가 불분명한 리팩터링에는 잘 맞지 않습니다. 이 도구는 본질적으로 **“최적화 함수가 정의된 문제”**에서 가장 강합니다. (GitHub)

한 줄 평가

pi-autoresearch는 AI 코딩 에이전트를 “코드 작성기”에서 “실험 반복 시스템”으로 한 단계 끌어올리는 프로젝트입니다. 핵심 가치는 화려한 모델 기술이 아니라, 측정 가능한 목표를 두고 Git, 벤치마크, 세션 문서, 터미널 UI를 하나의 루프로 묶었다는 점에 있습니다. AI가 코드를 써 주는 것보다, AI가 실험을 운영하게 만드는 쪽에 더 관심이 있다면 이 저장소는 꽤 강하게 참고할 만합니다. (GitHub)