# Autoresearch 시스템 Phase 1: 코어 러너 구현

## 개요
Karpathy의 autoresearch 방법론을 우리 스킬 시스템에 적용.
스킬 프롬프트(SKILL.md)를 자동으로 반복 개선하는 시스템.

**원리**: 딱 1가지만 변경 → 테스트 → 좋으면 유지, 나쁘면 롤백 → 95% 이상 3회 연속 달성 시 종료

## 우리 스킬 시스템 구조 (참고)
- 스킬 디렉토리: `/home/jay/workspace/skills/<skill-name>/SKILL.md`
- SKILL.md = YAML 프론트매터 + 마크다운 본문
- 스킬 레지스트리: `/home/jay/workspace/skills/shared/skill-registry.json`
- 기존 평가 도구: `/home/jay/workspace/scripts/skill-judge.py`

## Phase 1 산출물

### 1. 코어 러너 스크립트
**경로**: `/home/jay/workspace/scripts/autoresearch/runner.py`

**CLI 인터페이스**:
```bash
python3 scripts/autoresearch/runner.py \
  --skill ad-creative \
  --checklist skills/ad-creative/evals/checklist.yaml \
  --test-input "보험 FA 모집 광고, 타겟: 30대 보험설계사" \
  --rounds 10 \
  --target-score 0.95 \
  --consecutive 3
```

**핵심 파라미터**:
- `--skill`: 스킬명 (skills/ 하위 폴더명)
- `--checklist`: 체크리스트 YAML 경로
- `--test-input`: 테스트용 입력 텍스트
- `--rounds`: 최대 라운드 수 (기본 50)
- `--target-score`: 목표 점수 (기본 0.95 = 95%)
- `--consecutive`: 연속 달성 횟수 (기본 3)
- `--model-mutate`: 변경 생성용 모델 (기본 claude-sonnet-4-6)
- `--model-judge`: 채점용 모델 (기본 claude-haiku-4-5-20251001)
- `--dry-run`: 실제 변경 없이 1라운드만 시뮬레이션

**라운드 루프 (핵심 로직)**:
```
1. 현재 SKILL.md 읽기
2. LLM(mutate)에게 "딱 1가지만 변경해라" 요청 → 변경된 SKILL.md 생성
3. 변경된 SKILL.md로 스킬 실행 (test-input으로)
4. LLM(judge)에게 결과물 + 체크리스트 전달 → 각 항목 PASS/FAIL + 전체 점수
5. 점수가 이전보다 높거나 같으면 → KEEP (변경 유지)
6. 점수가 낮으면 → REVERT (원본 복원)
7. 연속 target_score 이상 consecutive회 → STOP
8. changelog 기록
```

### 2. 체크리스트 포맷
**경로**: `skills/<skill-name>/evals/checklist.yaml`

```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"  # PASS=1, FAIL=0, 가중평균
```

**규칙**: 최대 6개 항목. 넘으면 게이밍 위험.

### 3. Mutation 프롬프트 설계
LLM에게 보내는 변경 요청:

```
당신은 스킬 프롬프트 최적화 전문가입니다.
아래 스킬 프롬프트에서 **딱 1가지만** 변경하세요.

변경 유형 (하나만 선택):
- 규칙 추가: 새로운 규칙이나 제약 조건 1개 추가
- 예시 삽입: 좋은 예시 1개 추가
- 금지 목록: 금지 단어/표현 목록 추가
- 표현 수정: 기존 지시문 1개의 표현을 더 명확하게 수정
- 구조 변경: 지시 순서나 섹션 구조 1곳 변경
- 규칙 삭제: 효과 없어 보이는 규칙 1개 제거

체크리스트를 참고하여, 가장 효과적일 것 같은 변경을 선택하세요.

[현재 스킬 프롬프트]
{current_skill_md}

[체크리스트]
{checklist_yaml}

[이전 변경 로그 (최근 5개)]
{recent_changelog}

변경 내용을 설명하고, 변경된 전체 스킬 프롬프트를 출력하세요.
```

