Autoresearch
한 번에 가설 하나를 바꾸고 실제 결과로 유지하거나 되돌린다. 문서 형식 점수나 같은 입력의 연속 고득점은 개선의 증거를 대신하지 않는다. 이미 정상인 스킬에 규칙을 더하는 것이 목적은 아니다.
사용법
기본 설치에서는 카탈로그의 정확한 SKILL.md를 직접 읽고 아래 인자 의도를 적용한다.
다음 표기는 실행 파일이 아닌 route intent다. --include-source-only-skills로 활성화한 환경에서만
앞에 /를 붙인 compatibility alias를 사용할 수 있다.
autoresearch humanizer --input sample.md --rounds 20
autoresearch humanizer --checklist my-checklist.md
autoresearch --scan
autoresearch --scan --auto
| 인자 | 기본값 | 의미 |
|---|---|---|
<skill-name> |
없음 | 승인된 개선 대상; scan에서는 생략 가능 |
--scan |
꺼짐 | 스킬 문서의 조사 후보 수집; 실제 품질 판정 아님 |
--auto |
꺼짐 | 승인된 범위에서 scan 후보의 기준점부터 순서대로 확인 |
--input |
과업에 맞게 생성 | 수정에 사용할 개발 사례 |
--holdout |
별도 입력 1~2개 | 수정에 쓰지 않을 평가 사례 경로; 개선 행위자는 내용을 읽지 않음 |
--checklist |
과업 기준에서 작성 | 관측 가능한 결과 기준, 보통 3~6개 |
--rounds |
20 | 후보 수정 라운드의 상한; 평가·재확인을 포함한 시간/토큰 상한도 시작 전에 정함 |
--target |
95 | 개발 점수 목표(%); 최종 채택 조건과 별개 |
--streak |
3 | 개발 목표의 연속 달성 횟수; 최종 평가로 넘어가는 신호 |
명시된 대상·권한·상한을 유지한다. 이미 승인받은 개선 범위를 다시 확인하지 않는다. 대상이 불명확하거나 실행에 필요한 권한이 없을 때만 해당 부분을 확인한다.
Scan 모드
scan은 어떤 문서를 먼저 살펴볼지 정한다. 발견한 파일 수를 사용하며 고정 스킬 수를 가정하지 않는다. 정적 문서 특성은 실제 실패 가능성을 찾는 단서다. 점수가 낮다는 이유만으로 규칙·예시·금지 목록을 추가하거나, 그 요소를 제품 출력에 요구하지 않는다.
승인된 범위의
*/SKILL.md를 수집하고 다음 신호를 기록한다.신호 확인할 것 목적과 적용 조건 실제 과업과 명확히 연결되는가 지식·결정 기준 기본 능력에 없는 판단이나 필요한 계약이 있는가 예시·필수 필드 실제로 모호한 부분을 해소하는가; 불필요하면 없어도 됨 조건과 예외 관측 가능한 조건으로 행동이 달라지는가 참조·자원 필요한 파일·스크립트가 해석되고 실행 가능한가 분량·중복 같은 판단을 반복하거나 무관한 절차를 불러오는가 신호 / 의심되는 과업 실패 또는 비용 / 확인할 사례로 조사 우선순위를 제시한다. 이전 도구가 숫자 점수를 주었다면static-scan으로 표시하고 실행 점수와 합치지 않는다.--auto는 후보마다 아래 기준점 측정부터 진행한다. 기준점이 요구를 충족하고 측정된 비용 문제도 없으면 원본을 유지하고 다음 후보로 간다. 실행 증거가 없으면 미검증으로 남긴다. 체크리스트 수를 채우려고 범용 규칙을 보충하지 않는다.
정밀한 문서 검토가 필요하면 전역 SKILLS-CATALOG.md에서 첫 셀이 정확히 skill-judge인 단 하나의
행과 읽을 경로를 해석해 SKILL.md 전체를 직접 읽는다. 해석 실패는 NOT RUN이다.
문서 검토 점수 역시 행동 개선이나 런타임 검증의 증거는 아니다.
Phase 0: 준비
- 상위 하네스가 준 정확한 대상 파일을 사용한다. 이름만 받았다면 프로젝트 실제 파일 → 현재 CLI
활성 루트 → 카탈로그의 정확한 source-only
읽을 경로순으로 해석하고 frontmatter 이름을 확인한다. - 기존 실행을 재개할 때는 그 실행의 경로·기준점·상한을 이어받는다. 새 실행은 고유한
.autoresearch/<skill-name>/<run-id>/를run_dir로 만들고 이전 결과를 덮어쓰지 않는다. - 수정 전에 과업 결과 기준, 필수 제약·회귀 검사, 개발 사례, 별도 평가 사례, 실행 상한을 고정한다.
비용을 개선하려면 길이·시간·토큰 중 비교할 지표와 허용 변동도 미리 정한다. 측정하지 않은 비용은
unknown이다. 평가를 본 뒤 기준·기대값·상한을 바꾸지 않는다. 사용자 부담을 줄이는 변경은 불필요한 질문·반복 설명·재승인 대기를 관찰한다. 필요한 결정이나 권한 확인의 누락은 개선으로 세지 않는다. - 대상 파일과 필요한 참조의 해시를 기록하고 원본을
run_dir/original/에 보존한다. 실험은run_dir/candidate/의 사본에서 한다. 프로젝트 전체 stash/reset을 사용하지 않는다. 기존 실행이 이미 대상을 바꿨다면 원본 백업과 마지막 기록 해시를 먼저 확인한다. - 별도 평가 입력 1~2개를 개발 사례와 같은 유형·다른 내용으로 준비한다. 생성·보관·실행은
격리된 쓰기 가능 네이티브 작업자에게 맡긴다. 입력은
run_dir/holdout/set-N/inputs/, 출력은 같은 set의outputs/baseline/·outputs/candidate/에 둔다.
평가 시작점
기본은 대상 스킬을 읽은 뒤 과업을 수행하는 본문 수행 시험이다. 호출 누락·과호출·내부 참조 연결을 바꾸는 경우에만 진입 시험을 선택한다. 진입 시험은 실제 사용자 요청과 해당 런타임의 카탈로그 또는 상위 하네스에서 시작하며 대상 본문·정답 경로를 미리 주지 않는다. 읽은 파일·선택한 경로·실제 결과로 필요한 참조 로딩과 불필요한 진입 방지를 함께 확인한다. 원본과 후보에는 같은 등록 상태·입력·환경을 쓰며 source-only를 시험 편의상 활성 등록하지 않는다.
본문 수행 통과를 진입 성공으로, 경로 문자열의 정적 확인을 실제 로딩으로 보고하지 않는다. 관련 없는 변경에서 두 시험을 모두 강제하지 않으며, 기존 평가 상한·격리·holdout 규칙을 유지한다.
실행자·채점자 격리
- 실행자는 선택한 평가 시작점과 입력만 받는다. 본문 수행 시험에는 대상 스킬을 제공하고, 진입 시험에는 위 진입 자료만 제공한다. 체크리스트·기대 판정·다른 실행의 결과는 전달하지 않는다. 대상 스킬과 로그는 읽기 전용이며 지정 출력·임시 작업공간만 수정한다.
- holdout 담당은 채점하지 않는다. 모든 메시지와 자동 완료 요약은
쓴 파일 경로 + done만 반환한다. 메인은 그 경로를 채점자에게 전달하며 입력·출력을 열지 않는다. - 채점자는 기준·입력·실제 출력과 실행 증거만 읽고 스킬·수정 의도·최적화 로그는 읽지 않는다. 메인에는 기준별 판정과 집계만 반환하며 입력·출력의 주제·인용·요약을 포함하지 않는다.
- 기준점과 후보는 같은 모델·설정·환경·입력·채점 기준으로 실행하되 각 실행의 문맥은 새로 시작한다. 격리는 지시 기반이며 OS 보안 경계로 주장하지 않는다.
- 위임이 없으면 메인 컨텍스트에서 순차 실행하고
isolation: main-context로 기록한다. 이런 실행은 블라인드·독립 검증이라고 보고하지 않으며, 의미 판단의 일반화 증거가 부족하면deferred로 둔다. 모델 패밀리가 같다는 사실과 컨텍스트 격리 여부도 각각 기록한다.
Phase 1: 기준점 측정
- 원본 스킬로 개발 사례를 실제 실행하고 명령·출력·변경 파일을 남긴다. 가능한 기계적 검사는
코드로 확인한다. 의미 판단은 기준별
PASS | FAIL | UNCERTAIN | NOT RUN과 근거로 기록한다. - 점수는
PASS 수 / 전체 평가 수 × 100으로 계산한다(예: 3/5 = 60%). UNCERTAIN·NOT RUN을 통과에 합산하거나 분모에서 지우지 않는다. 필수 제약·회귀 실패는 점수와 별도로 유지한다. - 실제 과업 실패 또는 사전에 정한 지표의 측정된 비용 문제가 없으면 원본을 유지한다.
status: rejected; reason: no demonstrated need; target: unchanged로 기록하고 수정 루프를 끝낸다. - 개선할 문제가 있으면 holdout 담당이 원본으로 별도 평가 사례도 실행하고 채점자가 기준점을 남긴다. 같은 set에서 비교할 기준점·후보의 입력과 실행 조건을 고정한다.
Phase 2: 후보 수정·실행
남은 상한 안에서 개발 사례의 실패 원인 하나를 고르고 후보 사본에 변경 하나를 적용한다. 문서의 형태는 관찰한 실패에 맞춘다.
| 관찰한 실패 | 수정 형태 |
|---|---|
| 알고 있는 필수 규칙을 압박에서 생략 | 실제 생략을 겨냥한 금지·중단 조건 |
| 필요한 정보는 있지만 출력이 장황하거나 순서가 틀림 | 산출물의 부분·순서를 보여 주는 짧은 작성법 |
| 이미 만드는 산출물에서 필수 요소 누락 | 기존 템플릿의 필수 필드 |
| 특정 상황에서만 다른 행동이 필요 | 관측 가능한 조건과 그때의 행동 |
| 근거 문맥이 부족함 | 필요한 입력·참조를 작업 계약에 연결 |
| 중복 지시가 비용을 늘림 | 불필요한 지시 제거와 회귀 확인 |
개발 입력의 문장을 그대로 좋은 예시로 복사하지 않는다. 변경 후 같은 개발 사례와 필수 회귀를 실제 실행하고 원본·직전 후보와 비교한다.
- 필수 실패·회귀가 생기면 평균 점수가 올라도 해당 후보를 버린다.
- 개발 점수가 오르면 탐색 후보로 보존한다. 이 보존은 최종 채택이 아니다.
- 점수가 같으면 사전 비용 지표의 개선이 있거나 다음에 검증할 구체적 가설이 있을 때만 탐색을 계속한다. 근거 없는 동점 변경을 누적하지 않는다. 최종 동점 채택은 아래 게이트를 따른다.
- 점수가 떨어지면 직전 탐색 후보로 되돌린다. 원본·이미 채택된 파일과 사용자 변경은 보존한다.
--target이상이--streak회 연속이고 필수 실패가 없으면 최종 평가로 간다. 상한 소진은stop_reason: exhausted이며 성공이 아니다. 평가할 예산도 없으면deferred로 끝낸다.
최종 평가와 채택
후보의 개발 점수와 streak만으로 대상을 갱신하지 않는다. 수정에 쓰지 않은 평가셋에서 원본과 후보를 같은 조건으로 실제 실행하고, 필수 회귀와 사전에 고정한 과업·비용 기준을 함께 판정한다.
평가셋이 개발용으로 바뀌는 시점
다음 중 하나면 해당 set을 최종 평가에서 제외하고 기록을 보존한다.
- 입력·출력·주제가 개선 행위자에게 노출됨:
holdout: leaked. - 점수 또는 실패 항목만이라도 보고 후보를 수정함:
holdout: promoted-to-development. 본문을 읽지 않았어도 피드백을 수정에 썼으면 개발용이다.
새로운 set을 격리된 담당이 만들고 원본과 수정된 후보 둘 다 새 set에서 실행한다.
새 후보만 새 입력에서 실행하거나, 옛 기준점과 새 입력 점수를 비교하지 않는다.
새 입력·양쪽 실행을 위한 예산이 부족하면 status: deferred로 끝내고 원본/직전 채택본을 유지한다.
새 set을 만들었다는 사실로 라운드·시간·토큰 상한을 초기화하지 않는다.
후보를 바꾸지 않은 상태에서 평가 결과 자체의 변동이 의심되면 남은 예산 안에서 동일 조건의 재확인을 1회 할 수 있다. 최초 결과도 보존하며 좋은 결과만 선택하지 않는다.
최종 상태
| 상태 | 조건 | 대상 파일 |
|---|---|---|
accepted |
별도 평가에서 기준점 대비 유효한 개선, 목표 충족, 필수 제약·회귀 모두 통과 | 적용 직전 해시 확인 후 후보 반영 |
rejected |
회귀, 개선 효과 없음, 또는 목표 미달을 확인 | 원본/직전 채택본 유지 |
deferred |
증거 부족·평가 오염·불확실성·상한 소진·동시 수정으로 판정/적용 보류 | 원본/직전 채택본 유지; 동시 변경은 덮어쓰지 않음 |
not-run |
필수 실행을 시작할 수 없음 | 원본 유지; 이유 명시 |
- 동점은 자동 채택하지 않는다. 품질 회귀 없이 사전에 지정한 비용 지표가 허용 변동을 넘게 개선된 경우만 accepted가 가능하다. 비용 unknown이나 문서 형식 점수 상승은 그 근거가 아니다.
- 필수 실패, UNCERTAIN, NOT RUN은 평균·다른 성공·높은 streak로 상쇄하지 않는다. 명령 실행·설치 확인·정적 검사·의미 판단의 범위를 구분한다.
- holdout 점수가 개발 점수보다 20%p 이상 낮으면 과적합 신호를 기록한다. 추가 수정은 그 set을
개발용으로 전환한 뒤에만 하며, 최종 판정에는 새 set이 필요하다. 기준점보다 낮으면 회귀다.
재확인해도 낮으면
status: rejected; stop_reason: overfit으로 끝낸다. - 적용 직전에 실제 대상 해시가 시작 시점과 같은지 확인한다. 다르면 덮어쓰지 않고 deferred. 이전 실행이 직접 대상을 수정한 경우에도 마지막 기록 해시와 같을 때만 이번 변경을 복구한다. 해시가 다르거나 원본이 불명확하면 사본과 차이를 보존하고 복구를 보류한다.
Phase 3: 결과 기록
run_dir/autoresearch-log.md에 원본·후보 해시, 고정 기준과 입력 set ID, 조건·상한, 실제 실행 명령,
기준별 판정·분자/분모, 비용(미측정은 unknown), 채점자·격리 여부, 변경·되돌림·평가셋 전환 이력,
최종 status·stop_reason·적용 여부·재시도 조건을 남긴다. 과거 결과를 새 실행으로 세지 않는다.
예: 개발 기준점 3/5 = 60%, 후보 5/5 = 100%를 3회 연속 달성했으면 목표 95%의 평가 진입 조건은 충족한다. 그러나 별도 평가가 4/5 = 80%라면 accepted가 아니다. 남은 예산 없이 그 피드백으로 후보를 다시 고쳤다면 최종 상태는 deferred이며 새 평가가 필요하다.
상위 하네스에는 최종 상태, 적용한 파일·해시, 실제 개선 근거, 검증 범위와 남은 한계를 반환한다.
체크리스트 작성
관측 가능한 과업 결과를 기준으로 한다. 보통 3~6개로 합치되 필수 제약을 개수에 맞춰 버리거나 부족한 개수를 채우려고 규칙을 만들지 않는다. 제약·회귀 검사는 따로 보존한다.
| 모호하거나 형식만 보는 질문 | 결과를 보는 질문 |
|---|---|
| NEVER 목록이 있는가? | 재현한 거부 조건에서 쓰기·외부 호출이 발생하지 않는가? |
| 정해진 탐색 순서를 따르는가? | 기존 구현을 찾아 재사용하고 변경 범위를 지켰는가? |
| 모든 함수가 20줄 이하인가? | 지정 입력에서 정확한 결과와 오류를 반환하며 기존 회귀가 없는가? |
글쓰기·설계처럼 의미 판단이 필요한 기준도 실제 산출물을 보고 판정하고 근거를 남긴다. 특정 표기·길이·서술 방식은 사용자 과업에서 요구하거나 측정할 비용과 연결될 때만 기준으로 둔다.
관련 모듈과 출처
skill-evolve: 정제된 관찰을 과업 기준과 개선 후보에 연결한다.skill-judge: 문서 품질을 검토하며 실제 과업 실행을 대신하지 않는다.auto-continue-loop: 반복 실행의 별도 진입점이며 이 루프의 상한을 늘리지 않는다.- Karpathy autoresearch: 변경 하나와 실제 평가의 반복 원리.
- Superpowers writing-skills: 기준점 실패 관찰과 실패 유형에 맞춘 지침 형태 참고.