refactor: mobile-friendly split + compact 전략으로 전환

[greenheadHQ]

Summary

현재 atomic split 전략(카드당 1 fact, max 80자, 1 Cloze)을 mobile-friendly 전략으로 전환한다. split/compact/skip 삼자택일 operation 모델을 도입하여, LLM이 카드 특성에 맞는 최적 작업을 판정한다. 과도한 분할로 인한 학습 효과 저하 문제를 해결한다.

Context

• 현 상태: SuperMemo "Minimum Information Principle"을 엄격하게 적용하여 카드를 극도로 잘게 분할함 (예: CSS 명시도 1매 → 11매, DNS 1매 → 10매)
• 문제점: 이력 목록의 대부분이 "rejected" 상태. 과도한 분할이 오히려 학습 효과를 저하시킴
• 필요성: "모바일 AnkiDroid에서 스크롤 없이 표시"를 기준으로, split/compact/skip을 LLM이 판단하는 유연한 전략 필요
• 관련 이슈: refactor: split을 atomic하게 하지 말고, mobile-friendly하게만 스플릿하도록 하면 좋을듯? #102 (원본 제안)

Related Commits

• fe8c118 — refactor: Hard Split 제거 및 Split 단일화 (refactor: Hard Split 제거 및 Split 단일화 #45)
• 0338005 — docs: mobile-friendly split + compact 디자인 스펙 초안
• 62ef2d4 — docs: 2차 spec review suggestion 반영 및 status 업데이트
• 038b2fd — docs: mobile-friendly split + compact 구현 계획 작성

Affected Files

File	Role	Required Change
packages/core/src/parser/text-length.ts	신규	HTML/Cloze/Callout 제거 후 순수 텍스트 길이 계산 유틸리티
packages/core/src/gemini/validator.ts	Zod 검증	discriminated union 스키마 (split/compact/skip) + 레거시 shouldSplit 폴백
packages/core/src/splitter/atomic-converter.ts	트리거 판정	analyzeForOptimization (Cloze 수 OR 텍스트 길이 초과)
packages/core/src/gemini/prompts.ts	LLM 프롬프트	SYSTEM_PROMPT 전면 개편 (atomic → mobile-friendly), buildOptimizationPrompt
packages/core/src/gemini/client.ts	LLM 클라이언트	requestCardOptimization, estimateOptimizationCost
packages/core/src/prompt-version/types.ts	타입/상수	REJECTION_REASONS 업데이트, PromptConfig deprecated
packages/server/src/routes/split.ts	API 라우트	operation 분기 (preview/apply), compact apply 경로
packages/server/src/routes/cards.ts	API 라우트	needsOptimization, filter alias
packages/server/src/history/store.ts	이력 저장소	operation 컬럼, markGenerated compact 분기
packages/web/src/pages/SplitWorkspace.tsx	UI 메인	operation별 프리뷰 뷰, compact diff 뷰
packages/web/src/pages/CardBrowser.tsx	UI	canSplit → needsOptimization
packages/web/src/components/card/AuditReportPanel.tsx	신규	Compact 감사 보고서 패널
packages/web/src/components/card/CompactDiffView.tsx	신규	Compact 2-pane diff 뷰

Proposed Changes

Core Layer

• computeTextLength 유틸리티 추가 (HTML/Cloze/Callout 제거 후 순수 텍스트 길이)
• Zod discriminated union 스키마 (operation: split | compact | skip) + 레거시 shouldSplit 폴백 변환
• analyzeForOptimization — Cloze 수 OR 텍스트 길이(500자) 초과 시 트리거
• SYSTEM_PROMPT 전면 개편: atomic → mobile-friendly, operation 판정 가이드, compact 지침
• buildOptimizationPrompt + OPTIMIZATION_RESPONSE_FORMAT
• requestCardOptimization, estimateOptimizationCost
• REJECTION_REASONS 업데이트 (char-exceeded 제거, over-compressed/info-lost 추가)

Server Layer

• systemPrompt 해시 기반 마이그레이션 (구버전 자동 갱신)
• 기존 프롬프트 버전 archived + 새 기본 버전 생성
• routes/cards.ts — needsOptimization, filter alias
• routes/split.ts — operation 분기 (preview: split/compact/skip, apply: split/compact)
• History store — operation 컬럼, markGenerated/markApplied compact 분기

Web Layer

• OptimizationPreviewResult discriminated union 타입
• AuditReportPanel (preserved/removed/transformed 컬러 태그)
• CompactDiffView (원본 vs compact 2-pane)
• SplitWorkspace operation 분기 + CardBrowser needsOptimization
• History 페이지 operation 배지 + compact 상세 뷰

Notes

• 디자인 스펙: docs/superpowers/specs/2026-03-22-mobile-friendly-split-design.md
• 구현 계획: docs/superpowers/plans/2026-03-22-mobile-friendly-split.md
• 기존 함수명(requestCardSplit 등)은 deprecated wrapper로 유지하여 하위 호환 보장
• feat(web): Validate 탭 — All-in-One 카드 건강 허브 #93 (Validate 탭)의 Phase 2에서 requestCardSplit 재사용 → 이 리팩토링 완료 후 requestCardOptimization으로 전환 필요
• MAX_TEXT_LENGTH = 500은 모바일 AnkiDroid 실제 테스트 후 튜닝 예정

[greenheadHQ]

LLM 이행 가이드 — Mobile-Friendly Split + Compact

대상: packages/core (validator, prompts, client, parser), packages/server (routes, history), packages/web (workspace, components)
목표: atomic split을 mobile-friendly optimization(split/compact/skip)으로 전환하여 과도한 분할을 방지한다
예상 소요: ~60분 (다중 세션, Phase별 독립 실행)
난이도: 복잡
관련 이슈: #103, #102

핵심 원칙

1. 진실 원천 우선: 이 가이드의 값보다 CLI/파일시스템에서 확인한 실제 값이 우선한다.
2. 기존 패턴 존중: deprecated wrapper로 하위 호환을 유지한다. 기존 함수명을 호출하는 코드가 즉시 깨지지 않도록 한다.
3. 구현 계획 참조: docs/superpowers/plans/2026-03-22-mobile-friendly-split.md를 Task 단위로 따라가되, 디자인 스펙 docs/superpowers/specs/2026-03-22-mobile-friendly-split-design.md이 최종 권위이다.

---

Phase 1: 사전 확인 + 아키텍처 파악

다음 명령으로 현재 상태를 확인한다 (병렬 가능):

# 1. 현재 SYSTEM_PROMPT 확인 — "Atomic Card" 문구 존재해야 함
grep -n "Atomic Card" packages/core/src/gemini/prompts.ts

# 2. 현재 validator 스키마 — shouldSplit 필드 존재해야 함
grep -n "shouldSplit" packages/core/src/gemini/validator.ts

# 3. 현재 트리거 조건 — MAX_CLOZES_PER_CARD = 3, analyzeForSplit 존재해야 함
grep -n "MAX_CLOZES_PER_CARD\|analyzeForSplit" packages/core/src/splitter/atomic-converter.ts

# 4. 현재 client 함수명 — requestCardSplit, estimateSplitCost
grep -n "export async function" packages/core/src/gemini/client.ts

# 5. 현재 history store — split_cards_json, splitCards.length
grep -n "split_cards_json\|splitCards" packages/server/src/history/store.ts | head -20

# 6. 현재 cards route — canSplit, isSplitable
grep -n "canSplit\|isSplitable\|analyzeForSplit" packages/server/src/routes/cards.ts

# 7. 디자인 스펙/구현 계획 존재 확인
ls docs/superpowers/specs/2026-03-22-mobile-friendly-split-design.md
ls docs/superpowers/plans/2026-03-22-mobile-friendly-split.md

기대 결과:

• SYSTEM_PROMPT에 "Atomic Card" 문구 존재 (→ 교체 대상)
• SplitResponseSchema에 shouldSplit: z.boolean() 존재 (→ discriminated union으로 교체)
• MAX_CLOZES_PER_CARD = 3, analyzeForSplit 존재 (→ analyzeForOptimization 추가)
• requestCardSplit, estimateSplitCost 존재 (→ rename + wrapper)
• 디자인 스펙/구현 계획 파일 존재

실제 값이 기대와 다르면: 실제 값을 기준으로 진행한다. 특히 #93 PR이 먼저 머지되어 파일 구조가 변경되었을 수 있다.

Phase 2: Core 기반 구조 (Task 1-3)

구현 계획 Task 1, 2, 3을 순서대로 실행한다. TDD 기반.

2-1. Text Length Utility (Task 1)

파일 생성: packages/core/src/parser/text-length.ts

const CLOZE_RE = /\{\{c\d+::([^:}]+)(?:::[^}]*)?\}\}/g;
const CALLOUT_MARKER_RE = /^:::\s*(?:tip|warning|error|note|link|toggle)\b[^\n]*/gm;
const CALLOUT_CLOSE_RE = /^:::$/gm;
const HTML_TAG_RE = /<[^>]+>/g;
const MULTI_WS_RE = /\s+/g;

