프로젝트 유형별 CLAUDE.md 템플릿 5종 — 복붙용 파일과 에이전트가 실제로 따르는 규칙

# Project: <name> — Next.js 15 App Router

## Commands
- Dev: `npm run dev` · Build: `npm run build` (PR 전 반드시 통과) · Lint: `npm run lint`
- Tests: `npm test` (Vitest). 파일 하나만: `npx vitest run src/lib/foo.test.ts`
- Type check: `npx tsc --noEmit` — `src/types/`를 건드렸으면 반드시 실행

## Architecture
- `src/app/(marketing)/` 공개 페이지 · `src/app/(app)/` 인증 라우트 · `src/app/api/` 라우트 핸들러
- `src/lib/` 순수 함수와 서버 전용 데이터 접근 (파일 상단에 `import 'server-only'`)
- `src/ui/` 표현 컴포넌트. `src/ui/`에서 데이터 페칭 금지.
- DB: Prisma는 `src/lib/prisma.ts`를 통해서만. 다른 곳에서 `new PrismaClient()` 금지.

## Rules
- 기본은 Server Component. `'use client'`는 훅/이벤트 핸들러가 필요할 때만, 그 파일은 작게.
- 페칭은 `page.tsx`/`layout.tsx` 또는 `src/lib/`에서 하고 아래로 내려보낸다. `useEffect` 페칭 금지.
- 환경변수는 `src/lib/env.ts`(zod 검증)에서만 읽는다. 인라인 `process.env.X` 금지. 시크릿에 `NEXT_PUBLIC_` 접두사 금지.
- Tailwind만. CSS 모듈 금지, 인라인 `style=`은 동적 값에만.
- 라우트 핸들러는 `NextResponse.json`을 반환하고, DB를 만지기 전에 zod로 body를 검증한다.
- 라우트를 바꿨으면 `curl`로 한 번 쳐보고 상태 줄을 요약에 붙인다.

## Don't
- PR 설명에 이유를 적지 않고 의존성을 추가하지 않는다.
- `prisma/schema.prisma`를 수정했으면 `npx prisma generate`를 돌리고 마이그레이션을 언급한다.

# Project: <name> — PyTorch 학습 + 평가

## Environment
- Python env: `conda activate <env>` (base env 금지). 의존성은 `pyproject.toml`; 추가는 pip가 아니라 `uv add`.
- GPU: 먼저 `nvidia-smi`. `CUDA_VISIBLE_DEVICES=<빈 id>`를 쓰고, 10GB 이상 쓰이는 GPU에는 절대 띄우지 않는다.
- 데이터는 `/data/<project>/` (읽기 전용). 출력은 `runs/<date>-<name>/`. `data/`에 쓰지 않는다.

## Commands
- 스모크 테스트 (30초): `python train.py --config configs/smoke.yaml`
- 본 실행: `python train.py --config configs/base.yaml --run-name <name>` (`runs/`에 로그)
- 평가: `python eval.py --ckpt runs/<run>/best.pt --split val`
- 테스트: `pytest tests/ -x -q` — 설정 변경을 커밋하기 전 반드시 통과

## Rules
- 설정 변경은 `configs/` 아래 새 YAML로. `base.yaml`을 제자리에서 고치지 않는다. 가설 이름으로 파일명을 짓는다.
- 모든 실행은 `runs/<run>/config.yaml`(고정 사본)과 `metrics.json`을 남긴다. 안 남기는 스크립트는 먼저 고친다.
- 숫자는 그 숫자를 만든 run 디렉터리와 함께 보고한다. **run 경로 없는 숫자는 결과가 아니다.**
- 보고하는 실행에는 `--seed`가 필수. 1% 이상 개선을 주장하려면 시드 3개.
- 노트북(`notebooks/`)은 스크래치다. 살아남아야 할 것은 테스트와 함께 `src/`로 옮긴다.
- `eval.py`의 메트릭 로직을 바꾸지 않는다. 메트릭이 틀렸으면 이슈를 열고, 실험 중간에 인라인으로 고치지 않는다.

## When training fails
- OOM → `batch_size` 절반, `grad_accum` 두 배, run 이름에 기록. 해상도/시퀀스 길이를 몰래 낮추지 않는다.
- NaN loss → 멈추고 원인 배치를 저장(`--dump-nan-batch`)한 뒤 보고. `nan_to_num`을 끼워 넣지 않는다.

# Monorepo: <name> — pnpm + Turborepo

## Layout
- `apps/web` (Next.js) · `apps/api` (Fastify) · `apps/worker` (BullMQ)
- `packages/ui` (공유 React) · `packages/db` (Prisma + client) · `packages/config` (eslint/tsconfig)
- 패키지마다 자체 `AGENTS.md`가 있다. **가장 가까운 파일이 이긴다.** 수정 전에 읽는다.

## Commands (리포 루트에서)
- 설치: `pnpm i` · 전체 빌드: `pnpm turbo build` · 패키지 하나 테스트: `pnpm --filter @acme/api test`
- 변경분 린트: `pnpm turbo lint --filter=...[origin/main]`
- `packages/`를 건드린 게 아니면 필터 없이 `pnpm turbo test`를 돌리지 않는다.

