diff --git a/build/eval/interview/README.md b/build/eval/interview/README.md new file mode 100644 index 0000000..d58d1e7 --- /dev/null +++ b/build/eval/interview/README.md @@ -0,0 +1,238 @@ +# designpaca 인터뷰 게이트 로컬 평가 도구 + +designpaca 스킬의 0단계 사용자 인터뷰가 실제 하네스(Claude Code, Codex)에서 +일어나는지를 실측하는 로컬 전용 평가 도구다. **CI에는 넣지 않는다** — 실제 +모델 호출 비용이 들고, 로그인된 CLI 인증을 전제로 하기 때문이다. + +스킬을 고치기 전후 결과를 이 도구로 비교해서 "인터뷰 게이트가 실제로 +강해졌는지"를 숫자로 확인하는 것이 목적이다. + +## Claude 러너 두 가지 (v1 / v2) + +- **v1 (`run-claude.mjs`, `--runners claude`)** — `claude -p`(비대화형 CLI)를 + 직접 서브프로세스로 호출한다. 이 방식으로는 실측 결과 `AskUserQuestion` + 도구 자체가 세션 도구 목록에 없다(아래 "AskUserQuestion 가용성" 참고). +- **v2 (`run-claude-sdk.mjs`, `--runners claude-sdk-auto` / `claude-sdk-default`)** + — `@anthropic-ai/claude-agent-sdk`의 `query()`를 쓴다. 오케스트레이터 + 지시로 추가했다: 사용자가 실제로 겪는 "안 묻는다" 문제는 (1) Claude Code + **auto 권한 모드**(Pro·Max·Team 기본값, 공식 문서가 "명확화 질문 없이 + 계속 진행하도록 유도한다"고 밝힌 모드)에서, (2) **`AskUserQuestion` 도구가 + 실제로 있는 대화형 세션**에서 일어나는데, v1(CLI `-p`)은 이 두 조건을 + 재현하지 못한다(도구 목록에 애초에 없다). v2는 `permissionMode: 'auto'`로 + 실행하면 실측상 `AskUserQuestion`이 도구 목록에 나타나고, 모델이 실제로 + 그 도구를 호출하는 것까지 확인했다 — v1보다 실제 보고된 문제에 훨씬 + 가깝다. v1은 (구현이 더 가볍고 SDK 의존성이 없다는 이유로) 계속 남겨 둔다. + `--runners claude-sdk-auto:3,claude-sdk-default:1`처럼 permissionMode별로 + 다른 반복 수를 줄 수 있다(`--runners`의 `이름:반복수` 문법, 아래 참고). + `default` 모드는 보조 지표로만 쓴다(auto가 실제 보고된 문제 조건에 더 + 가깝다). + +## 사전 준비 + +- `claude` CLI가 로그인되어 있어야 한다(`claude -p "OK 라고만 답해"`로 확인). +- **v2(SDK) 러너를 쓰려면** `outputs/eval/deps/`에 SDK를 한 번 설치한다 + (저장소 자체의 의존성을 늘리지 않으려고 저장소 밖 스크래치 경로에 둔다): + ```bash + mkdir -p outputs/eval/deps && cd outputs/eval/deps + npm init -y && npm install @anthropic-ai/claude-agent-sdk + ``` + 공식 quickstart(code.claude.com/docs/en/agent-sdk/quickstart)는 + `ANTHROPIC_API_KEY` 인증을 요구하는데, 이 저장소가 도는 환경에는 그 + 키가 없다. 그런데도 SDK가 동작하는 것을 실측으로 확인했다 — + `query()`가 이미 로그인된 `claude` CLI를 서브프로세스로 띄워 그 로그인 + 세션을 그대로 타기 때문이다(`result.json`의 `apiKeySource: "none"`). +- `codex` CLI가 로그인되어 있어야 한다(`~/.codex/auth.json` 존재, `codex doctor`로 확인). +- Node.js — 저장소 루트의 요구 버전(>=20.11)이면 된다. v1 Claude 러너와 + Codex 러너는 이미 설치된 CLI를 서브프로세스로 호출할 뿐 추가 설치가 + 없다. + +## 실행 + +```bash +node build/eval/interview/run.mjs \ + --skill-dir <평가할 SKILL.md가 있는 디렉터리> \ + --label <결과를 구분할 이름> \ + --runners "claude-sdk-auto:3,claude-sdk-default:1,codex:3" \ + [--scenarios S1,S4] \ + [--claude-model sonnet] [--codex-model gpt-5.1-codex] \ + [--timeout-ms 300000] +``` + +- `--skill-dir`: `SKILL.md`가 직접 들어 있는 디렉터리(예: `packages/skill`, + 또는 특정 커밋을 `git archive`로 뽑은 사본). +- `--label`: 결과가 쌓이는 폴더 이름. 같은 label로 러너를 나눠 여러 번 + 실행해도(`--runners claude`, 그다음 `--runners codex`) `results.jsonl`에 + 누적되고 `summary.md`는 매번 전체를 다시 집계한다. +- `--runners`: 콤마로 구분한 러너 목록. `이름:반복수`로 러너별 반복 수를 + 따로 줄 수 있다(생략하면 `--repeat`, 기본 3). 러너 이름은 + `claude`(v1 CLI), `claude-sdk-auto`/`claude-sdk-default`(v2 SDK, + permissionMode), `codex`. +- 결과는 `outputs/eval/interview/runs/