CLAUDE.md: The File That Makes AI Understand Your Codebase

The Most Important File in Your Project

If I could give one piece of advice to any developer using Claude Code, it would be this: write a good CLAUDE.md file. Nothing else you do will have as much impact on the quality of AI-assisted development.

CLAUDE.md is a markdown file at the root of your project that tells Claude Code how to work with your codebase. It describes your conventions, your patterns, your architectural decisions, your preferred approaches. Think of it as the onboarding document for an AI pair programmer.

Without CLAUDE.md, Claude Code works with generic best practices. It writes good code, but it writes code in its style, not yours. With a well-written CLAUDE.md, Claude Code writes code that looks like it belongs in your project — because it understands the rules.

What Goes in CLAUDE.md

Over the past year, I have refined my CLAUDE.md files across multiple React and Next.js projects. Here is what I have found matters most:

Project Overview

Start with a brief description of what the project is and its technical stack. This sets the foundation for everything else:

# Project: DashboardPro

A B2B analytics dashboard built with Next.js 14 (App Router), TypeScript,
TailwindCSS, and shadcn/ui. Backend is a separate Express API.

## Tech Stack
- Next.js 14 with App Router
- TypeScript (strict mode)
- TailwindCSS + shadcn/ui
- Zustand for client state
- TanStack Query for server state
- React Hook Form + Zod for forms
- Vitest + React Testing Library for tests

Architecture and File Structure

Explain how your project is organized and why. This prevents Claude Code from putting files in the wrong place:

## Architecture

### Directory Structure
- `app/` — Next.js App Router pages and layouts
- `components/` — Reusable UI components
  - `components/ui/` — shadcn/ui base components (do not modify)
  - `components/[feature]/` — Feature-specific components
- `hooks/` — Custom React hooks
- `stores/` — Zustand stores
- `services/` — API client functions
- `types/` — Shared TypeScript types
- `lib/` — Utility functions and configurations
- `__tests__/` — Integration tests (unit tests are co-located)

### Component Organization
Each component directory contains:
- `ComponentName.tsx` — The component
- `ComponentName.types.ts` — Props interface and related types
- `ComponentName.test.tsx` — Unit tests
- `index.ts` — Barrel export

Coding Conventions

This is where you get specific about how code should be written in your project:

## Conventions

### Components
- Use function declarations, not arrow functions, for components
- Always use forwardRef for components that render DOM elements
- Props interface named `[ComponentName]Props`
- Export component as default from the file
- Barrel export from index.ts

Example:
```tsx
// Good
function Button({ variant, children, ...props }: ButtonProps) {
  return <button className={cn(buttonVariants({ variant }))} {...props}>{children}</button>
}

// Bad
const Button: React.FC<ButtonProps> = ({ variant, children }) => { ... }

Hooks

• Custom hooks start with use
• One hook per file
• Return object, not array (unless it is a simple two-value hook)
• Include JSDoc with @example

State Management

• Zustand for client state (UI state, user preferences)
• TanStack Query for server state (API data)
• NEVER use useState for data that comes from an API
• NEVER use useEffect for data fetching

Styling

• TailwindCSS utility classes, never inline styles
• Use cn() utility for conditional classes (from lib/utils)
• Design tokens defined in tailwind.config.ts
• No CSS modules, no styled-components

### Error Handling Patterns

Specify how errors should be handled consistently:

```markdown
## Error Handling

### API Calls
- All API functions return `Promise<ApiResponse<T>>`
- ApiResponse shape: `{ data: T | null, error: string | null }`
- Components use TanStack Query's error state
- Never try-catch in components — let the query handle it

### Error Boundaries
- Wrap each route segment in an ErrorBoundary
- ErrorBoundary shows a user-friendly message with retry button
- Log errors to our monitoring service via `logError()`
- Never show stack traces or technical details to users

Testing Standards

Tell Claude Code exactly how to write tests for your project:

## Testing

### Unit Tests
- Co-located with the component: `Component.test.tsx`
- Use React Testing Library, NOT Enzyme
- Test behavior, not implementation
- Use `screen.getByRole()` over `getByTestId()` when possible
- Mock API calls with MSW, not jest.mock

### Test Structure
```tsx
describe('ComponentName', () => {
  it('renders in default state', () => { ... })
  it('handles user interaction: [specific action]', () => { ... })
  it('displays error state when API fails', () => { ... })
  it('is accessible (has correct ARIA attributes)', () => { ... })
})

What to Test

• User-visible behavior
• Error states
• Loading states
• Accessibility attributes
• Keyboard navigation for interactive elements

### Build and Run Commands

Simple but critical — tell Claude Code how to build, test, and run your project:

```markdown
## Commands

- `npm run dev` — Start development server
- `npm run build` — Production build
- `npm run test` — Run all tests
- `npm run test:watch` — Run tests in watch mode
- `npm run lint` — ESLint check
- `npm run type-check` — TypeScript type checking

Things to Avoid

Explicit anti-patterns are just as important as positive patterns:

## Anti-patterns (DO NOT USE)

- DO NOT use `any` type — always define proper interfaces
- DO NOT use `useEffect` for data fetching — use TanStack Query
- DO NOT use inline styles — use Tailwind classes
- DO NOT use `console.log` — use our logger utility
- DO NOT create new CSS files — everything is Tailwind
- DO NOT add new dependencies without checking if shadcn/ui
  or our existing utilities already solve the problem
- DO NOT use default exports for hooks or utilities — only for components
- DO NOT use relative imports that go up more than 2 levels — use @ alias

Advanced CLAUDE.md Techniques

Context-Specific Sections

You can include sections that only matter for certain types of work:

## When Working on Forms
- Always use React Hook Form + Zod
- Schema defined in a separate file: `formName.schema.ts`
- Error messages come from the Zod schema, not hardcoded in JSX
- Submit handler calls the appropriate service function
- Show loading state on the submit button during submission

## When Working on API Integration
- Service functions live in `services/[domain].ts`
- Use the `apiClient` from `lib/apiClient.ts` — never raw fetch
- Response types defined in `types/api/[domain].ts`
- Always handle pagination with our `usePaginatedQuery` hook

Team-Specific Guidelines

When I set up Claude Code for teams, the CLAUDE.md often includes team agreements:

## Team Agreements
- PR descriptions must explain WHY, not just WHAT
- Every new component needs at least one test
- Accessibility is not optional — every interactive element needs
  keyboard support and ARIA attributes
- New features behind feature flags (use our FeatureFlag component)

The Impact of a Good CLAUDE.md

The difference between working with and without CLAUDE.md is stark. Without it, I spend time correcting Claude Code's output — changing arrow functions to function declarations, moving test files to the right location, fixing import patterns. With it, the output matches my project's conventions from the start.

In my experience, a well-written CLAUDE.md reduces the need for manual corrections by about 80 percent. That translates directly to faster development and more consistent code.

The investment is small — maybe an hour to write a thorough CLAUDE.md. The return is every single interaction with Claude Code producing better, more consistent, more project-appropriate code. For any project that lasts more than a week, it is the highest-leverage hour you will spend.