## Rules
- `packages/*` 변경은 모든 앱의 변경이다. PR 제목에 명시하고(`[packages/db] ...`) 의존하는 앱 전부의 테스트를 돌린다.
- 앱 간 import 금지 (`apps/web` → `apps/api`). 공유 코드는 `packages/`로.
- 버전 올리기: `pnpm changeset` — `package.json` 버전을 손으로 고치지 않는다.
- 생성 코드(`packages/db/generated/`, codegen `*.d.ts`)는 절대 편집하지 않는다. 생성기를 다시 돌린다.

## Ownership
- `packages/db` 스키마 변경에는 마이그레이션 파일 **그리고** `packages/db/CHANGELOG.md` 한 줄이 필요하다.
- `apps/worker` 잡은 멱등이어야 한다. 재시도 계약은 `apps/worker/AGENTS.md`.

# packages/db
- 스키마: `prisma/schema.prisma`. 변경 후: `pnpm prisma generate && pnpm prisma migrate dev --name <what-changed>`.
- 로컬 DB가 아닌 곳에 `prisma db push` 금지.
- 새 테이블에는 마이그레이션, 앱 부팅에 필요한 행이 있으면 `seed.ts` 항목, CHANGELOG.md 한 줄이 필요하다.

# Project: <name> — Airflow DAG + BigQuery 위 dbt 모델

## Commands
- 로컬 Airflow: `make airflow-up` (docker) · DAG 파싱 확인: `python dags/<dag>.py`
- dbt: `dbt build --select <model>+ --target dev` (노트북에서 `--target prod` 금지)
- 쿼리 드라이런: `bq query --dry_run --use_legacy_sql=false < query.sql` — 스캔 바이트를 요약에 붙인다
- 테스트: `dbt test --select <model>` 와 `pytest tests/`

## Rules
- 새 모델에는 `schema.yml`의 `description`과, 키에 대한 `unique` + `not_null` 테스트가 최소한 있어야 한다.
- 증분 모델은 `unique_key`를 정의하고 같은 파티션을 다시 돌려도 안전(멱등)해야 한다.
- 백필: DAG에 명시적 `--backfill-approved` 플래그 없이 한 번에 7일 초과 금지. 실행 전에 무엇이 덮어써지는지 말한다.
- 다른 모델이 읽는 모델에 `SELECT *` 금지. 컬럼을 나열한다.
- 비용: 100GB 이상 스캔하는 쿼리는 파티션 필터가 있거나, 왜 없는지 주석이 있어야 한다.
- 타임존: 웨어하우스는 전부 UTC. 변환은 표현 레이어에서만.

## Don't
- 데이터셋 이름을 하드코딩하지 않는다. `{{ source() }}` / `{{ ref() }}`.
- 데이터를 "고치려고" 행을 지우지 않는다. 보정 모델을 쓰고 이유를 문서화한다.

# Project: <name> — 실험 + 글쓰기

## Layout
- `notebooks/<topic>-<n>.ipynb` 탐색용 · `src/` 테스트 있는 재사용 코드 · `results/<topic>/*.json` 원시 출력 · `figures/` 는 `scripts/plot_*.py`만 생성
- `drafts/` 글. 글은 `results/` 파일을 인용하지, 손으로 친 숫자를 쓰지 않는다.

## Commands
- Env: `conda activate research` · 실행 전 GPU 확인: `nvidia-smi`
- 실험 실행: `python src/run.py --exp <name> --out results/<topic>/<name>.json`
- 그림 전체 재생성: `python scripts/plot_all.py` (멱등; PNG를 커밋)

## Rules
- 모든 실험 스크립트는 설정, 시드, git 커밋 해시, 소요 시간, 원시 메트릭을 저장한다. 예외 없음.
- 글의 주장("X가 4.6배 빠르다")은 그것을 뒷받침하는 JSON에 링크되어야 한다. JSON이 없으면 그 문장은 나가지 않는다.
- 베이스라인은 처리군과 같은 세션, 같은 하드웨어에서 돌린다. 논문의 숫자와 비교할 때는 반드시 그렇다고 밝힌다.
- 결과가 논문과 다르면 그대로 보고하고 설정 차이를 나열한다. 맞을 때까지 튜닝하지 않는다.
- 노트북은 커밋 전 출력을 지운다(`nbstripout`). `notebooks/final/`만 예외.

## Writing
- 소제목과 굵은 주장이 본문 숫자보다 앞서 나가면 안 된다. 발행 전 굵은 글씨를 감사한다.
- 실험이 보여주지 *않는* 것을 별도 절로 적는다.

## Side effects
- 보내거나, 결제하거나, 외부에 쓰거나, 지우는 것은 전부 `src/lib/<effect>.ts`를 거친다. 다른 곳에서 클라이언트를 만들지 않는다.
- 행동하지 *않기로* 한 모든 분기는 이유를 로그에 남긴다. 조용한 skip 금지.
- 작업 완료를 말하기 전에 `npm run verify`가 exit 0이어야 한다. 마지막 줄을 붙인다.