CLAUDE.md Guide

CLAUDE.md is a special file that provides project-specific context and instructions to Claude Code. When Claude starts in a directory, it reads this file to understand your project.

File Locations

Location	Scope	Purpose
./CLAUDE.md	Project	Project-specific instructions
~/.claude/CLAUDE.md	Global	Your personal preferences
./.claude/CLAUDE.md	Project (hidden)	Alternative project location

Basic Structure

# Project Name

Brief description of what this project does.

## Tech Stack

- Framework: Next.js 14
- Database: PostgreSQL
- ORM: Prisma
- Testing: Jest + React Testing Library

## Project Structure

src/ ├── app/ # Next.js app router pages ├── components/ # React components ├── lib/ # Utility functions └── services/ # Business logic

## Development Commands

- `npm run dev` - Start development server
- `npm run test` - Run tests
- `npm run build` - Production build

## Conventions

- Use TypeScript strict mode
- Components use PascalCase
- Utilities use camelCase
- Tests live next to source files (`*.test.ts`)

## Important Notes

- Never commit `.env` files
- Run migrations before starting: `npm run db:migrate`
- API keys are in 1Password under "Project X"

What to Include

Do Include

• Tech stack - Languages, frameworks, databases
• Project structure - Where things live
• Commands - How to build, test, deploy
• Conventions - Naming, formatting, patterns
• Gotchas - Non-obvious things that trip people up
• Environment setup - Required env vars, services

Don’t Include

• Sensitive data (API keys, passwords)
• Information that changes frequently
• Generic programming advice
• Entire codebases or large code blocks

Team Template

Use this template for new projects:

Download CLAUDE.md template

View template

# [Project Name]

[One-line description]

## Quick Start

1. Clone: `git clone [repo]`
2. Install: `npm install`
3. Configure: `cp .env.example .env.local`
4. Run: `npm run dev`

## Tech Stack

- [List main technologies]

## Project Structure

[Brief overview of directory structure]

## Commands

| Command | Description |
|---------|-------------|
| `npm run dev` | Start dev server |
| `npm run test` | Run tests |
| `npm run build` | Production build |

## Conventions

- [Coding standards]
- [Naming conventions]
- [Git workflow]

## Environment Variables

| Variable | Description | Where to find |
|----------|-------------|---------------|
| `DATABASE_URL` | DB connection | 1Password |
| `API_KEY` | External API | Admin dashboard |

## Troubleshooting

### [Common Issue 1]
Solution...

### [Common Issue 2]
Solution...

## Contacts

- Tech Lead: @username
- DevOps: @username

Tips

1. Keep it updated - Outdated instructions cause confusion

2. Be concise - Claude reads this every session; don’t make it huge

3. Use examples - Show don’t tell when explaining conventions

4. Version it - Commit CLAUDE.md to git so the team shares it

5. Layer it - Use global CLAUDE.md for personal prefs, project CLAUDE.md for project specifics

Example: This Documentation Site

Here’s the CLAUDE.md for this documentation site:

# ThePrintSpace Developer Docs

Internal documentation site built with Astro + Starlight.

## Commands

- `npm run dev` - Start dev server at localhost:4321
- `npm run build` - Build for production (outputs to dist/)
- `npm run preview` - Preview production build

## Adding Documentation

1. Create `.md` files in `src/content/docs/`
2. Add frontmatter with title and description
3. Guides and Reference sections auto-generate sidebar
4. Getting Started requires manual sidebar config in `astro.config.mjs`

## Structure

- `src/content/docs/` - All documentation content
- `public/` - Static assets (including llms.txt)
- `src/assets/` - Images and logo

## Deployment

Pushes to `main` trigger GitHub Actions → Cloudflare Pages