gh-wasabeef-claude-code-cookbook-plugins-ko/commands/check-prompt.md

## 프롬프트 품질 검사

AI Agent 용 프롬프트의 품질을 평가·개선하기 위한 포괄적 베스트 프랙티스 모음집입니다. 실제 프롬프트 개선 프로세스에서 쌓은 지식을 체계화하고, 애매함 제거·정보 통합·강제력 강화·추적 시스템·지속적 개선 등 모든 중요 관점을 망라합니다.

### 사용법

```bash
# 프롬프트 파일의 품질 체크
cat your-prompt.md
/check-prompt
"이 프롬프트의 품질을 체크하고 개선안을 제시하세요"
```

### 옵션

- 없음 : 현재 파일 또는 선택한 텍스트 분석
- `--category <name>` : 특정 카테고리만 체크 (structure/execution/restrictions/quality/roles/improvement)
- `--score` : 품질 점수만 산출
- `--fix` : 검출된 문제를 자동 수정 제안
- `--deep` : 심층 분석 모드 (애매함·정보 분산·강제력을 중점 체크)

### 기본 사용 예시

```bash
# 프롬프트 전체 품질 평가
cat devin/playbooks/code-review.md
/check-prompt
"이 프롬프트의 품질을 6 개 카테고리로 평가하고, 문제점과 개선안을 제시하세요"

# 심층 분석 모드
/check-prompt --deep
"애매함·정보 분산·강제력 부족을 중점적으로 체크하고 근본적인 개선안을 제시하세요"

# 특정 카테고리 체크
/check-prompt --category structure
"구조와 명확성 관점으로 이 프롬프트를 체크하세요"

# 애매한 표현 검출 및 수정
/check-prompt --fix
"애매한 표현을 검출하고 명확한 표현으로 수정 제안하세요"
```

---

## 핵심 설계 원칙

### 원칙 1: 해석의 여지를 완전히 배제

- **절대 금지**: "원칙적으로" "권장" "가능하면" "상황에 따라" "적절히 판단"
- **필수 사용**: "반드시" "절대로" "엄수" "예외 없이" "강제"
- **예외 조건**: 수치로 엄격하게 한정 ("다음 3 가지 조건만" "이 2 가지 경우를 제외하고")

### 원칙 2: 정보의 전략적 통합

- 관련된 중요 정보는 하나의 섹션에 완전 통합
- 실행 체크리스트에 전체상 요약
- 참조의 순환이나 분산을 철저히 배제

### 원칙 3: 단계적 강제력 구축

- 🔴 (실행 중지 레벨) → 🟡 (품질 중요) → 🟢 (권장사항)의 명확한 계층
- 권장 레벨에서 필수 레벨로의 점진적 승격
- 위반 시 영향도와 대처법 명시

### 원칙 4: 추적 가능성 확보

- 모든 실행 결과를 기록·검증 가능
- 허위 보고를 기술적으로 방지
- 성공/실패의 객관적 판단 기준

### 원칙 5: 피드백 주도 개선

- 실제 실패 사례로부터 학습
- 지속적인 효과성 검증
- 새로운 패턴의 자동 검출

---

## 📋 포괄적 체크 항목

### 1. 📐 구조와 명확성 (배점: 25 점)

#### 1.1 지시사항 우선순위 표시 (8 점)

- [ ] 🔴🟡🟢 우선순위가 모든 중요 지시사항에 명시되어 있음
- [ ] 실행 중지 레벨 조건이 구체적이고 명확하게 정의됨
- [ ] 각 우선순위의 판단 기준이 객관적이고 검증 가능함
- [ ] 우선순위 계층이 일관되게 적용됨

#### 1.2 애매한 표현의 완전 배제 (9 점)

