# Research Eval

> 커맨드·스킬·서브에이전트의 품질을 실제로 측정할 때 사용합니다. '이 커맨드 잘 도는지 평가해줘', '스킬 성능 측정해줘', '트리거 정확도 봐줘', 'eval 돌려줘' 같은 요청에 대응합니다. 단, 출처 신뢰도 검증은 /verify, 산출물 정합성 대조는 /synthesize를 사용합니다.

- Skill: `fivetaku/research-eval` (Agent Skill)
- Install (CLI): `npx skillmds@latest add fivetaku/research-eval`
- Raw SKILL.md: https://api.skillmd.com/api/skills/fivetaku/research-eval/raw
- Safety review: pending
- Works with: Claude Code, Claude.ai, OpenAI Codex
- Category: Research & Search
- Author: fivetaku (https://skillmd.com/u/fivetaku)
- Updated: 2026-09-17
- Page: https://skillmd.com/skills/fivetaku/research-eval

---


# eval Workflow

Codex-compatible mirror of `eval.md` from the `research` archetype.

# /eval

**구조 검증이 아니라 행동 검증이다.** 파일이 있는지가 아니라 실제로 시켰을 때 의도대로 도는지를 측정한다.

> 출처: Claude Science `skills/skill-creator/` 구조를 이식 (Apache-2.0, 2026-08-03 해부).
> 원문 grader 지침: *"약한 assertion에 통과 판정을 주는 건 쓸모없는 정도가 아니라 해롭다 — 거짓 확신을 만든다."*

## 사용법

```text
/eval [대상]            # 커맨드명·스킬명·서브에이전트명
/eval [대상] --describe # description 트리거 정확도만 측정
```

## 실행 흐름

### Step 1: 대상과 기대치 확정

- 대상의 정의 파일을 읽는다 (`.claude/commands/*.md`, `.claude/agents/*.md`).
- **기대치(expectations)를 목록으로 뽑는다** — "이 입력을 주면 무엇이 나와야 하는가"를 3~7개.
- 기대치는 **trivially 충족되지 않아야 한다.** "출력이 존재한다" 같은 건 기대치가 아니다.

### Step 2: 테스트 프롬프트 작성

- **should-trigger 3개** — 이 대상이 반드시 발동해야 하는 발화.
- **NOT-trigger 2개** — 비슷하지만 다른 대상으로 가야 하는 발화.
- 실제 사용자가 쓸 법한 말로 쓴다. 정의 파일의 문구를 그대로 베끼면 측정이 무의미해진다.

### Step 3: 실행

- 각 프롬프트를 **독립 서브에이전트**로 실행하고 트랜스크립트를 남긴다.
- 같은 프롬프트를 **최소 2회** 돌린다 — 1회 실행은 분산을 못 본다.
- 결과를 `60-scripts/` 산출 규약에 따라 파일로 남긴다 (원본 덮어쓰기 금지).

### Step 4: 채점 — 그리고 **eval 자체를 비판한다**

두 가지를 동시에 한다.

1. **기대치별 pass/fail 판정** — 판정마다 트랜스크립트의 근거 위치를 인용한다.
2. **기대치 자체의 비판** — 아래를 명시적으로 답한다.
   - trivially 충족되는 기대치가 있는가?
   - **아무 기대치도 확인하지 않는 중요한 결과**가 있는가?
   - NOT-trigger가 실제로 안 걸렸는가, 아니면 애초에 너무 다른 발화였는가?

> 채점만 하고 기대치를 비판하지 않으면 **거짓 확신을 만든다.** 이 단계를 건너뛰면 eval을 돌리지 않은 것보다 나쁘다.

### Step 5: 분산 리포트

- 같은 프롬프트의 회차 간 결과가 갈리면 **분산으로 보고한다.** 평균만 내지 않는다.
- 갈리는 항목은 **모델의 성질인지 정의 파일의 모호함인지** 가른다.

### Step 6: description 최적화 (`--describe` 또는 트리거 오류 발견 시)

트리거 정확도는 **description 문제**다.

- should-trigger가 안 걸렸다 → description에 그 발화 형태가 없다. **추가한다.**
- NOT-trigger가 걸렸다 → 경계가 없다. **"단, ~는 /다른커맨드를 사용합니다"를 추가한다.**
- 고친 뒤 Step 2~5를 다시 돌려 **전후를 비교한다.** 고쳤다는 주장만으로 끝내지 않는다.

## 산출물

`40-reports/_eval/{대상}-{날짜}.md`:

```markdown
# eval — {대상}

## 기대치와 판정
| # | 기대치 | 판정 | 근거 |

## 트리거 정확도
should-trigger n/3 · NOT-trigger n/2

## 분산
| 프롬프트 | 회차1 | 회차2 | 갈림 |

## eval 자체 비판
- trivially 충족되는 기대치: …
- 아무도 확인 안 하는 결과: …

## 조치
- description 변경: (전) … → (후) …
- 재측정 결과: …
```

## 품질 게이트

- [ ] 기대치 3개 이상, trivially 충족되는 것 0개
- [ ] should-trigger 3 + NOT-trigger 2 실행
- [ ] 같은 프롬프트 2회 이상 → 분산 보고
- [ ] 판정마다 트랜스크립트 근거 인용
- [ ] **eval 자체 비판 섹션이 비어 있지 않다**
- [ ] description을 고쳤으면 전후 재측정 결과가 있다

## 참조

- 검증 판정 기준: `frameworks/verification-rubric.md`
- 산출물 correctness: `frameworks/output-correctness.md`
- 스크립트 무결성(채점기도 게이트 대상): `60-scripts/README.md`