/check-prompt

프롬프트 품질 검사

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

✅ 애매함 제거의 실천 기법

# ❌ 개선 전 (애매함)

"지적사항은 원칙적으로 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 일)

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. 최적화 지속: 지속적인 개선 사이클

---

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

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

개선 전 상황

품질 점수: 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% 향상

교훈·베스트 프랙티스

성공 요인

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

실패 회피책

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

---

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

---

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