CLAUDE.md 템플릿 모음

 

CLAUDE.md 템플릿 모음

백엔드 / 프론트엔드 실전용

Claude Code를 써보면 금방 느끼게 됩니다.

CLAUDE.md 하나로 결과 품질이 완전히 달라진다.

이 파일은 단순한 설명 문서가 아니라,
👉 **Claude Code에게 적용되는 ‘최상위 시스템 규칙’**입니다.

• 프롬프트보다 우선
• 작업 범위 제어 가능
• 사고(대규모 수정, 실수 커밋) 예방 효과 큼

아래는 실제로 바로 써먹기 좋은 템플릿입니다.

---

1️⃣ 백엔드용 CLAUDE.md 템플릿

API / 서버 / 인증 / DB 중심 프로젝트에 적합

# Project Overview
This is a backend service project.
The primary goal is stability, security, and maintainability.

## Tech Stack
- Language: TypeScript
- Runtime: Node.js 20+
- Framework: NestJS
- Database: PostgreSQL
- ORM: Prisma
- Authentication: JWT
- Testing: Jest
- Package Manager: pnpm

## Project Structure
- src/modules: Feature-based modules
- src/common: Shared utilities, guards, filters
- src/config: Environment and configuration
- prisma: Database schema and migrations
- test: Integration and e2e tests

## Key Commands
- pnpm dev: Start development server
- pnpm build: Build for production
- pnpm test: Run tests
- pnpm lint: Run lint checks
- pnpm prisma:migrate: Run DB migrations

## Code Style Rules
- Use async/await (no raw Promise chains)
- Prefer explicit types (avoid `any`)
- Controllers must be thin (no business logic)
- Business logic belongs in services
- Always handle errors explicitly
- Use DTOs for request/response validation

## Testing Rules
- All new features must include tests
- Prefer integration tests over unit tests
- Cover edge cases and error scenarios
- Tests must be deterministic

## Security Rules
- Never log secrets or tokens
- Never expose internal error messages to clients
- Validate all external inputs
- Follow least-privilege principle

## Git Rules
- Do not commit directly to the main branch
- Create feature branches for all changes
- Use conventional commit messages

## Do Not
- Do NOT modify files in `src/legacy`
- Do NOT skip tests
- Do NOT change database schema without migration
- Do NOT introduce breaking API changes without notice

📌 백엔드용 포인트

• Do Not 섹션이 사고 방지에 매우 중요
• 인증/보안 관련 규칙은 반드시 명시

---

2️⃣ 프론트엔드용 CLAUDE.md 템플릿

React / Next.js / UI 중심 프로젝트에 적합

# Project Overview
This is a frontend web application.
The focus is on user experience, readability, and maintainable UI architecture.

## Tech Stack
- Framework: Next.js 14 (App Router)
- Language: TypeScript
- Styling: Tailwind CSS
- State Management: React Context / Zustand
- Data Fetching: React Query
- Testing: Jest + React Testing Library

## Project Structure
- src/app: Next.js App Router pages
- src/components: Reusable UI components
- src/features: Feature-based UI logic
- src/hooks: Custom React hooks
- src/lib: Utilities and API clients
- src/styles: Global styles

## Code Style Rules
- Use functional components only
- Prefer composition over inheritance
- Keep components small and focused
- Avoid deeply nested JSX
- Use semantic HTML elements
- Props must be typed explicitly

## State Management Rules
- Avoid unnecessary global state
- UI-only state stays local
- Server state handled via React Query
- No direct API calls inside components

## Styling Rules
- Use Tailwind utility classes
- Avoid inline styles
- Use consistent spacing and color tokens
- No duplicated styles across components

## Testing Rules
- Test user behavior, not implementation details
- Prefer screen queries over container queries
- Mock API calls explicitly
- Snapshot tests only when necessary

## Performance Rules
- Avoid unnecessary re-renders
- Use memoization when appropriate
- Lazy-load heavy components
- Optimize images and assets

## Do Not
- Do NOT use `any`
- Do NOT mutate props or state directly
- Do NOT add global CSS without discussion
- Do NOT introduce breaking UI changes silently

📌 프론트엔드용 포인트

• 상태 관리 규칙을 명확히 쓰는 게 중요
• UI 쪽은 “하지 말 것”을 구체적으로 써야 함

---

3️⃣ 공통 규칙 (전역 CLAUDE.md 추천)

모든 프로젝트에 공통으로 적용하고 싶다면

# Global Claude Rules

- Always respond in Korean
- Prefer minimal, safe changes
- Ask for clarification if requirements are unclear
- Avoid large refactors unless explicitly requested
- Summarize changes before applying them
- Never modify unrelated files

📍 위치:

~/.claude/CLAUDE.md

---

4️⃣ 디렉토리별 CLAUDE.md 활용 예시

project-root/
├─ CLAUDE.md                # 전체 프로젝트 규칙
├─ src/
│  ├─ api/
│  │  └─ CLAUDE.md          # API 관련 규칙
│  ├─ components/
│  │  └─ CLAUDE.md          # UI 컴포넌트 규칙

👉 이렇게 하면 폴더별로 다른 성격의 규칙 적용 가능

---

5️⃣ 잘 쓰는 팁 (중요)

• ❌ 너무 길게 쓰지 말 것 (100~200줄 권장)
• ❌ 설명서처럼 쓰지 말 것
• ⭕ “규칙” 중심으로 작성
• ⭕ 사고 날 수 있는 부분은 반드시 명시
• ⭕ 팀 컨벤션과 최대한 일치시키기

---

정리

CLAUDE.md는
Claude Code를 ‘툴’에서 ‘팀원’으로 바꿔주는 파일이다.

• 프롬프트보다 강력하고
• 반복 설명을 줄여주며
• 실수를 크게 줄여준다

Claude Code를 제대로 쓰고 싶다면,
👉 CLAUDE.md부터 정리하는 게 가장 먼저다.

---