empirical-prompt-tuning

name	empirical-prompt-tuning
description	사용자가 쓴 Claude Code Skill / SlashCommand / 프롬프트를 별도 AI에 백지 dispatch 시켜 재현성을 객관 측정하는 메타 스킬. 자기 재독으로는 못 보는 불명확점·재량 보완·재시도를 정성+정량(tool_uses) 양면으로 수집해 1회 1테마로 정련. 트리거 - "내 스킬 평가해줘", "프롬프트 재현성 검증", "skill 튜닝", "SKILL.md 다듬어줘", "암묵지 빼줘", "empirical prompt tuning". 단순 윤문은 humanize-korean, 다분야 토론 리뷰는 start로 분기.

Empirical Prompt Tuning

자기가 쓴 프롬프트의 재현성을 자기는 평가할 수 없다. 별도 AI에게 백지 상태로 실행시키고 불명확점을 보고받아 단계적으로 정련하는 루프 스킬.

핵심 원칙 (이걸 빠뜨리면 의미 없음)

1. 글쓴이와 판정자 분리 — 자기 재독은 편향이 들어간다. 반드시 다른 컨텍스트(서브에이전트 / 신규 세션 / 다른 AI)에게 실행시킨다.
2. 시나리오 사전 고정 — 실행 후에 시나리오를 손보면 "불명확점이 메워진 것처럼 위장" 가능. 절대 금지.
3. 매번 신규 dispatch — 같은 세션 재사용은 이전 지적 학습으로 통과율이 가짜로 오른다.
4. 양면 측정 — 정성(불명확점·재량 보완·재시도)과 정량(tool_uses·duration_ms·요건 달성률)을 동시에 본다. 정량만으론 본문이 야위는 줄 모른다.
5. 1회 반복 1테마 — 한 번에 여러 곳 고치면 무엇이 효과적이었는지 추적 불가.
6. hold-out 시나리오 — 조정에 쓰지 않은 신규 시나리오로 과적합 검사.

환경별 분기

이 스킬은 두 환경에서 작동한다. 첫 단계에서 어느 쪽인지 판별한다:

• Claude Code 환경 (Task tool 사용 가능) → references/claude-code-flow.md 참조
• Claude.ai 환경 (Task tool 없음, 단일 세션) → references/claude-ai-flow.md 참조

판별 방법: Task tool이 노출되어 있으면 Claude Code, 그렇지 않으면 Claude.ai로 간주한다. 사용자가 "Claude Code에서 돌려줘" 또는 "지금 이 자리에서 돌려줘"로 명시하면 그에 따른다.

워크플로우 (공통)

[1] 대상 식별        → 평가할 SKILL.md / SlashCommand / 프롬프트 파일 확보
[2] 시나리오 설계    → median 1개 + edge 1~2개 + hold-out 1개
[3] 요건 체크리스트  → [critical] 태그 최소 1개 포함
[4] 실행 (환경별)    → 서브에이전트 병렬 OR 신규 세션 직렬
[5] 보고 수집        → 정성(불명확점/재량/재시도) + 정량(tool_uses/duration)
[6] 1테마 수정       → 가장 큰 불명확점 1개만 본문 반영
[7] 재실행           → 새로운 dispatch로 [4] 반복
[8] 종료 판정        → 수렴/발산/종료 중 하나

[1] 대상 식별

사용자에게 평가 대상의 형태를 확인한다:

• ~/.claude/skills/<n>/SKILL.md (Skill 본체)
• ~/.claude/commands/<n>.md (SlashCommand)
• 임의의 프롬프트 텍스트 파일

frontmatter의 description이 표방하는 범위와 본문이 커버하는 범위가 어긋나는지 사전 정적 체크. 어긋나면 서브에이전트가 description에 맞춰 본문을 "재해석"해 빠진 skill이 가짜로 통과한다.

[2] 시나리오 설계

최저 조건: median 1 + edge 1~2 + hold-out 1.

분류	역할	개수
median	가장 전형적인 사용 케이스	1
edge	본문 설명 범위에서 벗어난 변형	1~2
hold-out	조정에 쓰지 않고 끝까지 보존	1

시나리오는 1단락의 상황 설정으로 구성한다. 자세한 작성법은 references/scenario-design.md 참조.

[3] 요건 체크리스트 작성

각 시나리오마다 요건을 항목화한다. [critical] 태그를 최소 1개 부여한다. critical 항목이 모두 ○일 때만 성공으로 간주.

요건 체크리스트:
1. [critical] <최저 라인 항목>
2. [critical] <또 다른 최저 라인>
3. <일반 항목>
4. <일반 항목>

[critical]이 없으면 "전부 50% 달성" 같은 흐릿한 결과가 나오고 다음에 어디를 고쳐야 할지 알 수 없게 된다.

[4] 실행

