Claude Code Playbook Template

Claude Hunt 강의용 Next.js 16 + React 19 템플릿. 사용법과 워크플로우 문서는 docs.claude-hunt.com에서 확인하세요.

기술 스택

Next.js 16 (App Router) · React 19 · Tailwind CSS 4 · shadcn/ui · Bun · Vitest · Playwright

시작하기

bun install
bun dev

http://localhost:3000에서 결과를 확인할 수 있습니다.

스크립트

명령어	설명
bun dev	개발 서버 실행
bun run build	프로덕션 빌드
bun start	프로덕션 서버 실행
bun run lint	ESLint 실행
bun run typecheck	tsc --noEmit 타입 검사
bun run test	Vitest 단위/컴포넌트 테스트 1회 실행
bun run test:watch	Vitest watch 모드
bun run test:e2e	Playwright E2E 테스트 실행

테스트

• 단위·컴포넌트: Vitest + Testing Library. 설정은 vitest.config.mts, 매처와 cleanup은 vitest.setup.ts에 있습니다. 테스트 파일은 소스 옆에 *.test.ts(x)로 둡니다(app/page.test.tsx, lib/utils.test.ts 참고). globals를 켜지 않았으므로 describe/it/expect는 vitest에서 import 합니다.
• E2E: Playwright. 설정은 playwright.config.ts, 테스트는 e2e/*.spec.ts에 둡니다. webServer가 bun run dev를 자동으로 띄우므로 별도 서버 실행이 필요 없습니다.

E2E를 처음 실행하기 전에 브라우저를 한 번 내려받아야 합니다.

bunx playwright install chromium

브라우저가 이미 설치된 환경(예: Claude Code 원격 세션)에서는 내려받는 대신 실행 파일 경로를 지정할 수 있습니다.

PLAYWRIGHT_CHROMIUM_PATH=/opt/pw-browsers/chromium bun run test:e2e

async Server Component는 Vitest가 아직 지원하지 않으므로 E2E로 검증합니다.

• 런타임 검증(에이전트용): agent-browser. 에이전트가 next-dev-loop 스킬로 실행 중인 앱을 직접 조작해 변경을 확인할 때 씁니다. 프로젝트 의존성이 아니므로 한 번 전역으로 설치합니다.

npm i -g agent-browser
agent-browser install  # 설치된 Chrome이 없을 때만

Claude Code 워크플로우

flowchart LR
    DP["define-product"] --> PRODUCT[/"PRODUCT.md"/]
    PRODUCT --> SI["shape-idea"]
    SI --> SPEC[/"docs/specs/<slug>/spec.md"/]
    SPEC --> ST["split-into-tasks<br/>여러 결과로 나눌 때"]
    SPEC --> IMP["implement"]
    ST --> IMP
    IMP --> HR["human-review<br/>중대한 결과를 검토할 때"]
    IMP --> PR["pr"]
    HR --> PR
    FU[/"docs/follow-ups/*.md"/] --> RF["resolve-follow-ups"]
    RF --> PR

파이프라인 밖에서는 project-knowledge, maintain-project-context, add-stack-context, build-prototype, explain-visually, tdd가 각자의 조건에 따라 켜집니다. project-knowledge는 GLOSSARY.md, docs/decisions/, docs/follow-ups/에 다음 작업에서도 재사용할 지식과 후속 항목을 남깁니다. Git 작업은 commit, pull, push, pr, merge가 해당 요청에 맞춰 처리합니다.

카메라 라이브 보기 (ViewRTSP)

RTSP 영상은 go2rtc(MIT)가 WebRTC로 바꿔 브라우저에 전달합니다.

1. go2rtc 실행 파일을 tools/go2rtc/에 둡니다. (Windows: go2rtc_win64.zip의 go2rtc.exe)
2. 실제 카메라: bun run relay를 실행하고, 앱의 설정 메뉴에서 카메라 RTSP 주소를 저장합니다. 주소는 config/relay-state.yaml에 남아 다음 실행에도 유지됩니다.
3. 카메라 없이 확인: tools/arial.ttf를 두고 bun run relay:test를 실행하면 시각이 찍힌 테스트 영상이 나옵니다. 설정 메뉴의 "시험용 영상"에서 시계 영상과 색 막대 영상을 골라 주소 전환을 시험할 수 있습니다.
4. 다른 터미널에서 bun dev를 실행하고 http://localhost:3000 을 엽니다.

배포 환경의 시험용 영상

실제 카메라 없이도 화면과 저장 기능을 확인할 수 있도록, 미리 만든 영상(public/test-loop.mp4, 10초)을 반복해서 RTSP로 내보내는 시험용 영상을 제공합니다. 평소에는 꺼져 있고, 켠 relay에서만 설정 메뉴에 "반복 재생 영상"이 나타납니다.

• 켜기: bun run relay 대신 bun run relay:sample을 실행합니다. 카메라는 그대로 쓰고 시험용 영상만 덧붙습니다.
• 쓰기: 설정 메뉴의 "시험용 영상"에서 "반복 재생 영상"을 고르고 저장합니다.
• 필요한 것: PATH에 ffmpeg. 영상을 다시 인코딩하지 않아(-c copy) 라즈베리파이에서도 부담이 작습니다.
• 한계: 시계가 없어서 순간 저장의 정확도는 확인할 수 없습니다. 그 확인에는 bun run relay:test의 시계 영상을 씁니다.

데모 모드 (Vercel 미리보기)

중계 서버와 카메라가 없는 환경에서는 데모 모드가 켜져, public/test-loop.mp4를 브라우저에서 바로 반복 재생합니다. Vercel은 VERCEL=1을 자동으로 넣어 주므로 따로 설정할 것이 없고, 다른 곳에서 확인하려면 DEMO_MODE=1로 실행합니다. 화면에 "데모 화면입니다" 안내가 보이며, 이미지 캡처와 수동 녹화(내 기기 저장)만 쓸 수 있습니다.

환경 변수: GO2RTC_URL(기본 http://127.0.0.1:1984), SAVE_DIR(서버 저장 폴더, 기본 ./saved).