### 4. Judge 프롬프트 설계
```
아래 체크리스트의 각 항목에 대해 결과물을 평가하세요.
각 항목에 PASS 또는 FAIL로 답하고, 짧은 이유를 달아주세요.

[체크리스트]
{checklist_items}

[스킬 결과물]
{skill_output}

JSON 형식으로 응답:
{
  "items": [
    {"id": "specific_number", "result": "PASS", "reason": "..."},
    ...
  ],
  "total_score": 0.8,
  "summary": "..."
}
```

### 5. Changelog 저장
**경로**: `skills/<skill-name>/evals/autoresearch-log.json`

```json
{
  "skill": "ad-creative",
  "started_at": "2026-03-26T18:00:00",
  "rounds": [
    {
      "round": 1,
      "mutation_type": "규칙 추가",
      "mutation_description": "헤드라인에 구체적 숫자 포함 규칙 추가",
      "score_before": 0.6,
      "score_after": 0.8,
      "items_detail": [...],
      "decision": "KEEP",
      "timestamp": "..."
    }
  ],
  "final_score": 0.95,
  "total_rounds": 4,
  "kept": 3,
  "reverted": 1
}
```

### 6. 스킬 실행 방법
스킬을 프로그래밍적으로 실행하는 방법이 필요.
- `skill_loader.py`의 `load_skill()` 함수로 SKILL.md 내용을 로드
- Anthropic API를 직접 호출하여 스킬 프롬프트 + 테스트 입력으로 결과 생성
- API 키: `/home/jay/workspace/.env.keys`에서 `ANTHROPIC_API_KEY` 로드
- **스킬 실행 모델**: Sonnet (비용 효율) — `claude-sonnet-4-6`

```python
import anthropic
# .env.keys에서 키 로드
client = anthropic.Anthropic(api_key=api_key)
response = client.messages.create(
    model="claude-sonnet-4-6",
    max_tokens=4096,
    system=skill_prompt,  # SKILL.md 본문
    messages=[{"role": "user", "content": test_input}]
)
skill_output = response.content[0].text
```

## 구현 주의사항
1. **원본 백업**: 변경 전 SKILL.md 원본을 `skills/<name>/evals/backup-original.md`에 저장
2. **에러 핸들링**: API 실패 시 해당 라운드 스킵, 로그에 기록
3. **비용 추적**: 각 라운드의 토큰 사용량 기록 (input/output tokens)
4. **YAML 프론트매터 보존**: SKILL.md 변경 시 프론트매터는 건드리지 않음. 마크다운 본문만 변경.
5. **Git 안전**: SKILL.md 변경 후 git에 커밋하지 않음. 수동 커밋은 제이회장님이 결정.
6. **.env.keys 로드**: `python-dotenv` 또는 직접 파싱. 경로: `/home/jay/workspace/.env.keys`
7. **모듈화**: runner.py, mutator.py, judge.py, changelog.py 로 분리

## 파일 구조
```
/home/jay/workspace/scripts/autoresearch/
├── runner.py          # 메인 루프 + CLI
├── mutator.py         # LLM 기반 단일 변경 생성
├── judge.py           # 체크리스트 기반 채점
├── changelog.py       # 변경 로그 관리
├── skill_executor.py  # 스킬 실행 (API 호출)
└── README.md          # 사용법
```

## 검증
1. `--dry-run`으로 1라운드 시뮬레이션 정상 동작
2. 체크리스트 YAML 파싱 정상
3. changelog JSON 정상 생성
4. API 호출 성공 (키 로드 확인)
5. 원본 백업 정상 생성

## Phase 2 (이번 스코프 아님, 참고용)
- 대시보드 위젯: 점수 그래프, 항목별 통과/실패, 변경 로그 실시간 표시
- 스케줄 연동: 백그라운드에서 자동 실행
- 복수 test-input 지원: 여러 입력으로 채점 → 평균