managing-prompts

name	managing-prompts
description	프롬프트 버전 관리, A/B 테스트, 이진 패턴 힌트, 품질 추적 등 프롬프트 시스템 전반을 다루는 스킬. 프롬프트 관련 질문이면 무조건 이 스킬을 먼저 확인할 것. 원격 프롬프트 업데이트 절차는 syncing-prompts 스킬 참조. Triggers: "프롬프트 버전 관리", "A/B 테스트 만들어", "SuperMemo 규칙", "Cloze Enhancer", "프롬프트 성능", "카드 길이 기준", "이진 패턴", "실패 패턴 분석", "시스템 프롬프트 구조", "system prompt 타입", "프롬프트 마이그레이션", "히스토리", "반려 사유", "활성 버전", "메트릭".

프롬프트 관리

프롬프트 버전 관리 개요

프롬프트 버전 관리, A/B 테스트, 품질 추적 시스템. SuperMemo's Twenty Rules 기반 카드 분할 품질 보장.

저장 구조

output/prompts/
├── versions/           # 버전 파일 (v1.0.0.json 등)
├── history/            # 분할 히스토리 (날짜별)
├── experiments/        # A/B 테스트
└── active-version.json # 현재 활성 버전

핵심 데이터 구조

• PromptVersion: id, name, description, createdAt, updatedAt, systemPrompt, splitPromptTemplate, analysisPromptTemplate, examples, config, status, metrics, modificationPatterns, parentVersionId?, changelog?
• SplitHistoryEntry: id, timestamp, promptVersionId, noteId, deckName, originalContent, originalCharCount, originalTags?, splitCards, userAction, rejectionReason?, modificationDetails?, aiModel?, splitReason?, executionTimeMs?, tokenUsage?, qualityChecks
• Experiment: id, name, createdAt, status, controlVersionId, treatmentVersionId, controlResults, treatmentResults, conclusion?, winnerVersionId?
• ActiveVersionInfo: versionId, activatedAt, activatedBy
• REJECTION_REASONS: 6개 상수 (too-granular, context-missing, char-exceeded, cloze-inappropriate, quality-low, other)

카드 길이 기준 / 필수 원칙

코드에서 직접 확인:

• 길이 기준: packages/core/src/prompt-version/types.ts → DEFAULT_PROMPT_CONFIG
• 필수 원칙: packages/core/src/gemini/prompts.ts → SYSTEM_PROMPT
• 이진 패턴: packages/core/src/gemini/cloze-enhancer.ts → BINARY_PATTERNS

LLM 경로 구분

Note: Split 프롬프트는 packages/core/src/llm/factory.ts를 통해 멀티 LLM(Gemini/OpenAI) 지원. Cloze Enhancer는 packages/core/src/gemini/cloze-enhancer.ts에 위치하며, LLM API 호출 없이 순수 로컬 패턴 매칭 로직으로 동작합니다 (LLM 추상화 계층 미사용). gemini/ 디렉토리에 있는 것은 역사적 이유(초기 Gemini 전용 시절의 잔재)이며, 실제로는 LLM 독립적인 유틸리티입니다.

Cloze Enhancer (gemini/cloze-enhancer.ts)

이진 패턴 자동 감지 (26개)로 Yes/No Cloze에 힌트 자동 추가.

카테고리	예시	힌트
존재/상태	있다/없다	있다 | 없다
방향성	증가/감소	증가 ↑ | 감소 ↓
동기화	동기/비동기	Sync | Async
상태	상태/무상태	Stateful | Stateless
계층	물리/논리	Physical | Logical

주요 함수: analyzeClozes(), checkCardQuality(), detectBinaryPattern(), enhanceCardsWithHints(), countCardChars(), detectCardType()

Self-Correction 루프

1. 모바일 친화성 확인 (AnkiDroid 스크롤 없이 읽기)
2. 길거리 쪽지 테스트 (맥락 자족성)
3. 유일 답 검증
4. 고아 카드 검증 (주제당 최소 2개)
5. 불합격 시 수정 + qualityChecks 기록

주요 API

// 버전 관리
await listPromptVersions();          // storage.ts: listVersions()
await getPromptVersion('v1.0.0');    // storage.ts: getVersion()
await createPromptVersion({ name, systemPrompt, ... }); // storage.ts: createVersion()
await savePromptVersion(version);    // storage.ts: saveVersion()
await deletePromptVersion('v1.0.0'); // storage.ts: deleteVersion()
await setActiveVersion('v1.0.0');

// 히스토리 & 메트릭
await addHistoryEntry({ promptVersionId, noteId, ... });
await recordPromptMetricsEvent({ promptVersionId, userAction, splitCards });

// 실패 패턴 분석
const { patterns, insights } = await analyzeFailurePatterns('v1.0.0');

// A/B 테스트
await createExperiment('테스트명', 'v1.0.0', 'v1.1.0');
await getExperiment('exp-id');

export 이름 규칙: storage.ts 내부 함수명(listVersions, getVersion, saveVersion 등)은 packages/core/src/index.ts에서 AnkiConnect getVersion과의 충돌을 피하기 위해 as 별칭으로 re-export됩니다 (listPromptVersions, getPromptVersion, savePromptVersion 등). 함수 자체가 이름이 다른 게 아니라, re-export 별칭입니다.

자주 발생하는 문제

• export 이름 충돌: storage.ts의 getVersion 등은 index.ts에서 as getPromptVersion으로 re-export (별칭, 함수명 자체 변경 아님)
• SplitWorkspace 버전 선택: 헤더 드롭다운에서 활성 버전 ✓ 표시
• 히스토리 자동 기록: 분할 적용 시 /api/prompts/history로 자동 전송

상세 참조

• references/version-system.md — PromptVersion 타입, 저장 구조 상세
• references/supermemo-rules.md — 20 Rules, 카드 길이 기준
• references/cloze-enhancer.md — 이진 패턴 26개, 품질 검사
• references/troubleshooting.md — Phase 1 프롬프트 개선 결정사항