CLAUDE.md Configuration Guide:
Set Up Claude Code for Any Project

CLAUDE.md is the single most powerful configuration file in your Claude Code workflow — and most teams are barely using 10% of what it can do. This isn't a glorified README. It's a persistent instruction layer that Claude Code reads at the start of every session, shaping how it understands your codebase, respects your architecture decisions, and handles your team's conventions without repeating yourself 50 times a day.

Getting CLAUDE.md right is the difference between a developer assistant that asks obvious questions and one that ships production-quality code on the first attempt. Our Claude Code enterprise deployment service spends a significant chunk of onboarding time on this file alone — because the payoff is immediate and measurable.

What Is CLAUDE.md and Why It Matters

When Claude Code starts a session in your project directory, it automatically scans for a file named CLAUDE.md at the repository root. Everything in this file is injected into Claude's context before your first message. It's not a one-time setup — it's read on every session, on every subagent invocation, and by every Claude Code instance running in that repository.

Think of it as the briefing document you'd hand a senior contractor on their first day. Except this contractor reads it perfectly, retains it completely, and applies it consistently — as long as you write it well. Without a CLAUDE.md, Claude Code is making educated guesses about your tech stack, your naming conventions, your preferred libraries, and which parts of the codebase are off-limits for modification.

The CLAUDE.md system supports three scopes. The project-root CLAUDE.md covers the entire repository and is the most commonly used. Subdirectory CLAUDE.md files override or extend project-root instructions for specific packages or modules — useful in monorepos where the payments service has different rules than the frontend. The global CLAUDE.md at ~/.claude/CLAUDE.md applies across every project on that machine and is ideal for personal preferences like output formatting or editor conventions that follow you everywhere.

For enterprise Claude Code deployments, we also recommend maintaining a shared CLAUDE.md template in version control that gets applied to every new repository. This ensures organisation-wide standards — security patterns, approved libraries, compliance requirements — are baked into every Claude Code session from day one.

Anatomy of an Effective CLAUDE.md

There's no enforced schema for CLAUDE.md — it's plain Markdown, and Claude reads it as prose. But structure matters enormously. Claude Code performs significantly better when the file is organised into clearly labelled sections with consistent formatting. Here's the structure we use across client deployments:

# [Project Name] — Claude Code Configuration

## Project Overview
[2-3 sentences: what this codebase does, its primary language/framework, and its purpose in the architecture]

## Tech Stack
- Language: TypeScript 5.3, Node.js 20 LTS
- Framework: Next.js 14 (App Router)
- Database: PostgreSQL via Prisma ORM
- Auth: NextAuth.js v5
- Testing: Vitest + Playwright
- Deployment: AWS ECS via Terraform

## Architecture & Key Decisions
[Explain WHY, not just what. This is where Claude learns your patterns.]

## Code Style & Conventions
[Naming, file structure, import order, async patterns]

## Forbidden Patterns
[Explicit list of what NOT to do — as important as what to do]

## Testing Requirements
[When to write tests, what to test, coverage expectations]

