# Autoresearch - 스킬 프롬프트 자동 최적화

## 개요

Karpathy의 autoresearch 방법론을 기반으로 한 스킬 프롬프트 반복 개선 시스템입니다. 스킬의 SKILL.md 파일을 자동으로 최적화하여 평가 점수를 향상시킵니다.

## 원리

단순하고 체계적인 최적화 루프:

1. **변경**: 체크리스트와 최근 변경 이력을 바탕으로 **딱 1가지만 변경**
2. **테스트**: 변경된 스킬을 테스트 입력으로 실행
3. **채점**: 체크리스트 기준으로 출력물 평가
4. **판정**:
   - 점수 ≥ 이전 점수 → **유지 (KEEP)**
   - 점수 < 이전 점수 → **롤백 (REVERT)**
5. **종료**: **95% 이상 3회 연속 달성** 시 자동 종료

## 사용법

### 기본 예시

```bash
python /home/jay/workspace/scripts/autoresearch/runner.py \
  --skill ad-creative \
  --checklist /home/jay/workspace/skills/ad-creative/evals/checklist.yaml \
  --test-input "우리 서비스를 광고하는 카피를 작성해줘"
```

### CLI 옵션

| 옵션 | 필수 | 기본값 | 설명 |
|------|------|--------|------|
| `--skill` | ✓ | - | 스킬명 (skills/ 하위 폴더명) |
| `--checklist` | ✓ | - | 체크리스트 YAML 파일 경로 |
| `--test-input` | ✓ | - | 테스트용 입력 텍스트 |
| `--rounds` | - | 50 | 최대 라운드 수 |
| `--target-score` | - | 0.95 | 목표 점수 (0.0~1.0) |
| `--consecutive` | - | 3 | 연속 달성 횟수 |
| `--model-mutate` | - | claude-sonnet-4-6 | 프롬프트 변경 생성 모델 |
| `--model-judge` | - | claude-haiku-4-5-20251001 | 채점용 모델 |
| `--dry-run` | - | False | 1라운드만 시뮬레이션 (실제 변경 없음) |
| `--skills-dir` | - | /home/jay/workspace/skills | 스킬 디렉토리 경로 |

### 고급 예시

```bash
# 더 높은 목표와 많은 라운드
python runner.py \
  --skill my-skill \
  --checklist ./checklist.yaml \
  --test-input "test input" \
  --rounds 100 \
  --target-score 0.98 \
  --consecutive 5

# 특정 모델 사용
python runner.py \
  --skill my-skill \
  --checklist ./checklist.yaml \
  --test-input "test input" \
  --model-mutate claude-opus-4-6 \
  --model-judge claude-opus-4-6

# dry-run으로 동작 확인
python runner.py \
  --skill my-skill \
  --checklist ./checklist.yaml \
  --test-input "test input" \
  --dry-run
```

## 파일 구조

```
scripts/autoresearch/
├── runner.py              # CLI 엔트리포인트 및 메인 루프
├── skill_executor.py      # 스킬 로드 및 실행
├── mutator.py            # 프롬프트 변경 생성 (LLM 기반)
├── judge.py              # 출력물 채점 (체크리스트 기반)
├── changelog.py          # 라운드 로그 관리
└── README.md             # 이 파일
```

### 모듈별 역할

- **runner.py**: 전체 최적화 루프 조율, CLI 인터페이스
- **skill_executor.py**: `SKILL.md` 로드, 스킬 실행, API 호출
- **mutator.py**: LLM을 이용하여 프롬프트의 한 가지 요소만 변경
- **judge.py**: 체크리스트를 기준으로 스킬 출력 평가
- **changelog.py**: 각 라운드의 변경 이력 기록 및 저장

## 체크리스트 YAML 형식

### 기본 구조

```yaml
name: 체크리스트-이름
version: 1
description: "체크리스트 설명"
items:
  - id: 항목-ID-1
    question: "평가 질문?"
    weight: 1.0
  - id: 항목-ID-2
    question: "다른 평가 질문?"
    weight: 2.0
scoring:
  method: "weighted_average"  # 가중 평균 계산
```

### 예시: 광고 카피 품질 체크리스트

```yaml
name: ad-creative-quality
version: 1
description: "광고 카피 품질 체크리스트"
items:
  - id: specific_number
    question: "헤드라인에 구체적인 숫자나 결과가 포함되어 있는가?"
    weight: 1.0
  - id: no_buzzwords
    question: "혁신적, 시너지, 획기적 같은 유행어가 없는가?"
    weight: 1.0
  - id: concrete_cta
    question: "CTA에 구체적인 동사가 포함되어 있는가?"
    weight: 1.0
  - id: pain_point
    question: "첫 문장이 구체적인 고충을 짚고 있는가?"
    weight: 1.0
  - id: word_count
    question: "전체 카피가 150단어 이내인가?"
    weight: 1.0
scoring:
  method: "weighted_average"
```

## 산출물

### 로그 파일 경로

최적화 완료 후 다음 경로에 JSON 형식의 changelog 저장:

```
skills/<skill-name>/evals/changelog-<timestamp>.json
```

### 로그 형식

```json
{
  "skill_name": "ad-creative",
  "timestamp": "2026-03-26T10:30:00Z",
  "initial_score": 0.72,
  "final_score": 0.96,
  "total_rounds": 12,
  "kept": 10,
  "reverted": 2,
  "rounds": [
    {
      "round_num": 1,
      "mutation_type": "clarify_instructions",
      "mutation_description": "단계별 지시사항 추가",
      "score_before": 0.72,
      "score_after": 0.78,
      "decision": "kept",
      "items": [
        {
          "id": "specific_number",
          "score": 1.0,
          "feedback": "OK"
        }
      ],
      "input_tokens": 2500,
      "output_tokens": 1200
    }
  ]
}
```

### 자동 생성 파일

- **backup-original.md**: 최적화 전 원본 스킬 백업
- **changelog-<timestamp>.json**: 각 라운드의 변경 이력

## 주요 특징

- **원자적 변경**: 매번 한 가지만 변경하여 효과 측정 명확
- **자동 롤백**: 성능 저하 시 즉시 이전 버전으로 복원
- **조기 종료**: 목표 달성 시 불필요한 라운드 스킵
- **상세 로깅**: 모든 변경과 점수 변화 기록
- **dry-run 모드**: 실제 변경 없이 동작 확인 가능