- [ ] **치명적 애매 표현**: "원칙적으로" "권장" "가능하면"이 0 개
- [ ] **강제 표현 사용**: "반드시" "절대로" "엄수" "예외 없이"를 적절히 사용
- [ ] **예외 조건의 수치 한정**: "3 가지 조건만" 등 명확한 경계선
- [ ] **판단 여지 배제**: 여러 해석이 불가능한 표현만 사용
- [ ] **그레이존 박멸**: 모든 상황에서 명확한 판단 기준

#### 1.3 정보의 전략적 통합 (8 점)

- [ ] 중요 정보의 여러 곳 분산이 완전히 해소됨
- [ ] 관련 지시사항이 논리적으로 하나의 섹션에 통합됨
- [ ] 실행 체크리스트에 전체상이 빠짐없이 요약됨
- [ ] 참조의 순환이나 무한 루프가 존재하지 않음

### 2. 🎯 실행 가능성 (배점: 20 점)

#### 2.1 구체적 절차의 완전성 (7 점)

- [ ] 모든 명령어 예시가 실제로 실행 가능하고 검증됨
- [ ] 환경변수·전제조건·의존성이 빠짐없이 명기됨
- [ ] 오류 시 대처법이 구체적이고 실행 가능함
- [ ] 절차 순서가 논리적이고 필연성이 있음

#### 2.2 검증 가능성 확보 (7 점)

- [ ] 실행 결과의 성공/실패가 객관적으로 판단 가능함
- [ ] 출력 예시·로그 형식·기대값이 구체적으로 제시됨
- [ ] 테스트 방법·검증 절차가 구현 가능함
- [ ] 중간 결과 확인 포인트가 적절히 배치됨

#### 2.3 자동화 적응성 (6 점)

- [ ] 스크립트화·CI/CD 통합이 용이한 형식
- [ ] 인간 판단 부분과 AI 실행 부분의 명확한 분리
- [ ] 배치 처리·병렬 실행 대응

### 3. 🚫 금지사항의 명확화 (배점: 15 점)

#### 3.1 절대 금지사항의 체계화 (8 점)

- [ ] 실행해서는 안 되는 조작의 완전한 목록화
- [ ] 각 금지사항의 위반 시 영향도 (경미/심각/치명적) 명시
- [ ] 대안 수단·회피 방법의 구체적 제시
- [ ] 금지사항의 기술적 근거 설명

#### 3.2 예외 조건의 엄격한 한정 (7 점)

- [ ] 예외를 인정하는 조건이 구체적이고 한정적 (수치 지정)
- [ ] "완전히 중복" "명시적으로 기재" 등 객관적 판단 기준
- [ ] 그레이존을 남기지 않는 명확한 경계선
- [ ] 예외 적용 시 추가 조건·제약 명시

### 4. 📊 품질 보증 메커니즘 (배점: 20 점)

#### 4.1 추적 시스템의 완전성 (8 점)

- [ ] 전체 실행 결과의 자동 기록·통계 획득 기능
- [ ] 허위 보고를 기술적으로 방지하는 검증 기능
- [ ] 실시간 모니터링·알림 기능
- [ ] 감사 로그의 변조 방지 기능

#### 4.2 템플릿 준수의 강제 (7 점)

- [ ] 필수 요소의 명확한 정의와 체크 기능
- [ ] 커스터마이즈 금지 부분의 기술적 제한
- [ ] 준수 확인의 자동화된 체크포인트
- [ ] 위반 시 자동 수정·경고 기능

#### 4.3 오류 처리의 망라성 (5 점)

- [ ] 예상 오류 패턴의 완전한 카탈로그화
- [ ] 오류 시의 단계적 대처 프로세스
- [ ] 실패를 성공으로 보고하는 것의 기술적 방지

### 5. 🎭 역할과 책임의 명확화 (배점: 10 점)

#### 5.1 AI Agent 의 권한 범위 (5 점)

- [ ] 실행 가능 조작과 금지 조작의 명확한 경계선
- [ ] 판단 권한의 구체적 범위와 제약
- [ ] 인간 확인이 필요한 조작의 명확한 분리

