prompt-shield: Instructions file for Claude Code

PromptShield

Prompt Quality Gate + PromptOps 표준 패키지 Claude Code + MCP 생태계의 프롬프트 품질 관리 표준

포지셔닝

이 프로젝트는 "Prompt improver"가 아닙니다.

우리의 목표:

• 훅(작성 시점 강제) + 레지스트리(자산화) + 테스트(회귀) + CI(게이트)
• 개발 조직이 원하는 "프롬프트 품질 표준"을 제공
• Eval/Red-team은 promptfoo와 연동으로 해결

아키텍처 개요

┌─────────────────────────────────────────────────────────────┐
│                     Developer Workflow                       │
├─────────────────────────────────────────────────────────────┤
│  [작성] ──→ [Hook: lint] ──→ [Commit] ──→ [CI: Gate] ──→ [Merge]
│                                              ↓
│                                    [Registry: Save]
│                                              ↓
│                                    [Eval: Regression]
└─────────────────────────────────────────────────────────────┘

핵심 모듈:
├── lint-engine/     # 단일 규칙 엔진 (Hook/CI 공유)
├── registry/        # MCP 서버 (버전/롤백/디프)
├── eval/            # 회귀 테스트 러너
├── pack/            # PromptPack 패키징
└── adapters/        # promptfoo 연동

개발 원칙

1. 결정적 제어 (Deterministic Control)

• Hook과 CI는 같은 규칙 엔진을 사용해야 함
• "환경마다 점수가 다름"은 신뢰를 깨뜨림
• 결과는 항상 예측 가능해야 함

2. Gate > Report

• "리포트만 남김"은 Gate가 아님
• 품질 기준 미달 시 빌드 실패 (exit 1)
• 경고만 남기는 기능은 Gate로 인정하지 않음

3. 로컬 우선

• 모든 기능은 로컬에서 먼저 동작해야 함
• Claude CLI 기반 실행 지원
• 외부 서비스 의존성 최소화

4. 연동 > 구현

• 이미 강력한 도구가 있으면 연동
• promptfoo: eval/red-team
• Claude Code: hooks
• 중복 구현 금지

코드 컨벤션

파일 구조

skills/prompt-shield/
├── playbooks/           # 스킬 실행 플레이북
├── scripts/             # CI/실행 스크립트
├── plugins/             # MCP 서버 플러그인
│   └── prompt-registry/ # Registry MCP 서버
└── docs/                # 문서

스크립트 작성

• CI 스크립트는 exit code 정책 명확히
• threshold는 config 파일로 (하드코딩 금지)
• 실패 메시지에 원인 포함 (파일/점수/기준)

MCP 서버

• MCP spec 준수: tools/resources/prompts capability
• 에러 메시지 표준화 (isError=true로 self-correct 유도)
• 버전 히스토리 유지 (rollback/diff 지원)

테스트

• 결정적 assertion 우선 (contains/regex/json schema)
• LLM judge는 보조적 (나중에)
• 캐시 지원 (동일 입력 재실행 비용 절감)