환경에 따라 분기:

• Claude Code: references/claude-code-flow.md의 Task tool 기동 절차
• Claude.ai: references/claude-ai-flow.md의 단일 세션 직렬 절차

dispatch 프롬프트 템플릿은 assets/dispatch-prompt-template.md 사용.

[5] 보고 수집

dispatch 응답에서 다음을 추출:

정성 데이터 (수정 우선순위 결정용):

• 불명확점 — 막힌 부분, 해석 망설임
• 재량 보완 — 지시에 없어서 자기 판단으로 채운 곳
• 재시도 — 같은 판단 다시 한 횟수와 이유

정량 데이터 (구조적 결함 검출용):

• 요건 달성 ○/×/부분적
• tool_uses (Claude Code의 경우 <usage> 태그에서 추출)
• duration_ms (동상)

tool_uses가 시나리오 간 큰 격차(예: 3 vs 15+)를 보이면 그 시나리오에서 본문 자기 완결성이 깨졌다는 신호. 본문에 "최소 완성 예시 inline" 또는 "언제 references를 읽을지 지침"을 추가하면 떨어진다.

[6] 1테마 수정

보고서에서 가장 큰 불명확점 1개를 골라 본문에 반영. 한 번에 여러 곳 고치지 않는다. 추적 불가능해진다.

수정 전, 사용자에게 **"이 수정이 어느 평가 기준의 어느 임곗값 문언을 충족하는가"**를 사전 언어화시킨다. 임곗값 문언을 안 보고 축 이름만 보고 수정하면 +0pt가 나오는 경우가 흔하다.

[7] 재실행

반드시 새로운 dispatch. 같은 서브에이전트나 같은 세션 재사용 금지. 시나리오와 요건 체크리스트는 [2]에서 고정한 그대로.

[8] 종료 판정

세 가지 상태 중 하나:

수렴 (정지):

• 연속 2회에 걸쳐 신규 불명확점 0
• 정확도 ≤+3pt 변동
• steps ±10% 이내, duration ±15% 이내
• hold-out 시나리오에서 직전 평균 대비 -15pt 이상 떨어지지 않음 → 과적합 없음

발산 (구조 재설계):

• 3회 이상 반복해도 신규 불명확점이 줄지 않음
• 패치로는 못 고친다. 본문 구조를 다시 쓴다.

종료 (충분):

• 중요도와 개선 비용이 맞지 않게 됨
• 80~90점 도달했고 남은 항목은 사용 빈도 낮은 디테일

체감으로 50→80이 가장 효과 크고, 80→90은 2~3회, 90→100은 정체이므로 명확한 멈춤 시점.

정량 메트릭 임곗값 가이드

정확도 50점 이하 → 본문 설계 결함 의심. 발산 가능성 검토.
정확도 50~80     → 본문 추가/명시화로 빠르게 개선. 1~2회 반복.
정확도 80~90     → 디테일 보완 단계. 2~3회 반복.
정확도 90+       → 정체. 종료 권장.

tool_uses 1~3    → 자기 완결성 양호.
tool_uses 4~10   → references 분리 의도라면 정상.
tool_uses 15+    → 구조 결함. 실행 AI가 헤매고 있음.

함정 (자주 빠지는 곳)

• 시나리오가 본문 설명 범위만 따라간다 → "전부 100%"가 나오는 가짜 통과. median + edge + hold-out 강제.
• 같은 AI 재사용 → 이전 지적 학습으로 통과. 매번 신규 dispatch.
• 메트릭만 본다 → 본문이 야위어도 모른다. 정성 피드백이 주, 정량은 보조.
• 1회에 여러 수정 → 무엇이 효과 있었는지 추적 불가. 1테마/회.
• 사후 시나리오 튜닝 → 본말전도. 절대 금지.
• 자기 재독으로 대체 → 편향이 들어간다. 별도 AI dispatch 못 하면 평가 자체를 건너뛰고 명시 보고.

적용 안 하는 케이스

• 일회성 일회용 프롬프트
• 글쓴이의 주관적 취향 반영이 목적인 경우
• 단순 맞춤법·번역투 윤문 (→ humanize-korean)
• 다분야 전문가 토론 형식 리뷰 (→ start)

참고 파일

• references/claude-code-flow.md — Task tool 기반 병렬 dispatch 절차
• references/claude-ai-flow.md — 단일 세션 직렬 폴백 절차
• references/scenario-design.md — median/edge/hold-out 시나리오 작성 가이드
• references/scoring-rubric.md — 20점 평가 기준 템플릿 (기술 문서/스킬 양쪽)
• assets/dispatch-prompt-template.md — dispatch 프롬프트 본체 템플릿
• assets/report-structure.md — 서브에이전트 보고 구조 강제 템플릿
• assets/iteration-log-template.md — 반복 추이 기록표 템플릿