# task-1101.1 완료 보고서: Autoresearch 시스템 완전학습 + 첫 실행

**팀**: dev4-team (비슈누 팀장)
**팀원**: 카르티케야(백엔드), 하누만(테스터)
**일시**: 2026-03-27

---

## SCQA

**S**: Autoresearch 시스템이 Phase 1~2까지 코드 완성되어 150개 테스트가 전부 PASS하는 상태이다. 이번 작업에서 시스템을 완전 학습하고 ad-creative 스킬에 대해 첫 실행을 진행해야 한다.

**C**: 실행 전 검증에서 ANTHROPIC_API_KEY가 환경변수, `.env.keys`, `.env` 등 모든 탐색 경로에 존재하지 않음이 확인됨. dry-run 모드도 초기 실행에서 `execute_skill()` → `load_env_key()`를 호출하므로 API 키 없이는 동작 불가. Phase 3(실제 최적화 실행) 진행 블로커.

**Q**: API 키 설정 후 Phase 3 실행을 위해 어떤 준비가 완료되었고, 무엇이 남았는가?

**A**: Phase 1(시스템 완전학습) 100% 완료, Phase 2의 테스트 검증(150/150 PASS) 완료. API 키를 `/home/jay/workspace/.env.keys`에 `ANTHROPIC_API_KEY=sk-ant-...` 형식으로 설정하면 Phase 3~4 즉시 실행 가능. dry-run + 5라운드 + 30라운드 실행 커맨드가 모두 준비됨.

---

## Phase 1: 시스템 완전학습 결과

### 아키텍처 요약
Autoresearch는 Karpathy의 autoresearch 방법론을 구현한 스킬 프롬프트 자동 최적화 파이프라인이다. 핵심 원리는 "딱 1가지만 변경 → 테스트 → 좋으면 KEEP, 나쁘면 REVERT → 목표 달성 시 종료"이다. mutator(LLM)가 SKILL.md를 한 번에 하나씩 변경하고, skill_executor가 API로 실행한 뒤, judge(LLM)가 체크리스트 기반으로 채점한다. 점수 개선이면 유지, 퇴보면 즉시 롤백. 이 루프를 최대 N 라운드 반복하며, 목표 점수를 연속 K회 달성하면 조기 종료한다.

### 실행 흐름
```
runner.run() → load_checklist → load_skill → backup_original → create_log
  → 초기 실행 (각 test_input: execute_skill → judge_output → 평균 점수)
  → for round in range(rounds):
      run_round(): get_recent_changelog → generate_mutation → apply_mutation
        → 각 test_input: execute_skill → judge_output
        → score >= prev → KEEP / score < prev → REVERT
  → finalize_log → save_log → [background시] generate_report
```

### 모듈별 핵심 역할
- **runner.py**: 전체 최적화 루프 오케스트레이션, dry-run/background 모드 처리
- **mutator.py**: 현재 SKILL.md + 체크리스트 + 이력을 LLM에 제공, "딱 1가지" 변경 생성, `---MODIFIED_SKILL---` 구분자로 파싱
- **judge.py**: 체크리스트 항목별 PASS/FAIL 채점, LLM 응답의 total_score 무시하고 가중평균 직접 재계산
- **changelog.py**: 라운드별 결과 누적, 최근 5개 이력을 mutator에 피드백
- **skill_executor.py**: SKILL.md를 system prompt로 Anthropic API 호출, API 키 탐색 담당
- **capture.py**: 실제 사용 시 user_input을 test-inputs.yaml에 자동 저장 (autoresearch 루프 내에서는 미호출)
- **reporter.py**: changelog를 마크다운 보고서로 변환, 토큰 비용 계산

### 주요 설정값
- 기본 mutate 모델: `claude-sonnet-4-6`, judge 모델: `claude-haiku-4-5-20251001`
- 기본 라운드: 50, 목표 점수: 0.95, 연속: 3
- 체크리스트 최대 항목: 6개, 캡처 최대 입력: 20개
- 백업 경로: `skills/<name>/evals/backup-original.md`
- 로그 저장: `skills/<name>/evals/autoresearch-log.json`

### 대상 스킬: ad-creative
- **체크리스트 5항목** (전부 weight 1.0): specific_number(숫자 포함), no_buzzwords(유행어 배제), concrete_cta(구체적 CTA), pain_point(고충 짚기), word_count(150단어 이내)
- **테스트 입력 3개**: insurance-fa-recruit(FA 모집), insurance-product-promo(종신보험 출시), insuwiki-landing(서비스 소개)

---

## Phase 2: 실행 전 검증 결과

### 1. 테스트 실행: PASS ✅
```
150 passed, 3 warnings in 0.64s
```
- 전체: 150개 / PASS: 150개 / FAIL: 0개
- warnings 3건은 의도적 예외처리 검증 경고 (무시 가능)