#### 5.2 분류 시스템의 통일 (5 점)

- [ ] 분류 정의의 명확성·유일성·배타성
- [ ] 분류 간 중요도 오해를 방지하는 명시적 설명
- [ ] 각 분류의 구체적 사용 예시와 판단 플로차트

### 6. 🔄 지속적 개선 (배점: 10 점)

#### 6.1 피드백 수집의 자동화 (5 점)

- [ ] 실행 로그로부터의 자동 개선점 추출
- [ ] 실패 패턴의 머신러닝 기반 분석
- [ ] 베스트 프랙티스의 자동 업데이트 메커니즘

#### 6.2 학습 기능의 구현 (5 점)

- [ ] 새로운 패턴의 자동 검출·분류
- [ ] 기존 규칙의 효과성 지속 모니터링
- [ ] 단계적 개선의 자동 제안

---

## 🚨 치명적 문제 패턴 (즉시 수정 요함)

### ❌ 레벨 1: 치명적 애매함 (실행 중지 레벨)

- **여러 해석 가능한 지시**: "적절히 판단해서" "상황에 따라" "원칙적으로"
- **애매한 예외 조건**: "특별한 경우는" "필요에 따라"
- **주관적 판단 기준**: "적절히" "충분히" "가능한 한"
- **미정의 중요 개념**: "표준적인" "일반적인" "기본적인"

### ❌ 레벨 2: 구조적 결함 (품질 중요 레벨)

- **정보 분산**: 관련 중요 정보가 3 곳 이상에 산재
- **순환 참조**: 섹션 A→B→C→A 의 무한 루프
- **모순되는 지시**: 다른 섹션에서 상반되는 지시
- **실행 순서 불명확**: 의존관계가 불분명한 절차

### ❌ 레벨 3: 품질 저하 (권장 개선 레벨)

- **검증 불가능성**: 성공/실패 판단 기준이 불명
- **자동화 곤란**: 인간의 주관적 판단에 의존하는 설계
- **보수 곤란**: 업데이트 시 영향 범위를 예측할 수 없는 구조
- **학습 곤란**: 신입이 이해하기까지 오랜 시간이 걸리는 복잡함

---

## 🎯 실증된 개선 기법

### ✅ 단계적 강화 접근법

1. **현황 분석**: 문제 분류·우선순위·영향도 평가
2. **치명적 문제 우선**: 레벨 1 문제의 완전 해결을 최우선
3. **단계적 구현**: 한 번에 모든 변경을 하지 말고 검증 가능한 단위로 실시
4. **효과 측정**: 개선 전후의 정량적 비교
5. **지속적 모니터링**: 개선 효과의 지속성 확인

### ✅ 애매함 제거의 실천 기법

```markdown
# ❌ 개선 전 (애매함)

"지적사항은 원칙적으로 GitHub 상의 해당 변경 부분에 인라인 코멘트로 작성하세요"

# ✅ 개선 후 (명확함)

"지적사항은 GitHub 상의 해당 변경 부분에 인라인 코멘트로 반드시 작성하세요. 예외는 섹션 3.3 에서 정의된 3 가지 조건만입니다"
```

### ✅ 정보 통합의 실천 기법

```markdown
# ❌ 개선 전 (분산)

섹션 2.1: "필수 6 섹션 사용"
섹션 3.5: "📊 종합평가, 📋 지적사항..."
섹션 4.2: "섹션 삭제 금지"

# ✅ 개선 후 (통합)

실행 체크리스트:
□ 10. 요약 코멘트를 투고 (필수 6 섹션 사용)
🔴 필수 6 섹션: 1) 📊 종합평가 2) 📋 지적사항의 분류별 집계 3) ⚠️ 주요 우려사항 4) ✅ 평가할 수 있는 점 5) 🎯 결론 6) 🤖 AI 리뷰 품질의 자기평가
❌ 절대 금지: 섹션 삭제·추가·이름 변경
```

### ✅ 추적 시스템의 구현 패턴

