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