| 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. 베이스라인 준비
시나리오
- 2
3개 (중앙 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] 항목이 모두 ○ → 성공- 하나라도 × 또는 부분 → 실패
정확도 계산
실패 시 규칙
- 어떤
[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) 수집 실패
핵심 요약
- subagent 실행
- usage 메타 수집
- 체크리스트 기반 평가
- 최소 수정 반복
이 4가지를 지키지 않으면 결과는 신뢰할 수 없다.
