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가 해당 요청에 맞춰 처리합니다.

출처

• 시·도 지도 경계: MapSVG South Korea를 @svg-maps/south-korea가 가공한 것으로, CC BY 4.0 라이선스입니다.
• 축제·행사 정보: 한국관광공사 국문 관광정보 서비스(TourAPI), 공공데이터포털.