## Deployment & Environments
[How this gets to production, what's safe to change]

## Security Rules
[Never commit X, always sanitise Y, use Z for secrets]

## Common Tasks
[Recipes for the 5-10 operations Claude will be asked to do most often]

Each section serves a purpose. The overview prevents Claude from misidentifying the project type. The tech stack section stops it suggesting axios when you use fetch, or proposing a class component when you're on a hooks-only codebase. The architecture decisions section is the most valuable — it's where you record the non-obvious choices that would otherwise require 20 minutes of context-setting every session.

The Architecture & Key Decisions Section

This is the section most teams skip, and it's the biggest missed opportunity. Don't just describe your architecture — explain the constraints and decisions that shaped it. "We use server actions instead of API routes because of our deployment model." "The payments module cannot import from the orders module due to circular dependency risks — always go through the shared types package." "We chose Zod over Yup specifically because of its TypeScript inference quality — use Zod for all validation."

These decisions are invisible to anyone reading the code for the first time, human or AI. Capturing them in CLAUDE.md means Claude Code becomes a guardian of your architectural standards rather than an inadvertent violator of them.

The Forbidden Patterns Section: Your Most Important Safety Net

The forbidden patterns section is the highest-ROI section in any CLAUDE.md for enterprise teams. It's where you prevent Claude Code from making suggestions that are technically valid but wrong for your specific context. Left unconfigured, Claude will optimise for general correctness — which sometimes conflicts with your security policies, performance requirements, or regulatory environment.

## Forbidden Patterns

### Never Do These
- Do NOT use `any` type in TypeScript. Use `unknown` and narrow properly.
- Do NOT use `console.log` in production code. Use the logger utility at `src/lib/logger.ts`.
- Do NOT access `process.env` directly. Use the typed config at `src/config/index.ts`.
- Do NOT modify files in `src/generated/` — these are auto-generated by Prisma.
- Do NOT use `eval()`, `Function()`, or dynamic `require()`.
- Do NOT implement your own crypto. Use the crypto utilities in `src/lib/crypto.ts`.
- Do NOT add new dependencies without checking the approved library list in `docs/approved-libraries.md`.

### Patterns We've Deliberately Moved Away From
- We used to use Redux. All new state management uses Zustand. Don't add Redux.
- We migrated away from class components in 2023. Write functional components only.
- The old API at `/api/v1/` is deprecated. All new endpoints use `/api/v2/` with the new auth middleware.

Notice the two categories: absolute prohibitions (security and correctness) and migration notes (historical context). The second category is often overlooked. Without it, Claude will reasonably suggest patterns based on what it finds in the codebase — including the legacy patterns you're trying to eliminate. Documenting these in CLAUDE.md actively accelerates your migration efforts.

The Common Tasks Section: Pre-Written Recipes

One of the most powerful but least-known features of CLAUDE.md is the ability to define common task recipes — step-by-step instructions for the operations Claude Code will be asked to perform repeatedly. When a developer types "add a new API endpoint", Claude will follow the recipe in CLAUDE.md rather than inventing a generic approach each time.

## Common Tasks

### Adding a New API Endpoint
1. Create the route handler in `src/app/api/v2/[resource]/route.ts`
2. Import and use `withAuth` middleware from `src/lib/middleware/auth.ts`
3. Validate request body using Zod schema — define schema in same file
4. Call the relevant service function from `src/services/` (never business logic in route handlers)
5. Return using the `apiResponse` utility from `src/lib/api-response.ts`
6. Add the endpoint to `docs/api-reference.md`
7. Write an integration test in `tests/api/`

### Adding a New Database Model
1. Define the Prisma schema in `prisma/schema.prisma`
2. Run `npx prisma migrate dev --name [migration-name]`
3. Run `npx prisma generate` to update the client
4. Create a service file in `src/services/[model-name].ts` for all DB operations
5. Do NOT query the database directly from route handlers or components

### Running Tests
- Unit tests: `npm run test`
- Integration tests: `npm run test:integration`
- E2E tests: `npm run test:e2e` (requires running dev server)
- Before PR: `npm run test:all && npm run lint && npm run type-check`

These recipes are particularly valuable for onboarding. When a developer is new to a codebase and using Claude Code, the common tasks section effectively transfers institutional knowledge at scale. Our Claude Code training workshops walk teams through building out this section collaboratively — it's one of the exercises that generates the most immediate team engagement.

Configuring CLAUDE.md in Monorepos

Monorepos require a layered approach. The root CLAUDE.md should cover organisation-wide standards: security policies, approved libraries, deployment context, and anything that applies across every package. Then each package or application within the monorepo can have its own CLAUDE.md that extends or overrides the root configuration for that specific context.

my-monorepo/
├── CLAUDE.md                    # Global: security, tooling, org standards
├── apps/
│   ├── web/
│   │   └── CLAUDE.md            # Next.js-specific config, React conventions
│   ├── api/
│   │   └── CLAUDE.md            # Express/Fastify config, REST conventions
│   └── mobile/
│       └── CLAUDE.md            # React Native config, mobile-specific patterns
└── packages/
    ├── shared-types/
    │   └── CLAUDE.md            # "This is a shared types package — no runtime code"
    └── ui-components/
        └── CLAUDE.md            # Storybook, design tokens, accessibility rules

When Claude Code is working inside apps/api/, it reads both the root CLAUDE.md and the apps/api/CLAUDE.md. This means you can enforce global standards while allowing each package to have its own clear boundaries and conventions. A team working on the mobile app doesn't need to be constrained by the API team's database access patterns — and vice versa.

For large enterprise monorepos, we often add a CLAUDE.md to sensitive packages with explicit access restrictions: "This is the payments service. Never modify the charge execution functions in src/charge.ts without explicit approval. All changes require a second set of eyes." This doesn't prevent Claude from making changes — it ensures those changes are flagged as high-stakes during review.

Security Considerations for CLAUDE.md

CLAUDE.md is stored in version control and is visible to everyone with repository access — which is usually the right call for project-level configuration. However, a few security considerations are worth addressing explicitly.

Never put sensitive values in CLAUDE.md. No API keys, no internal endpoint URLs that shouldn't be public, no internal hostname patterns that reveal infrastructure topology. CLAUDE.md is documentation-level content, not secrets management. Reference your secrets management system by name ("use Vault at the standard ENV_VAR approach") rather than exposing actual values or internal paths.

For the global CLAUDE.md at ~/.claude/CLAUDE.md, be more cautious about what you include. This file applies to all projects on the machine and could inadvertently expose personal configuration that doesn't belong in a corporate project context. We recommend keeping the global CLAUDE.md to purely personal preferences and coding style, with no project-specific content.

In enterprise environments with strict security requirements, consider whether CLAUDE.md content should be reviewed as part of your code review process. If a developer adds a forbidden pattern to CLAUDE.md that effectively un-bans a security-relevant practice, that should be caught in review. Our Claude governance framework includes CLAUDE.md review policies for precisely this reason.

Real-World CLAUDE.md Examples by Stack

Python / FastAPI Microservice

# Billing Service — Claude Code Configuration

## Overview
FastAPI microservice handling subscription billing and invoice generation.
Part of a larger microservices architecture. Communicates via gRPC with the
orders service and REST with the customer service.

## Tech Stack
- Python 3.12, FastAPI 0.110, Pydantic v2
- Database: PostgreSQL via SQLAlchemy 2.0 (async)
- Message queue: Kafka via aiokafka
- Testing: pytest + pytest-asyncio, coverage >= 90%
- Container: Docker, deployed to Kubernetes

## Critical Rules
- All financial calculations use the `Decimal` type. Never use float for money.
- All Kafka consumers must be idempotent. Every message may be delivered more than once.
- Never call external payment APIs from tests. Use the mock in `tests/mocks/stripe.py`.
- Database migrations via Alembic only. No raw DDL in application code.
- Structured logging via loguru. Log correlation IDs on every request.

## Forbidden Patterns
- No `from x import *`
- No mutable default arguments
- No synchronous database calls in async routes (use `await` always)
- No bare `except:` clauses

Java / Spring Boot Service

# Customer Data Service — Claude Code Configuration

## Overview
Spring Boot 3.2 service managing customer records and preferences.
Deployed to AWS ECS. SOC 2 and GDPR regulated data.

## Architecture
Hexagonal architecture (ports and adapters). Business logic in domain layer,
never in controllers or repositories. Domain objects are immutable records.
Use the mapper classes in `infrastructure/mappers/` to convert between layers.

## Critical Compliance Rules
- Never log fields marked @PII in domain objects (see PII annotations in `domain/`)
- Data deletion requests must go through `CustomerDeletionService` — never raw deletes
- All external API calls must use the retry-aware `HttpClient` in `infrastructure/http/`
- Audit logging required for all create/update/delete operations via `AuditService`

## Forbidden Patterns
- No `@Autowired` field injection — constructor injection only
- No Lombok @Data on entities — write explicit constructors and builders
- No direct EntityManager usage — use repositories
- No `Optional.get()` without `isPresent()` check

Keeping CLAUDE.md Current

CLAUDE.md rots if you don't maintain it. We see this pattern repeatedly: a team invests in a great CLAUDE.md at project start, then ignores it for six months while the codebase evolves. The result is a file full of outdated patterns, references to libraries you've since replaced, and forbidden patterns that no longer apply because you already removed the old code.

The most effective maintenance habit is treating CLAUDE.md as part of your pull request template. When a PR introduces a new architectural pattern, updates a library, or removes a legacy system, updating CLAUDE.md should be a checklist item. If the PR isn't big enough to warrant a CLAUDE.md change, it probably doesn't need one — but a migration PR absolutely should include one.

For larger teams, assign CLAUDE.md ownership to the same person or group responsible for developer experience or architecture decisions. This isn't a file that should be edited by committee on every PR — it should have clear owners who maintain its quality and accuracy. Think of it like your architecture decision records: important, carefully maintained, and owned by people who care about the long-term health of the system.

If you're evaluating Claude Code for your engineering organisation and want to see what a production-grade CLAUDE.md looks like for your specific stack, book a free strategy call with our Claude Certified Architects. We've built these configurations across financial services, healthcare, and manufacturing — the patterns transfer well.