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

zhongwei/gh-wasabeef-claude-code-cookbook-plugins-ko

Files

Zhongwei Li f525cc10dc Initial commit

2025-11-30 09:05:40 +08:00

16 KiB

Raw Permalink Blame History

프롬프트 품질 검사

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

사용법

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

옵션

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

기본 사용 예시

# 프롬프트 전체 품질 평가
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 문제의 완전 해결을 최우선
단계적 구현: 한 번에 모든 변경을 하지 말고 검증 가능한 단위로 실시
효과 측정: 개선 전후의 정량적 비교
지속적 모니터링: 개선 효과의 지속성 확인

✅ 애매함 제거의 실천 기법

# ❌ 개선 전 (애매함)

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

# ✅ 개선 후 (명확함)

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

✅ 정보 통합의 실천 기법

# ❌ 개선 전 (분산)

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

# ✅ 개선 후 (통합)

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

✅ 추적 시스템의 구현 패턴

# 실행 결과의 엄격한 추적
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

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

종합 점수 산출

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

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

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

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

품질 레벨 판정

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

🔧 실천적 개선 프로세스

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

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

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

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

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

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

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

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

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

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

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

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

개선 전 상황

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

실시한 개선 내용

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

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

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

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

개선 후 결과

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

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

교훈·베스트 프랙티스

성공 요인

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

실패 회피책

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

Claude 와의 연동

# 프롬프트 파일과 조합한 품질 체크
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 만 행 이상)의 경우 분할해서 분석할 것을 권장
권장사항: 정기적으로 프롬프트의 품질 체크를 수행하고 지속적으로 개선하세요

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

16 KiB Raw Permalink Blame History Unescape Escape