ritus

책상 앞 몰입, 명상, 운동처럼 정해 둔 시간 동안 한 가지에 머물고 싶을 때 쓰는 웹 타이머입니다. 지금 하기로 한 것을 화면으로 붙잡고, 구간 전환과 세션 종료는 소리로 알립니다. 자세한 제품 정의는 PRODUCT.md에 있습니다.

이 저장소는 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에서 결과를 확인할 수 있습니다.

사용 방법

1. 지금 집중할 일을 제목으로 적습니다. 비워 둬도 됩니다.
2. 원을 끌거나 숫자를 입력해 시간을 정합니다(1～60분). 두 구간을 번갈아 반복하려면 반복을 켭니다.
3. 재생 아이콘을 누르면 세션이 시작됩니다. 시작·구간 전환·종료는 소리로 알립니다.

타이머 곁에 메모장, 할 일 목록, 양심노트가 있고, 쓴 글 전체를 파일 하나로 백업할 수 있습니다. 화면별 자세한 사용법은 docs/manual.md에 있습니다.

개발할 때 재사용할 결정은 결정 찾아보기, 미확인·보류 항목은 남은 일에서 확인합니다. 완료된 스펙은 필요한 결정을 옮긴 뒤 정리하며 이전 요구사항과 검증 이력은 Git에서 찾습니다.

스크립트

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

테스트

PR을 열거나 main에 변경이 들어오면 GitHub Actions가 bun install --frozen-lockfile 후 lint, 타입 검사, 단위·컴포넌트 테스트를 실행합니다. Bun 버전은 package.json의 packageManager와 같이 1.3.6으로 고정합니다. 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로 검증합니다.

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