wasabeef AI 프롬프트 품질 평가 및 개선 제안
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 만 행 이상)의 경우 분할해서 분석할 것을 권장
- 권장사항: 정기적으로 프롬프트의 품질 체크를 수행하고 지속적으로 개선하세요
이 체크리스트는 실제 프롬프트 개선 프로젝트에서 실증된 지식의 완전판이고, 지속적으로 진화하고 있습니다.