Awesome CLAUDE.md — Project Config Best Practices

Project Overview

This is a Next.js 14 app with TypeScript, Tailwind CSS, and Prisma ORM.

Commands

• npm run dev — Start dev server
• npm run test — Run tests
• npm run lint — Run ESLint + Prettier

Code Style

• Functional components only, no class components
• Use Server Components by default
• State: Zustand for client, React Query for server
• Naming: PascalCase components, camelCase functions, kebab-case files

Architecture

• src/app/ — Next.js App Router pages
• src/components/ — Shared UI components
• src/lib/ — Utilities and helpers
• src/server/ — Server-side logic and API

Do NOT

• Do not use Redux or Context API for state
• Do not create CSS modules — use Tailwind only
• Do not add comments explaining obvious code

---

## Template Library

### Next.js + TypeScript
```markdown
# CLAUDE.md

## DB: Prisma with PostgreSQL, always use transactions for writes

Python FastAPI

# CLAUDE.md

## DB: SQLAlchemy async with PostgreSQL, Alembic for migrations

Go Microservice

# CLAUDE.md

## Testing: table-driven tests, testcontainers for integration

Monorepo

# CLAUDE.md

## Conventions: shared types in packages/types, all packages use TypeScript strict

Team Configuration

# CLAUDE.md

## Team Conventions

- PR titles: type(scope): description (conventional commits)
- Branch naming: feat/JIRA-123-description
- Tests required for all new functions
- No direct pushes to main — always PR

## Review Checklist

- [ ] Tests pass
- [ ] No console.log in production code
- [ ] Error handling for all API calls
- [ ] Accessibility: all interactive elements have labels

Best Practices

Keep It Focused

• Only include conventions Claude Code might get wrong
• Skip obvious things (Claude already knows language syntax)
• Update when you notice Claude making mistakes

Structure Matters

• Start with project overview (1-2 lines)
• Commands section for common tasks
• Code style for conventions
• Architecture for file structure
• "Do NOT" section for anti-patterns

Key Stats

• 3,000+ GitHub stars
• 20+ ready-to-use templates
• Covers 10+ tech stacks
• Community-contributed best practices
• Updated monthly

FAQ

Q: What is CLAUDE.md? A: A markdown file in your project root that configures Claude Code with project-specific conventions, commands, architecture, and coding standards.

Q: Where does CLAUDE.md go? A: In the root of your project directory. Claude Code automatically reads it at the start of every conversation.

Q: Can I have multiple CLAUDE.md files? A: Yes, you can place them in subdirectories for package-specific instructions in monorepos.