Claude Code Projects

How to configure Claude Code for your project: CLAUDE.md, project memory, per-project settings, and best practices for teams.

What is CLAUDE.md?

CLAUDE.md is a Markdown file at the root of your repository that Claude Code reads automatically at the start of every session. It's persistent project context — Claude absorbs it before reading a single line of your code.

Think of it as a README for Claude rather than for humans: concise, machine-first documentation about how to navigate and modify your codebase correctly.

# My Project — CLAUDE.md

## Tech stack
Next.js 14 (App Router), TypeScript, Prisma (PostgreSQL), Tailwind CSS.

## Key paths
- `src/app/` — Next.js routes and layouts
- `src/app/api/` — API route handlers
- `src/lib/` — shared utilities
- `prisma/schema.prisma` — database schema (do not edit directly — use migrations)

## Commands
- `npm run dev` — start dev server
- `npm run typecheck` — TypeScript check (run after any file changes)
- `npm run test` — Jest unit tests
- `npm run lint` — ESLint

## Do NOT modify
- `src/generated/` — auto-generated from GraphQL schema
- `prisma/migrations/` — generated migration files

## Conventions
- All new API routes must validate input with Zod before touching the DB
- Use `src/lib/logger.ts` for all logging (not console.log)
- Database queries must go through Prisma, never raw SQL

## Important invariants
- `userId` in all user-facing queries comes from the authenticated session, never from request body

CLAUDE.md vs README.md

.claude/settings.json — Project Runtime Config

While CLAUDE.md is prose context, .claude/settings.json controls Claude Code's runtime behaviour for the project:

{
  "allowedTools": [
    "Read",
    "Glob",
    "Grep",
    "Bash(npm run typecheck)",
    "Bash(npm run test **)",
    "Bash(git log **)",
    "Bash(git diff **)",
    "Bash(git status)"
  ],
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "npm run typecheck 2>&1 | tail -5"
          }
        ]
      }
    ]
  }
}

Both files are committed to version control and apply to every team member using Claude Code in the repo.

Memory Layers in Claude Code

Monorepo Setup

Claude Code supports hierarchical CLAUDE.md files for monorepos:

my-monorepo/
├── CLAUDE.md               ← global conventions (applies everywhere)
├── packages/
│   ├── api/
│   │   └── CLAUDE.md       ← API-specific notes
│   ├── web/
│   │   └── CLAUDE.md       ← Frontend-specific notes
│   └── shared/
│       └── CLAUDE.md       ← Shared library notes

When Claude works in packages/api/, it reads both the root CLAUDE.md and packages/api/CLAUDE.md. Use the root for cross-cutting concerns (auth invariants, global naming rules) and package files for package-specific commands, paths, and gotchas.

Best Practices for Teams

• Commit CLAUDE.md and .claude/settings.json — these should be version-controlled so all team members benefit equally
• Keep CLAUDE.md concise — aim for under 200 lines. Claude's attention degrades on very long context. Put the most important invariants first
• Use imperative language — "Always validate with Zod" beats "We generally try to validate with Zod where possible"
• List what NOT to edit — auto-generated files, migration files, vendored code. Claude can't always tell from file names alone
• Include test commands — Claude will run them after changes if you tell it what they are
• Update it like any other docs — when architecture changes, update CLAUDE.md in the same PR

Frequently Asked Questions

Related

• Claude Code Permissions — configuring allowedTools and permission modes
• Claude Code Hooks — running commands before/after tool use
• Claude Code Memory — full memory system guide
• Claude Code Setup — initial installation and configuration
• All Claude Code Skills — back to the full directory