Project Setup & CLAUDE.md

CLAUDE.md is a special file that Claude Code reads automatically at the start of every session. It's your project's instruction manual for AI — telling Claude:

• What the project is and how it's structured
• What conventions to follow
• What patterns to use (and avoid)
• How to run, test, and deploy the project

Without CLAUDE.md: Claude guesses based on what it reads. It might use the wrong patterns, wrong naming conventions, or wrong dependency versions.

With CLAUDE.md: Claude starts every conversation with your specific context already loaded. It's like briefing a new team member on day one.

# My Project

## Architecture
- Next.js 14 app router
- PostgreSQL via Prisma
- Tailwind CSS for styling

## Commands
- `npm run dev` — start development server
- `npm test` — run test suite
- `npm run lint` — check code style

## Conventions
- Use named exports (not default exports)
- Components in src/components/[feature]/
- API routes return { data, error } shape

Create the file in your project root:

cd ~/my-project
claude

Then ask Claude to help you write it:

> Analyse this project and create a CLAUDE.md file that describes 
> the architecture, conventions, and common commands. Base it on 
> what you can see in the codebase.

Claude will scan your project and generate a draft. Review it and refine:

> Good start, but:
> - We use vitest not jest
> - Add that we never use default exports
> - Add the database migration command: npx prisma migrate dev

Alternatively, write it yourself. Use this template:

# [Project Name]

## Overview
[One paragraph about what this project does]

## Tech Stack
- [Framework and version]
- [Database]
- [Styling approach]
- [Testing framework]

## Commands
- `[command]` — [what it does]

## Project Structure
- src/app/ — page routes
- src/components/ — shared UI components
- src/lib/ — utility functions
- src/types/ — TypeScript type definitions

## Conventions
- [Convention 1]
- [Convention 2]
- [Convention 3]

## Do NOT
- [Anti-pattern to avoid]
- [Thing that breaks the build]

Include:

Exclude:

The "Do NOT" section is critical:

## Do NOT
- Use `any` type in TypeScript — always specify types
- Import from barrel files (index.ts) — import directly from source
- Use class components — functional components only
- Add console.log — use our logger (src/lib/logger.ts)
- Modify database schema without a migration

This prevents the same mistakes from recurring across sessions. Every time Claude does something wrong that you have to correct, add it to the "Do NOT" list.

Beyond CLAUDE.md, Claude Code uses a .claude/ directory for configuration:

.claude/
├── settings.json          # Project-level settings
├── settings.local.json    # Personal settings (gitignored)
└── commands/              # Custom slash commands

settings.json — shared team settings:

{
  "permissions": {
    "allow": [
      "Bash(npm test)",
      "Bash(npm run lint)",
      "Bash(npx prisma *)"
    ]
  }
}

This pre-approves specific commands so Claude doesn't ask permission every time.

settings.local.json — personal preferences (add to .gitignore):

{
  "permissions": {
    "allow": [
      "Bash(git *)"
    ]
  }
}

Custom commands in .claude/commands/:

<!-- .claude/commands/fix-lint.md -->
Run `npm run lint`, then fix all fixable issues automatically.
Show me what changed.

Then use with: /fix-lint in your Claude session.

CLAUDE.md and .claude/settings.json should be committed to your repository. This means:

• Every team member gets the same AI behaviour
• New joiners get context immediately
• AI behaviour evolves with the codebase (via PR reviews)
• Conventions are enforced automatically

Team workflow:

1. Initial setup: Senior developer writes first CLAUDE.md
2. Evolution: Team members add to "Do NOT" list when AI makes mistakes
3. Review: CLAUDE.md changes go through PR review like any code
4. Onboarding: New developer installs Claude, runs it — immediately productive

Hierarchy of CLAUDE.md files: Claude reads CLAUDE.md files at multiple levels:

• ~/CLAUDE.md — global (your personal preferences)
• ./CLAUDE.md — project root (team shared)
• ./src/CLAUDE.md — directory-specific (optional, for large monorepos)

All are combined, with more specific files taking precedence.

Without CLAUDE.md — asking for a new component:

> Create a UserProfile component

Result: default exports, wrong folder, CSS modules (you use Tailwind), no TypeScript types. You spend 5 minutes correcting.

With CLAUDE.md — same request:

> Create a UserProfile component

Result: named export, correct folder (src/components/user/), Tailwind styling, proper TypeScript types, matches existing component patterns. Ready to use.

The ROI: 5 minutes writing CLAUDE.md × saved 5 minutes per interaction × 20 interactions per day = 100 minutes saved daily.

That's not an exaggeration for active AI users. The cumulative effect of not needing to correct conventions, file locations, and patterns adds up massively.