prompt-tunning

name	prompt-tunning
description	agent용 텍스트 지시(skill / slash command / task 프롬프트 / CLAUDE.md 절 / 코드 생성 프롬프트)를 바이어스를 배제한 실행자에게 실제 실행시키고, 실행자 자기보고 + 지시측 메트릭으로 양면 평가하여 반복 개선하는 방법론.

Prompt Tuning

프롬프트의 품질은 작성자에게 보이지 않는다.
작성자가 “명확하다”고 생각하는 지시일수록, 다른 에이전트는 쉽게 막힌다.

핵심은 바이어스를 배제한 실행자에게 실제로 실행시키고, 양면에서 평가하여 반복 개선하는 것이다.
개선이 더 이상 발생하지 않을 때까지 멈추지 않는다.

---

커맨드 문법

/prompt-tunning <스킬명>           지정 스킬 튜닝 (기본: 최소 3회 이터레이션)
/prompt-tunning <스킬명> --eval    채점만 수행 (파일 수정 없음)
/prompt-tunning <스킬명> --iter N  N회 이터레이션만 수행

스킬명: .claude/skills/<스킬명>/SKILL.md 또는 .claude/commands/<스킬명>.md 기준으로 탐색한다.

---

언제 사용하는가

• skill / slash command / 태스크 프롬프트를 신규 작성하거나 대폭 수정한 직후
• 에이전트가 기대대로 동작하지 않고, 원인을 지시의 모호성에서 찾고자 할 때
• 자주 사용하는 핵심 프롬프트를 안정화하고 싶을 때

---

사용하지 않는 경우

• 일회성 프롬프트 (평가 비용 대비 효과 낮음)
• 성공률 개선이 목적이 아닌, 단순 취향 반영

---

워크플로우

0. Iteration 0 — description / body 정합성 체크 (정적)

• description이 정의하는 목적/용도 확인
• body가 해당 범위를 실제로 커버하는지 확인
• 불일치 시 iteration 시작 전에 수정

※ 이 단계를 생략하면 false positive 발생

---

1. 베이스라인 준비

시나리오

• 23개 (중앙 1 + edge 12)
• 실제 사용 상황 기반

체크리스트

• 3~7개
• 반드시 [critical] 최소 1개 포함
• 사전 정의 후 변경 금지

---

2. 바이어스 제거 실행

• 반드시 Task tool로 새로운 subagent 생성
• 자기 재검토 금지

---

3. 실행

subagent에게 다음을 전달:

• 대상 프롬프트
• 시나리오
• 체크리스트

실행 후 자기보고 포함 결과 반환

---

4. 양면 평가 (핵심)

4-1. 실행자 자기보고

• 불명확한 지점
• 해석에 고민한 부분
• 임의 판단한 부분

---

4-2. 지시측 메트릭

항목	설명
성공/실패	critical 전부 충족 여부
정확도	체크리스트 충족률
단계 수(tool_uses)	실행자가 사용한 도구 호출 / 판단 단계 수
소요시간	실행자의 duration_ms
재시도 횟수(retries)	같은 판단을 여러 번 다시 했는가?
불명확점 수	자기보고의 불명확 항목 수 (0이 최선)
임의 판단 수	자기보고의 임의 판단 항목 수 (0이 최선)
수행 난이도	쉬움 / 보통 / 어려움

가중치 : 질적(불명확점 수, 임의 판단 수) 요소를 메인으로 하고 양적(단계 수, 소요시간, 재시도 횟수) 요소는 보조로 한다.

---

성공/실패 기준

• [critical] 항목이 모두 ○ → 성공
• 하나라도 × 또는 부분 → 실패

---

정확도 계산

• ○ = 1
• 부분 = 0.5
• × = 0

---

실패 시 규칙

• 어떤 [critical] 항목이 실패했는지 반드시 기록

---

5. 수정 적용

• 불명확점 제거를 위한 최소 수정만 수행
• 1 iteration = 1 테마

반드시 명시:

이 수정이 어떤 체크리스트 항목을 해결하는가

---

6. 재평가

• 반드시 새로운 subagent 사용
• 동일 시나리오 유지
• 반복 실행

---

7. 수렴 판단

다음 조건 2회 연속 만족 시 종료:

