CLAUDE.md 실전 템플릿

CLAUDE.md는 저장소 루트에 두면 세션마다 자동으로 로드되는 프로젝트 지침 파일입니다. 이 글은 작성 원칙을 이미 안다고 보고, 바로 복사해서 쓸 수 있는 템플릿만 다룹니다.

어떤 구조로 쓰는가

프로젝트 종류와 무관하게 다음 네 블록이면 충분합니다. 순서도 이대로 두세요.

1. 한 줄 개요 — 이 저장소가 무엇인지
2. 명령 — 빌드·테스트·린트·개발 서버
3. 규칙 — 코드만 봐서는 알 수 없는 관례
4. 금지 — 건드리면 안 되는 것

여기 없는 내용은 대부분 빼도 됩니다. 이 파일은 매 세션 고정 비용이라 200줄을 넘기지 않는 것이 공식 문서의 권고입니다.

기본 템플릿

어느 프로젝트에나 맞는 최소 형태입니다.

# <프로젝트 이름>

<한 줄 설명>

## 명령
- 개발 서버: `npm run dev`
- 테스트: `npm test`
- 타입 체크: `npm run typecheck`
- 린트: `npm run lint`

## 규칙
- 코드를 수정한 뒤에는 반드시 `npm run typecheck`를 실행한다.
- 새 API 라우트에는 통합 테스트를 함께 추가한다.
- 목록 조회는 항상 페이지네이션을 사용한다.

## 금지
- `src/generated/` 아래 파일 직접 수정 금지 (코드 생성 결과물)
- 새 상태 관리 라이브러리 도입 금지
- 커밋·푸시는 사용자가 요청할 때만 수행한다

웹 프론트엔드 템플릿

# <서비스명> 웹

Next.js + TypeScript 기반 사용자 대면 웹앱.

## 명령
- 개발: `pnpm dev`
- 빌드 검증: `pnpm build`
- 테스트: `pnpm test`
- E2E: `pnpm test:e2e`

## 규칙
- 스타일은 Tailwind 유틸리티만 사용한다. 새 CSS 파일을 만들지 않는다.
- 서버 컴포넌트를 기본으로 하고, 클라이언트 컴포넌트는 상호작용이 필요한 경우에만 만든다.
- 새 컴포넌트는 `components/` 아래 기존 파일의 구조와 명명 규칙을 따른다.
- 텍스트는 하드코딩하지 않고 `locales/ko.json`에 넣는다.

## 금지
- `app/api/` 응답 스키마를 임의로 바꾸지 않는다. 모바일 앱이 함께 쓴다.
- 이미지 도메인 추가 시 `next.config.js` 수정 전 확인을 받는다.

백엔드·API 템플릿

# <서비스명> API

Python + FastAPI. PostgreSQL 사용.

## 명령
- 개발 서버: `uv run uvicorn app.main:app --reload`
- 테스트: `uv run pytest`
- 마이그레이션 생성: `uv run alembic revision --autogenerate -m "<메시지>"`
- 마이그레이션 적용: `uv run alembic upgrade head`

## 규칙
- 스키마를 바꾸면 반드시 Alembic 마이그레이션을 함께 만든다.
- 모든 엔드포인트는 Pydantic 응답 모델을 명시한다.
- 외부 호출은 `app/clients/` 아래에만 둔다. 라우터에서 직접 호출하지 않는다.
- 수정 후 `uv run pytest -q`가 통과하는 것까지 확인한다.

## 금지
- 운영 DB에 접속하는 명령 실행 금지
- `alembic upgrade`를 사용자 승인 없이 실행하지 않는다
- 시크릿 값을 코드나 테스트 픽스처에 넣지 않는다

비개발 프로젝트 템플릿

문서·리서치·콘텐츠 저장소에도 같은 방식이 통합니다.

# <프로젝트명> 콘텐츠 저장소

블로그 원고와 리서치 노트를 관리하는 저장소.

## 구조
- 발행 원고: `posts/`
- 리서치 원본: `research/` (읽기 전용, 수정 금지)

## 규칙
- 원고는 Markdown으로 쓰고 프론트매터에 title, date, tags를 넣는다.
- 수치나 인용을 쓸 때는 반드시 출처 URL을 함께 적는다.
- 확인하지 못한 수치는 쓰지 않는다.

## 금지
- `research/` 아래 파일 수정 금지
- 원고 문체를 임의로 바꾸지 않는다. 기존 글의 톤을 따른다.

붙여넣은 뒤 반드시 손볼 것

템플릿을 그대로 두면 효과가 절반입니다. 다음 순서로 다듬으세요.

1. 명령을 실제로 한 번씩 실행해 본다. 동작하지 않는 명령이 적혀 있으면 그 지침 전체의 신뢰가 떨어집니다.
2. "우리 팀만 아는 것"을 세 줄 이상 추가한다. 자동 생성으로는 나오지 않는 부분이 여기입니다.
3. 검증 불가능한 문장을 지운다. "품질을 신경 쓰세요" 같은 문장은 장식입니다.
4. 폴더 한정 규칙은 그 폴더로 내린다. apps/web/CLAUDE.md처럼 좁은 범위가 우선합니다.
5. 긴 워크플로 지침은 Skills로 옮긴다. Skills는 호출될 때만 로드되므로 기본 컨텍스트가 가벼워집니다.

계층별로 무엇을 두나