previs

코딩 에이전트의 작업 계획(plan)과 작업 회고(recap)를 사람이 검토하기 좋은 인터랙티브 비주얼 문서로 만들어주는 도구.

Version: 0.6.0 (M5 완료 — 로컬 런처: 재사용 우선 싱글턴 뷰어 서버. "개인 도구" 1차 완성)

무엇을 하나

• plan — 구현 착수 전 계획을 다이어그램·와이어프레임·파일 맵으로 시각화해 리뷰어 승인 게이트 역할을 한다.
• recap — 구현 완료 후 PR/브랜치/diff를 변경의 "형태"로 요약해 raw diff 이전의 리뷰 진입점을 제공한다.

문서는 기본적으로 로컬 .previs/ 폴더에 JSON 블록으로 발행되며(로컬 우선), 협업 모드(Supabase)에서 코멘트·공유·피드백 루프를 지원한다.

문서 맵

문서	내용
AGENTS.md	프로젝트 공통 지침 (CLAUDE.md는 심볼릭 링크)
docs/GOAL.md	전체 목표와 마일스톤 로드맵 (M0~M7)
docs/ARCHI.md	아키텍처 기준 문서
DESIGN.md	뷰어 UI 디자인 시스템 (블록 콘텐츠에는 미적용)

개발

pnpm workspace 모노레포 (Node ^22.13.0 || >=24, pnpm 10).

pnpm install
pnpm lint      # ESLint
pnpm typecheck # 패키지별 tsc --noEmit
pnpm test      # 빌드 후 Vitest 실행 (dist smoke 포함)
pnpm build     # 패키지별 tsc 빌드

핵심 패키지:

• packages/schema — 블록 JSON 스키마 (스킬·뷰어·저장 계층이 공유하는 계약)
• packages/recap — git diff에서 recap 블록을 기계 도출하는 CLI. pnpm recap:derive --out <manifest>로 실행 (/previs-recap 스킬이 사용)
• packages/launcher — 재사용 우선 싱글턴 뷰어 런처. pnpm viewer:up으로 실행 (이미 떠 있으면 URL 재사용, 없으면 백그라운드 기동, 다중 세션 동시 호출에도 프로세스 1개 보장)
• apps/viewer — 로컬 JSON 문서 뷰어. 보통 pnpm viewer:up 으로 기동하며(previs 전용 포트 대역 47738~47801), 직접 실행은 pnpm --filter @previs/viewer dev

개발 워크플로우

TRIP(Plan → Implement → Review → Test) 워크플로우로 진행하며, 계획·리뷰·테스트 문서는 docs/ 하위에 축적된다. 자세한 규칙은 AGENTS.md를 본다.