```bash
# 실행 결과의 엄격한 추적
POSTED_COMMENTS=0
FAILED_COMMENTS=0
TOTAL_COMMENTS=0

# 각 조작의 결과 기록
if [ $? -eq 0 ]; then
    echo "✅ 성공: $OPERATION" >> /tmp/execution_log.txt
    POSTED_COMMENTS=$((POSTED_COMMENTS + 1))
else
    echo "❌ 실패: $OPERATION" >> /tmp/execution_log.txt
    FAILED_COMMENTS=$((FAILED_COMMENTS + 1))
fi

# 허위 보고 방지
if [ $POSTED_COMMENTS -ne $REPORTED_COMMENTS ]; then
    echo "🚨 경고: 보고 수와 실제 투고 수가 불일치"
    exit 1
fi
```

---

## 📈 품질 점수 계산 (개선판)

### 종합 점수 산출

```text
기본 점수 = Σ(각 카테고리 점수 × 배점) / 100

치명적 문제 페널티:
- 레벨 1 문제: -20 점/건
- 레벨 2 문제: -10 점/건
- 레벨 3 문제: -5 점/건

보너스 요소:
- 자동화 대응: +5 점
- 학습 기능 구현: +5 점
- 실증된 개선 사례: +5 점

최종 점수 = 기본 점수 + 보너스 - 페널티
```

### 품질 레벨 판정

```text
95-100 점: 세계 최고 수준 (업계 표준으로 추천 가능)
90-94 점:  우수 (프로덕션 운용 가능)
80-89 점:  양호 (경미한 개선으로 운용 가능)
70-79 점:  보통 (개선 필요)
60-69 점:  개선 요망 (대폭 수정 필요)
50-59 점:  대폭 수정 요망 (근본적 재검토 필요)
49 점 이하: 사용 금지 (완전한 재설계 필요)
```

---

## 🔧 실천적 개선 프로세스

### 페이즈 1: 진단·분석 (1-2 일)

1. **전체 구조 파악**: 섹션 구성·정보 플로·의존관계 시각화
2. **애매함 검출**: 해석 여지가 있는 표현의 전건 추출
3. **정보 분산 분석**: 관련 정보의 산재 패턴 매핑
4. **강제력 평가**: 권장/필수의 분류와 실효성 평가
5. **추적 가능성 확인**: 실행 결과의 기록·검증 기능 평가

### 페이즈 2: 우선순위·계획 (반나절)

1. **치명도 분류**: 레벨 1-3 의 문제 분류와 영향도 평가
2. **개선 순서 결정**: 상호 의존관계를 고려한 최적 순서
3. **리소스 배분**: 개선 효과와 비용의 균형 최적화
4. **위험 평가**: 개선 시 부작용·호환성 문제 예측

### 페이즈 3: 단계적 구현 (2-5 일)

1. **레벨 1 문제 해결**: 치명적 애매함의 완전 배제
2. **정보 통합 실시**: 분산 정보의 전략적 집약
3. **강제력 강화**: 권장 → 필수로의 단계적 승격
4. **추적 시스템 구현**: 실행 결과의 자동 기록·검증 기능
5. **템플릿 강화**: 필수 요소의 명확화와 준수 강제

### 페이즈 4: 검증·조정 (1-2 일)

1. **기능 테스트**: 모든 변경점의 동작 확인
2. **통합 테스트**: 시스템 전체의 정합성 확인
3. **성능 테스트**: 실행 효율·응답 확인
4. **사용성 테스트**: 실제 사용 시나리오에서의 검증

### 페이즈 5: 운영·모니터링 (지속)

1. **효과 측정**: 개선 전후의 정량적 비교
2. **지속적 모니터링**: 품질 저하의 조기 검출
3. **피드백 수집**: 실제 운영에서의 문제점 추출
4. **최적화 지속**: 지속적인 개선 사이클

---

## 📊 실제 개선 사례 (상세판)

