research-eval

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

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에 통과 판정을 주는 건 쓸모없는 정도가 아니라 해롭다 — 거짓 확신을 만든다."

사용법

/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:

# 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