How to Create the Perfect CLAUDE.md (incl. Template)

# ~/.claude/CLAUDE.md (Global)
- Always use TypeScript
- Write tests with Jest

# ~/project/CLAUDE.md (Project)
- Write tests with Vitest  # Overrides Jest

# Result for Claude:
- Always use TypeScript (from global)
- Write tests with Vitest (from project)

# Terminal
mkdir -p ~/.claude
touch ~/.claude/CLAUDE.md

# Global Developer Preferences

## General Rules
- Prefer TypeScript over JavaScript
- Write code in English, comments in German
- Use modern ES6+ syntax
- No console.log() in production code

## Code Quality
- Write clean, readable code
- Use meaningful variable names
- Keep functions small (max 20 lines)
- Follow DRY principle

## Error Handling
- Always try-catch with async/await
- Never swallow errors
- Meaningful error messages

## Git
- Commit messages in English
- Use Conventional Commits format
- Never push directly to main

Create a CLAUDE.md for this project. Analyze the project comprehensively so you don't forget anything. Use the following template:"

# [Project Name]

[One-sentence description of the project]

## Tech Layers
- **Framework**: [e.g., Next.js, React, Vue]
- **Language**: [e.g., TypeScript, Python]
- **Database**: [e.g., PostgreSQL, MongoDB]
- **Styling**: [e.g., Tailwind, CSS Modules]
- **Testing**: [e.g., Jest, Vitest, Pytest]

## Project Structure
```
src/
├── [important folder]/   # [Description]
├── [another folder]/     # [Description]
└── [config files]        # [Description]
```

## Development
```bash
[install command]        # Install dependencies
[dev command]           # Development server
[build command]         # Production build
[test command]          # Run tests
```

## Code Standards
- [Standard 1, e.g., "TypeScript strict mode"]
- [Standard 2, e.g., "Follow ESLint rules"]
- [Standard 3, e.g., "No any types"]
- [Standard 4, e.g., "Tests for new features"]

## Project-Specific Rules
- [Rule 1, e.g., "API calls only via services/"]
- [Rule 2, e.g., "Styling only with Tailwind"]
- [Rule 3, e.g., "Components must be typed"]

## Important Notes
- [Note 1, e.g., "Production secrets in .env.production"]
- [Note 2, e.g., "No direct DB queries"]
- [Note 3, e.g., "Mind rate limiting"]

## Common Mistakes to Avoid
- DON'T: [Common mistake]
- DON'T: [Another mistake]
- ALWAYS: [Best practice]
- ALWAYS: [Another best practice]

# AI Blog Project

Next.js 15 Blog with TypeScript, focused on AI and SEO topics.

## Tech Layers
- **Framework**: Next.js 15.3.3 with App Router
- **Language**: TypeScript 5.x (strict mode)
- **Styling**: Tailwind CSS v4 with PostCSS
- **UI**: Radix UI + shadcn/ui components
- **Database**: PostgreSQL with Prisma ORM

## Project Structure
```
src/
├── app/              # Next.js App Router
│   └── blog/         # Blog posts (IMPORTANT: No /blog/ URL!)
├── components/       # React Components
│   └── ui/          # shadcn/ui Components
├── lib/             # Utilities and Services
└── types/           # TypeScript Types
```

## Important Commands
```bash
npm run dev          # Development server
npm run build        # Production build
npm run lint         # Run ESLint
npm run typecheck    # TypeScript check
```

## Blog System Rules
- Blog posts in src/app/blog/[slug]/page.tsx
- URLs WITHOUT /blog/ prefix (Rewrite in next.config.ts)
- Always use BlogPostConfig for metadata
- CodeBlock component for all code examples
- Define FAQ items outside the component

## Code Standards
- Components in PascalCase
- Utilities in camelCase
- Tailwind instead of CSS modules
- No new components without checking ui/
- German content, English code

## Common Mistakes to Avoid
- DON'T: Create new README.md
- DON'T: Leave console.log in code
- DON'T: New UI components from scratch
- ALWAYS: Edit existing files
- ALWAYS: TypeScript strict mode

## Git Workflow
- Feature branches from main
- PR before merge
- Squash commits on merge

## Context Rules

### For Bug Fixes
- First understand, then fix
- Analyze root cause
- Write regression test
- Update changelog

### For New Features
- First define Types/Interfaces
- API-First Design
- Write tests in parallel
- Documentation comments

### For Refactoring
- Don't change functionality
- Tests must stay green
- Proceed step by step
- Measure performance

## Code Standards (Detailed)

### Naming Conventions
- Components: PascalCase (UserProfile, NavBar)
- Hooks: camelCase with 'use' prefix (useAuth, useFetch)
- Utils: camelCase (formatDate, parseJson)
- Constants: SCREAMING_SNAKE_CASE (API_URL, MAX_RETRY)
- Types/Interfaces: PascalCase with Suffix (UserType, ApiResponse)

### Async Code
```typescript
// ALWAYS like this:
try {
  const data = await fetchData()
  return processData(data)
} catch (error) {
  logger.error('Fetch failed:', error)
  throw new AppError('Data fetch failed', error)
}

// NEVER like this:
fetchData().then(data => processData(data))
```

### Imports
- Absolute imports for src/ ('@/components/Button')
- Grouped imports (React, Third-party, Local)
- Prefer named exports

## File Locations (IMPORTANT!)

### Where new files go:
- React Components → src/components/[name]/[Name].tsx
- API Routes → src/app/api/[route]/route.ts
- Utilities → src/lib/utils/[name].ts
- Types → src/types/[name].types.ts
- Hooks → src/hooks/use[Name].ts
- Tests → [same-folder]/[name].test.ts

### These folders NOT to touch:
- node_modules/ (obvious, but Claude does it anyway)
- .next/ (Build output)
- dist/ (Build output)
- coverage/ (Test output)

### When in doubt:
ALWAYS ask me before creating new files!

# Project Core (Max 100 Lines)

## Must-Know (Top Priority)
- [Only the most important things]
- [Max 10 points]

## Quick Reference
```
npm run dev
npm run build
npm run test
```

## Details see:
- Architecture: docs/ARCHITECTURE.md
- API: docs/API.md
- Testing: docs/TESTING.md

# Team Project

[... Project Config ...]

---
## Changelog
- 2025-01-25: TypeScript strict mode enabled (FH)
- 2025-01-20: Tailwind v4 Update (MK)
- 2025-01-15: Initial version (FH)

# CLAUDE.md → AGENTS.md (Universal) + Symlink
mv CLAUDE.md AGENTS.md
ln -s AGENTS.md CLAUDE.md