export function computeTextLength(html: string): number {
  let text = html;
  text = text.replace(CLOZE_RE, "$1");
  text = text.replace(CALLOUT_MARKER_RE, "");
  text = text.replace(CALLOUT_CLOSE_RE, "");
  text = text.replace(HTML_TAG_RE, "");
  text = text.replace(MULTI_WS_RE, " ").trim();
  return text.length;
}

테스트 파일, export 추가 등은 구현 계획 Task 1의 Step 1-6을 그대로 따른다.

cd packages/core && bun test src/__tests__/text-length.test.ts

2-2. Zod Validator (Task 2)

파일 수정: packages/core/src/gemini/validator.ts

핵심 변경:

• SplitCardSchema: charCount 제거
• QualityChecksSchema: allCardsUnder80Chars/noEnumerations 제거
• OperationResponseSchema: discriminated union (split/compact/skip)
• convertLegacyResponse(): shouldSplit 감지 시 자동 변환
• validateOperationResponse(): 레거시 감지 → 변환 → 검증
• 기존 validateSplitResponse는 deprecated wrapper

cd packages/core && bun test src/__tests__/validator-operation.test.ts

2-3. Optimization Analysis (Task 3)

파일 수정: packages/core/src/splitter/atomic-converter.ts

BEFORE:

export function analyzeForSplit(htmlContent: string): SplitAnalysis {

AFTER (추가):

export const MAX_TEXT_LENGTH = 500;

export interface OptimizationAnalysis {
  needsOptimization: boolean;
  reasons: { clozeOverflow: boolean; textOverflow: boolean; };
  hasTodoBlock: boolean;
  clozeCount: number;
  textLength: number;
}

export function analyzeForOptimization(htmlContent: string): OptimizationAnalysis {
  // computeTextLength 사용, cloze + text 트리거
}

/** @deprecated Use analyzeForOptimization */
export function analyzeForSplit(htmlContent: string): SplitAnalysis {
  // 기존 로직 유지 (wrapper)
}

cd packages/core && bun test src/__tests__/optimization-analysis.test.ts

커밋

git add packages/core/src/parser/text-length.ts packages/core/src/__tests__/text-length.test.ts \
  packages/core/src/parser/index.ts packages/core/src/gemini/validator.ts \
  packages/core/src/__tests__/validator-operation.test.ts \
  packages/core/src/splitter/atomic-converter.ts packages/core/src/__tests__/optimization-analysis.test.ts
git commit -m "$(cat <<'EOF'
feat(core): mobile-friendly 기반 구조 — text-length, validator, optimization analysis

- computeTextLength: HTML/Cloze/Callout 제거 후 순수 텍스트 길이 계산
- OperationResponseSchema: split/compact/skip discriminated union + 레거시 폴백
- analyzeForOptimization: Cloze 수 OR 텍스트 길이(500자) 트리거

Part of #103
EOF
)"

Phase 3: Core 프롬프트 + 클라이언트 (Task 4-6)

3-1. System Prompt + Optimization Prompt (Task 4)

파일 수정: packages/core/src/gemini/prompts.ts

핵심 변경 (디자인 스펙 Section 2 참조):

• SYSTEM_PROMPT: "Atomic Card 생성 전문가" → "모바일 친화적 카드 최적화 전문가"
• 카드 길이 하드 리밋 전부 제거
• Operation 판정 가이드 (split/compact/skip) 추가
• Compact 지침 + auditReport 작성 지침 추가
• buildSplitPrompt → buildOptimizationPrompt
• SPLIT_RESPONSE_FORMAT → OPTIMIZATION_RESPONSE_FORMAT
• buildSplitPromptFromTemplate → buildOptimizationPromptFromTemplate

테스트: cd packages/core && bun test src/__tests__/optimization-prompt.test.ts

3-2. LLM Client (Task 5)

파일 수정: packages/core/src/gemini/client.ts

• requestCardSplit → requestCardOptimization (반환 타입: OperationResponse)
• estimateSplitCost → estimateOptimizationCost
• analyzeCardForSplit 인라인 프롬프트 → mobile-friendly 기준
• 기존 함수명은 deprecated wrapper

3-3. Types + Exports (Task 6)

파일 수정: packages/core/src/prompt-version/types.ts

BEFORE:

export const REJECTION_REASONS = [
  { id: "too-granular", label: "분할이 너무 세분화" },
  { id: "context-missing", label: "맥락 태그 부적절" },
  { id: "char-exceeded", label: "글자수 초과" },
  // ...

AFTER:

export const REJECTION_REASONS = [
  { id: "too-granular", label: "분할이 너무 세분화" },
  { id: "context-missing", label: "맥락 태그 부적절" },
  { id: "cloze-inappropriate", label: "Cloze 위치/내용 부적절" },
  { id: "quality-low", label: "전반적 품질 미달" },
  { id: "over-compressed", label: "과도한 압축" },
  { id: "info-lost", label: "핵심 정보 누락" },
  { id: "other", label: "기타" },
] as const;

PromptConfig 모든 char limit 필드에 @deprecated JSDoc.

파일 수정: packages/core/src/index.ts — 새 함수/타입 re-export.

커밋

git add packages/core/src/gemini/prompts.ts packages/core/src/__tests__/optimization-prompt.test.ts \
  packages/core/src/gemini/client.ts packages/core/src/prompt-version/types.ts packages/core/src/index.ts
git commit -m "$(cat <<'EOF'
feat(core): mobile-friendly prompts, client, types, exports

- SYSTEM_PROMPT: atomic → mobile-friendly 전면 개편
- buildOptimizationPrompt + OPTIMIZATION_RESPONSE_FORMAT
- requestCardOptimization, estimateOptimizationCost
- REJECTION_REASONS: char-exceeded 제거, over-compressed/info-lost 추가

Part of #103
EOF
)"

Phase 4: Server Layer (Task 7-9)

4-1. History Types + Store (Task 7)

파일 수정: packages/server/src/history/types.ts

• SplitSessionListItem에 operation: "split" | "compact" | "skip" 추가
• SplitCardPayload에서 charCount 제거
• SplitGeneratedPayload.splitCards → optional
• SplitGeneratedPayload에 operation, compactedContent, auditReport 추가
• SplitAppliedPayload.splitCards → optional, operation/compactedContent 추가
• CompactPayload 인터페이스 추가

파일 수정: packages/server/src/history/store.ts

• DB 마이그레이션: ALTER TABLE split_sessions ADD COLUMN operation TEXT NOT NULL DEFAULT 'split'
• markGenerated: payload.splitCards?.length ?? 0 guard, compact 데이터를 ai_response_json에 저장
• markApplied: compact 분기 추가
• 쿼리에서 operation 컬럼 포함

4-2. SystemPrompt Migration (Task 8)

서버 시작 시 remote systemPrompt 해시 비교 → 구버전이면 자동 갱신. 기존 프롬프트 버전 archived + 새 기본 버전 생성.

4-3. Server Routes (Task 9)

파일 수정: packages/server/src/routes/cards.ts

BEFORE: isSplitable: analysis.canSplit
AFTER: needsOptimization: analysis.needsOptimization, reasons: analysis.reasons, textLength: analysis.textLength

filter 파라미터: "optimizable" 추가, "splitable" alias 유지.

파일 수정: packages/server/src/routes/split.ts

• import 변경: requestCardOptimization, estimateOptimizationCost
• preview: operation별 분기 (split/compact/skip), 응답 필드 operationReason (not splitReason)
• apply: operation: "compact" → updateNoteFields로 원본 content 교체, 새 카드 없음

커밋

git add packages/server/src/history/ packages/server/src/routes/
git commit -m "$(cat <<'EOF'
feat(server): operation branching, history compact support, systemPrompt migration

- history: operation 컬럼, markGenerated/markApplied compact 분기
- routes/cards: needsOptimization, filter alias
- routes/split: operation별 preview/apply, operationReason 필드
- systemPrompt: 해시 기반 자동 마이그레이션

Part of #103
EOF
)"

Phase 5: Web Layer (Task 10-13)

5-1. API Types + Hooks (Task 10)

파일 수정: packages/web/src/lib/api.ts

• SplitPreviewResult → OptimizationPreviewResult discriminated union
• CardSummary.analysis: canSplit → needsOptimization, estimatedCards 제거

파일 수정: packages/web/src/hooks/useSplit.ts

• apply mutation에 operation 필드 추가
• compact: compactedContent 전송

5-2. Compact UI Components (Task 11)

파일 생성:

• packages/web/src/components/card/AuditReportPanel.tsx — preserved(초록)/removed(빨강)/transformed(노랑) 컬러 태그
• packages/web/src/components/card/CompactDiffView.tsx — 2-pane diff (데스크톱: 좌우, 모바일: 탭)

