CLI Referencelore synthesize

lore synthesize [category]

LLM 으로 L2 flow 파일을 재구성하기 위한 프롬프트를 빌드 합니다. 카테고리 인자를 생략하면 변경된 모든 카테고리를 한 프롬프트에 묶어 출력합니다.

lore synthesize                          # 변경된 모든 카테고리 — 가장 흔한 사용법
lore synthesize signal                   # 단일 카테고리만
lore synthesize --since 2.weeks          # 최근 2주 git log 포함
lore synthesize --force                  # synth 캐시 무시 + 전체 재합성
lore synthesize --apply                  # (v0.2 예정) Anthropic API 호출 + 파일 덮어쓰기

synthesize 는 .lore/flows/<slug>.md 에 사람이 읽는 L2 보고서 를 만듭니다. 코드 → L3 raw facts 단계는 lore sync 가 .lore/draft/<slug>.md 에 따로 적어둡니다.

변경 감지 (synth 캐시)

같은 어노테이션 집합을 두 번 합성하지 않습니다. 카테고리별로 어노테이션을 정규화한 sha256 해시를 .lore/.synth-cache/<slug>.json 에 저장하고, 다음 실행 시 비교해 변경이 없으면 그 카테고리는 프롬프트에서 제외합니다 (LLM 호출 비용 절약).

결과의미
unchanged해시 동일 + flow 파일 존재 → 스킵
forced--force 로 캐시 무시
no-cache첫 실행
hash-mismatch어노테이션 변경됨
flow-missing.lore/flows/<slug>.md 가 사라졌음

--force 로 캐시 무시 가능. 캐시는 프롬프트 emit 시점에 낙관적으로 갱신되며, 사용자/LLM 이 실제로 flow 파일을 안 쓰면 다음 실행에서 flow-missing 로 자동 회복합니다.

출력물 — 9-section 보고서 골격

프롬프트는 LLM 이 다음 골격을 그대로 따르도록 강제합니다:

  • 상단 §0 📊 한눈에 보기 — 메트릭 카드 (파일 수 · 엔드포인트 · 모델 · 코드 발췌 · 🟡/🔴 정책 · 최근 변경)
  • ## 1. 구성 앱/파일 — 영역·파일·한 줄 책임 표
  • ## 2. 데이터 모델 — Mermaid erDiagram 우선 + 핵심 필드 제약 표 (영역 3+ 시 ### 2.1, ### 2.2)
  • ## 3. 엔드포인트 — Method | Path | View | 권한 | 핵심 로직 | 비고 6컬럼 표 + 권한 배지
  • ## 4. 대표 플로우 — 플로우당 mermaid sequenceDiagram 1개 + 번호 단계 (영역 3+ 시 ### 4.1, ### 4.2)
  • ## 5. 권한·데코레이터 패턴 — 가드·미들웨어·커스텀 데코레이터 정리
  • ## 6. 클라이언트 상태 — store / context / hook / route guard
  • ## 7. 정책 — 🟢 확정 / 🟡 확인 필요 / 🔴 TBD + 위험도 (🔥 / 🟧 / 🟩) 통합 표 (모든 🟡/🔴 행은 WHY 사유 한 줄 의무)
  • ## 8. 변경 이력 — @History 타임라인 (변경 분류 배지 🆕/🔄/🗑/🔐/💳/📜/🐛)
  • ## 9. 관련 파일 인덱스 — 라인번호 포함 풀리스트

평면 산문 H2 는 금지하고 표·다이어그램·번호 단계로 재구조화하도록 명시.

시각 어휘 (consistent badges)

같은 신호는 같은 배지로 통일합니다. 새 이모지를 즉흥으로 만들지 않습니다.

의미배지
정책 분류🟢 확정 · 🟡 확인 필요 · 🔴 TBD
위험도🔥 높음 · 🟧 보통 · 🟩 낮음
권한 (엔드포인트 표)🔓 public · 🔒 auth · 🛡️ admin · 💳 paid · 🤖 internal
변경 분류 (@History)🆕 신규 · 🔄 변경 · 🗑 제거 · 🔐 보안 · 💳 결제 · 📜 정책 · 🐛 버그

D1–D6 깊이 doctrine

표·다이어그램 골격을 넘어 사람이 코드를 안 열어보고도 1차 검토 가 가능하도록 강제하는 6개 규칙:

규칙내용
D1핵심 코드 인라인 발췌 (5–15줄) — §2/§3/§5 의 정책 결정 코드는 코드 펜스 + ⭐ 한 줄 해설
D2하위 섹션 깊이 — 영역 3개 이상이면 ### 2.1, ### 4.1 … 분리 (한 H2 에 다 욱여넣지 말 것)
D3기본값 / Magic 값 forensics — 비밀번호 default, CORS_ALLOW_ALL_ORIGINS=True, 긴 토큰 TTL, localhost 하드코딩, 미구현 enum, csrf_exempt 우회, 명명 mismatch, webhook 서명 누락 등 9개 패턴은 §7 에 자동 행 + 위험도
D4TBD 사유 명시 — 🔴 행은 “왜 코드만으로 결정 못 하는지” 한 줄
D5외부 docs cross-link — 사이드카 docs/, *_OPTIMIZATION.md 등은 §1 / §4 끝에 링크
D6레이어 다이어그램 — api_infra · client_state 같은 cross-cutting 카테고리는 수직 레이어 다이어그램 1개

§7 의 모든 🟡 / 🔴 행은 WHY 사유 한 줄 의무 (업계 비교 · 실패 영향 · 의존성). 사실만 적힌 행은 잘못된 보고서.

synthesize 한 번으로 D1–D6 가 일관되게 채워지지 않을 수 있습니다. 그럴 때는 2차 패스 로 lore review 를 돌려 누락된 깊이를 보강하세요.

Connection 추론

@Connection 어노테이션이 없어도 LLM 이 코드 단서로 다음 연결을 추론해 §4 또는 §9 에 명시합니다:

  • 엔드포인트 ↔ 화면/페이지/스토어 액션 매핑
  • 모델 ↔ 다른 모델의 FK / 참조 관계
  • 서버 background task ↔ 트리거 모델·이벤트
  • React 컴포넌트 ↔ 사용 hook ↔ API 클라이언트 함수

YAML frontmatter 보존

LLM 출력은 반드시 frontmatter (--- 블록) 를 포함해야 합니다. Claude Code 처럼 파일을 직접 쓰는 에이전트 환경에서는 기존 파일 상단의 frontmatter 를 verbatim 보존하고 닫는 --- 아래 본문만 새로 작성합니다. 신규 파일이거나 frontmatter 가 없으면 slug · title · icon · order · summary · tags · last_reviewed 를 직접 채웁니다. → reference/frontmatter

--since git log 번들링

--since <range> 를 주면 카테고리 어노테이션이 위치한 디렉토리의 git log 가 프롬프트에 함께 들어갑니다. 파일별로 git 루트를 자동 탐지하므로 모노레포 / 서브레포 / 멀티레포 어느 구조든 동작합니다.

<range> 는 git log --since 가 받는 모든 형식: 2.weeks, 1.month, 2025-03-01, yesterday 등.

lore synthesize --since 2.weeks    # 최근 2주
lore synthesize --since 1.month    # 한 달
lore synthesize --since 2026-01-01 # 절대 날짜

동작

단일 카테고리 모드

  1. domains[<category>] 검증
  2. 모든 프로젝트에서 해당 카테고리 어노테이션 추출
  3. synth 캐시와 비교 → 변경 없으면 스킵
  4. 기존 .lore/flows/<category>.md 본문 (있으면) 로드
  5. (--since 시) 해당 카테고리 파일들의 git log 수집
  6. L1 + 기존 L2 + L3 + git log + L2 doctrine → 9섹션 출력 contract 가 박힌 프롬프트 생성

전체 모드 (인자 없음)

  1. domains: 의 모든 카테고리 순회
  2. 각 카테고리의 어노테이션 + 캐시 비교 (변경 0 인 카테고리는 skip)
  3. 어노테이션 0 인 카테고리도 skip
  4. (--since 시) 모든 카테고리의 파일에 대한 git log 한 번에 수집
  5. 카테고리별 컨텍스트를 하나의 프롬프트로 묶고 === FILE: .lore/flows/<slug>.md === 마커로 LLM 이 응답을 분리하도록 지시

권장 워크플로 (v0)

--apply 가 v0.2 까지 미구현이므로:

lore sync                                  # L3 draft 갱신
lore synthesize --since 2.weeks | pbcopy   # 변경된 카테고리만 + git log
# Claude Code 에 붙여넣기 →
#   Claude Code 가 .lore/flows/<cat>.md 를 9섹션 구조로 갱신
lore review <cat>                          # 깊이 보강 (선택)
lore synclore review