### 2. API 키 확인: FAIL ❌
| 탐색 경로 | 결과 |
|-----------|------|
| 환경변수 `$ANTHROPIC_API_KEY` | 미설정 |
| `/home/jay/workspace/.env.keys` | 파일 있으나 키 없음 |
| `/home/jay/workspace/.env` | 파일 있으나 키 없음 |
| `/home/jay/.env.keys` | 파일 없음 |
| `/home/jay/.env` | 파일 없음 |

### 3. Dry-run 실행: FAIL ❌
```
OSError: API key 'ANTHROPIC_API_KEY' not found in environment variables, .env.keys, or .env files.
```
- 원인: dry-run 모드도 초기 실행 단계에서 `execute_skill()` 호출 → API 키 필수
- 코드 자체의 문제 아님, 순수 인프라 설정 누락

---

## Phase 3~4: 미수행 (블로커)

API 키 미설정으로 인해 아래 작업 미수행:
- 소규모 실행 (5라운드)
- 본 실행 (30라운드)
- 리포트 생성
- SKILL.md 최적화 결과 분석

### 실행 준비 완료 커맨드 (API 키 설정 후 즉시 실행 가능)

**API 키 설정:**
```bash
echo 'ANTHROPIC_API_KEY=sk-ant-...' >> /home/jay/workspace/.env.keys
```

**Dry-run:**
```bash
cd /home/jay/workspace && python3 scripts/autoresearch/runner.py \
  --skill ad-creative \
  --checklist skills/ad-creative/evals/checklist.yaml \
  --test-input "보험 FA 모집 광고 테스트" \
  --rounds 1 --dry-run
```

**5라운드 소규모 실행:**
```bash
cd /home/jay/workspace && python3 scripts/autoresearch/runner.py \
  --skill ad-creative \
  --checklist skills/ad-creative/evals/checklist.yaml \
  --test-inputs-file skills/ad-creative/evals/test-inputs.yaml \
  --rounds 5 --target-score 0.90
```

**30라운드 본 실행:**
```bash
cd /home/jay/workspace && python3 scripts/autoresearch/runner.py \
  --skill ad-creative \
  --checklist skills/ad-creative/evals/checklist.yaml \
  --test-inputs-file skills/ad-creative/evals/test-inputs.yaml \
  --rounds 30 --target-score 0.95 --consecutive 3
```

---

## 발견 이슈 및 해결

### 자체 해결 (0건)
코드 수정 금지 작업이므로 해당 없음.

### 범위 외 미해결 (3건)

1. **ANTHROPIC_API_KEY 미설정** — 범위 외 사유: 인프라/시크릿 관리 영역. 관리자가 `.env.keys`에 키 설정 필요.

2. **dry-run 모드가 API 호출을 건너뛰지 않음** — 범위 외 사유: 코드 수정 금지 지시. `runner.py` line 328-350의 초기 실행이 dry-run 여부와 무관하게 `execute_skill()`을 호출. 향후 개선 시 dry-run일 때 mock 응답 반환 로직 추가 권장.

3. **reporter.py 비용 계산 모델 고정** — 범위 외 사유: 코드 수정 금지. Sonnet 단가로만 계산하며 Haiku(judge) 토큰 비용이 구분되지 않음. 실제 비용보다 과대 산출됨.

---

## 검증 결과

### 작업 검증 매트릭스

**완료 항목:**
- 1. 150개 테스트 전체 PASS — 증거: `150 passed, 3 warnings in 0.64s`
- 6. pyright 에러 0건 — N/A (코드 수정 없음)

**인프라 전제조건 미충족으로 대기 중 (관리자 조치 후 재실행 예정):**
- 2. dry-run — 범위 외 사유: ANTHROPIC_API_KEY 미설정 (인프라 영역)
- 3. 소규모 실행 (5라운드) — 범위 외 사유: API 키 전제조건 미충족
- 4. 본 실행 (30라운드) — 범위 외 사유: API 키 전제조건 미충족
- 5. SKILL.md 백업 확인 — 범위 외 사유: 실행 미수행으로 백업 미생성

### 개선 제안
1. **체크리스트 항목 추가 제안**: `platform_spec_compliance` (플랫폼별 글자 수 제한 준수 확인) — 현재 5항목은 카피 품질만 평가하고 플랫폼 스펙 준수를 검증하지 않음
2. **다음 최적화 대상 스킬**: `copywriting-prompt` (전환율 카피) 또는 `blog-writer` (블로그 작성) — 사용 빈도 높고 체크리스트 정의가 용이
3. **dry-run mock 모드 추가**: API 키 없이도 구조 검증 가능하도록 `--dry-run` 시 더미 응답 반환 기능 추가 권장

---

## 생성/수정 파일 목록
- 생성: `/home/jay/workspace/memory/reports/task-1101.1.md` (본 보고서)
- 수정: 없음 (읽기 전용 작업)