5-3. SplitWorkspace + CardBrowser (Task 12)

파일 수정: packages/web/src/pages/SplitWorkspace.tsx

• REJECTION_REASONS 업데이트 (char-exceeded 제거, over-compressed/info-lost 추가)
• SplitCandidate.analysis: canSplit → needsOptimization, reasons/textLength 추가
• Preview 영역: operation === "split" → 기존 뷰, "compact" → CompactDiffView, "skip" → 메시지
• Apply 버튼: compact 시 "압축 적용"

파일 수정: packages/web/src/pages/CardBrowser.tsx

• analysis.canSplit → analysis.needsOptimization 변경

5-4. History Page (Task 13)

파일 수정: packages/web/src/pages/SplitHistory.tsx

• operation 배지 (Split/Compact)
• compact 상세 뷰: CompactDiffView + AuditReportPanel

커밋

git add packages/web/
git commit -m "$(cat <<'EOF'
feat(web): operation UI — compact diff view, audit report, workspace branching

- OptimizationPreviewResult discriminated union
- AuditReportPanel + CompactDiffView 신규 컴포넌트
- SplitWorkspace/CardBrowser: operation별 렌더링 분기
- History: operation 배지 + compact 상세 뷰

Part of #103
EOF
)"

Phase 6: 통합 검증 + 정리 + 커밋

정적 검증 (병렬 가능)

# 새 함수 존재
grep -q "analyzeForOptimization" packages/core/src/splitter/atomic-converter.ts
grep -q "validateOperationResponse" packages/core/src/gemini/validator.ts
grep -q "requestCardOptimization" packages/core/src/gemini/client.ts
grep -q "buildOptimizationPrompt" packages/core/src/gemini/prompts.ts
grep -q "needsOptimization" packages/server/src/routes/cards.ts
grep -q "operation" packages/server/src/history/types.ts

# old 패턴 부재 (primary code path에서)
! grep -q "shouldSplit" packages/core/src/gemini/prompts.ts
! grep -q "allCardsUnder80Chars" packages/core/src/gemini/validator.ts

빌드 + 테스트 검증

cd packages/core && bun test
bun run dev  # 서버+클라이언트 동시 시작, 수동 확인

수동 E2E 확인

1. 덱 선택 → 카드 목록에서 needsOptimization 배지 확인
2. 카드 선택 → 프리뷰 → LLM이 split/compact/skip 중 반환
3. compact → CompactDiffView + AuditReportPanel 표시
4. apply/reject 정상 동작
5. 이력 페이지 operation 배지

Deprecated wrapper 정리

모든 deprecated wrapper에 JSDoc @deprecated + Use XXX instead 추가.

스킬 문서 업데이트

@splitting-cards 스킬 문서를 mobile-friendly 전략에 맞게 업데이트.

최종 커밋

git add -A
git commit -m "$(cat <<'EOF'
chore: deprecation markers, skill docs, integration cleanup

Part of #103
EOF
)"

DA 피드백 + PR

구현 완료 후:

1. /run-da for_pr — 코드 품질 검증
2. /parallel-audit 10 — 전수조사
3. /create-pr — PR 생성

주의사항

• feat(web): Validate 탭 — All-in-One 카드 건강 허브 #93 Validate 탭과의 충돌: feat(web): Validate 탭 — All-in-One 카드 건강 허브 #93 PR이 먼저 머지될 수 있다. Phase 1에서 파일 구조 변경 여부를 반드시 확인한다. requestCardSplit → requestCardOptimization rename이 #93의 Validate 코드에도 영향을 줄 수 있다.
• Remote systemPrompt: 사용자가 커스터마이즈한 경우 자동 덮어쓰지 않는다. 서버 로그 경고만.
• MAX_TEXT_LENGTH = 500: 모바일 AnkiDroid 실제 테스트 후 튜닝 필요. 초기값은 보수적.
• Cloze 정규식: computeTextLength의 Cloze 정규식이 :: 포함 답(예: URL)을 잘못 파싱할 수 있다. 테스트에서 edge case 확인.

[greenheadHQ]

Close 사유

오버엔지니어링. split/compact/skip 삼자택일 + auditReport + CompactDiffView 등 불필요한 복잡성이 추가되어 PR #105에서 구현 실패.

원래 의도: 프롬프트의 atomic 제약(글자수 하드리밋, 카드당 1 Cloze)을 완화하여 mobile-friendly하게 분할.

→ 간결한 새 이슈로 대체 예정. 범위: 프롬프트 변경만.