• 신규 불명확점 0
• 신규 임의 판단 0
• 정확도 개선 ≤ 3%
• tool_uses 변화 ±10% (수집 가능한 경우)
• duration 변화 ±15% (수집 가능한 경우)

---

tool_uses 해석 (구조적 결함 탐지)

• 정확도가 높더라도 tool_uses 편차가 크면 구조적 결함이 존재한다. 예) 불필요한 탐색을 반복했지만 결과는 맞음 → 정확도 100%, 여러 번 시행착오 후 겨우 성공 → 정확도 100%, 특정 시나리오에서만 비정상적으로 많은 단계 사용 → 정확도 100%
• 특정 시나리오의 tool_uses가 다른 시나리오 대비 3배 이상이거나, 반복 실행 시 동일 시나리오에서 지속적으로 높은 값이거나, retries 증가와 함께 tool_uses 증가하면 구조적 결함을 인지한다.
• 해결방법은 최소 실행 예시 추가하거나, 조건별 행동을 명확히 정의하거나, reference 사용 조건 명확화하게 해준다.

의미

• self-contained 아님
• reference 탐색 의존

해결

• 최소 실행 예시 추가
• reference 사용 기준 명시

---

수정 효과 패턴

• 보수적: 기대보다 효과 적음
• 상향: 하나의 수정이 여러 지표 개선
• 무효: 영향 없음

해결:

수정이 어떤 판정 기준을 만족하는지 명확히 연결

---

subagent 실행 계약

당신은 아래 프롬프트를 처음 보는 실행자입니다.

## 대상 프롬프트
<전체 삽입>

## 시나리오
<상황>

## 체크리스트
1. [critical] ...
2. ...
3. ...

## 작업
1. 프롬프트 실행
2. 아래 형식으로 보고

## 보고서
- 결과:
- 체크리스트 평가:
  - 항목: ○ / × / 부분 (이유)
- 불명확점:
- 임의 판단:
- 재시도:

---

환경 제약

Task tool 사용 불가 시:

empirical evaluation skipped: dispatch unavailable

자기 평가 금지

---

Iteration 기록 템플릿

Iteration N

변경점

• ...

결과

시나리오	성공	정확도	불명확점	임의 판단	tool_uses	duration_ms

불명확점

• ...

임의 판단

• ...

다음 수정

• ...

---

Red Flags (합리화 경계)

다음과 같은 사고는 prompt tuning을 무력화시키는 대표적인 오류다. 발견 즉시 수정해야 한다.

잘못된 합리화	실제 문제
"스스로 다시 읽으면 같은 효과가 있다"	작성자는 자신의 문장을 객관적으로 평가할 수 없다. 반드시 새로운 subagent를 dispatch해야 한다.
"1개 시나리오면 충분하다"	단일 시나리오는 과적합을 유발한다. 최소 2개, 권장 3개 이상 사용한다.
"불명확점이 한 번 0이 나왔으니 끝"	우연일 수 있다. 최소 2회 연속 0일 때만 수렴으로 판단한다.
"여러 문제를 한 번에 고치자"	어떤 수정이 효과를 냈는지 추적 불가능해진다. 1 iteration = 1 테마 원칙을 유지한다.
"작은 수정도 전부 나눠서 iter 돌리자"	과도한 분할은 iteration 폭발을 유발한다. 의미적으로 연결된 수정은 하나로 묶는다.
"메트릭이 좋으니 질적 피드백은 무시"	시간/step 감소는 오히려 정보 부족(프롬프트 약화)의 신호일 수 있다. 질적 피드백이 우선이다.
"차라리 처음부터 다시 쓰는 게 빠르다"	3회 이상 반복해도 개선이 없을 때만 재설계를 고려한다. 그 이전은 개선을 회피하는 행동이다.
"같은 subagent를 계속 쓰자"	subagent는 이전 실행을 학습한다. 반드시 매 iteration마다 새로운 subagent를 사용해야 한다.

실패 패턴

• subagent 미사용
• 동일 agent 재사용
• 시나리오 변경
• 체크리스트 변경
• [critical] 항목이 없음
• usage 메타 (tool_uses, duration_ms) 수집 실패

---

핵심 요약

1. subagent 실행
2. usage 메타 수집
3. 체크리스트 기반 평가
4. 최소 수정 반복

이 4가지를 지키지 않으면 결과는 신뢰할 수 없다.