### 케이스 스터디: 대규모 프롬프트의 품질 개선

#### 개선 전 상황

```bash
품질 점수: 70 점/100 점
- 애매 표현: 15 곳 발견
- 정보 분산: 6 곳에 중요 정보 산재
- 강제력 부족: 권장 레벨 표현이 80%
- 추적 기능: 실행 결과 기록 없음
- 오류 처리: 실패 시 대처법 불분명
```

#### 실시한 개선 내용

```bash
# 1. 애매함 배제 (2 일간)
- "원칙적으로" → "예외는 섹션 3.3 의 3 가지 조건만"
- "권장" → "필수" (중요도 레벨 2 이상)
- "적절히" → 구체적인 판단 기준 명시

# 2. 정보 통합 (1 일간)
- 분산되었던 필수 6 섹션 정보 → 실행 체크리스트로 통합
- 관련 금지사항 → 하나의 섹션으로 집약
- 참조의 순환 해소 → 선형 정보 플로

# 3. 추적 시스템 구현 (1 일간)
- 실행 결과의 자동 로그 기록
- 허위 보고 방지 검증 기능
- 실시간 통계 표시

# 4. 오류 처리 강화 (반나절)
- 예상 오류 패턴의 완전한 카탈로그화
- 단계적 대처 프로세스 명문화
- 자동 복구 기능 구현
```

#### 개선 후 결과

```bash
품질 점수: 90 점/100 점 (+20 점 향상)
- 애매 표현: 0 곳 (완전 배제)
- 정보 통합: 중요 정보를 3 곳으로 집약
- 강제력: 필수 레벨 표현 95%
- 추적 기능: 완전 자동화
- 오류 처리: 90%의 문제를 자동 해결

실제 개선 효과:
- 판단 실수: 85% 감소
- 실행 시간: 40% 단축
- 오류 발생률: 70% 감소
- 사용자 만족도: 95% 향상
```

### 교훈·베스트 프랙티스

#### 성공 요인

1. **단계적 접근법**: 한 번에 모든 변경을 하지 말고 검증 가능한 단위로 실시
2. **데이터 주도**: 주관적 판단이 아닌 실측 데이터기반의 개선
3. **지속적 모니터링**: 개선 효과의 지속성을 정기적으로 확인
4. **피드백 중시**: 실제 사용자의 의견을 적극적으로 수집

#### 실패 회피책

1. **과도한 완벽주의**: 90 점 도달로 일단 운영 시작, 지속적 개선으로 100 점 목표
2. **일괄 변경의 위험성**: 대규모 변경은 반드시 단계적으로 실시
3. **후방 호환성**: 기존 워크플로에 대한 영향을 최소한으로 억제
4. **문서화 부족**: 모든 변경을 상세히 기록·공유

---

### Claude 와의 연동

```bash
# 프롬프트 파일과 조합한 품질 체크
cat your-prompt.md
/check-prompt
"이 프롬프트의 품질을 평가하고 개선점을 제안하세요"

# 여러 프롬프트 파일의 비교
cat prompt-v1.md && echo "---" && cat prompt-v2.md
/check-prompt
"두 버전을 비교하고 개선된 점과 남은 과제를 분석하세요"

# 실제 오류 로그와 조합한 분석
cat execution-errors.log
/check-prompt --deep
"이 오류를 일으켰을 가능성이 있는 프롬프트의 문제점을 파악하세요"
```

### 주의사항

- **전제조건**: 프롬프트 파일은 Markdown 형식으로 작성되어 있을 것을 권장
- **제한사항**: 대규모 프롬프트 (1 만 행 이상)의 경우 분할해서 분석할 것을 권장
- **권장사항**: 정기적으로 프롬프트의 품질 체크를 수행하고 지속적으로 개선하세요

---

_이 체크리스트는 실제 프롬프트 개선 프로젝트에서 실증된 지식의 완전판이고, 지속적으로 진화하고 있습니다._