How to Set Up Claude Code Projects with CLAUDE.md Files

Mar 16, 2026

Problem

Every time I started a new Claude Code session, I had to explain my project from scratch. Which framework I was using. What coding style I preferred. How to handle errors. What testing requirements existed.

I wasted the first 10 minutes of every session re-explaining the same things. And even then, Claude would make assumptions. It would use patterns I didn’t want. It would skip tests I required. It would structure files in ways that didn’t match my codebase.

I tried writing these preferences in a README, but Claude didn’t consistently read it. I tried pasting instructions at the start of each session, but that got tedious fast.

Then I discovered CLAUDE.md files.

What CLAUDE.md Does

CLAUDE.md is a project-level instruction file that Claude Code reads automatically at the start of each session. You place it in your project root, and Claude follows those instructions throughout your conversation.

Here’s what changed when I added a CLAUDE.md file:

Before CLAUDE.md:

Me: Can you help me refactor this function?

Claude: Sure! [Uses class components when I want functional]
Me: Actually, can you use hooks instead?
Claude: OK! [Forgets to add error handling]
Me: Also need error handling...
Claude: Got it! [Skips tests entirely]

After CLAUDE.md:

Me: Can you help me refactor this function?

Claude: I'll refactor using functional components with hooks, add proper
error handling, and create tests to maintain 80% coverage. [Does all three]

The instructions I defined in CLAUDE.md were followed without me having to repeat them.

How to Set It Up

Basic Structure

Create a file named CLAUDE.md in your project root:

# Project Name

## Overview
Brief description of what this project does.

## Tech Stack
- Frontend: React, TypeScript, Tailwind CSS
- Backend: Node.js, Express, PostgreSQL
- Testing: Jest, Playwright

## Coding Standards

### Naming Conventions
- Components: PascalCase (e.g., UserProfile.tsx)
- Functions: camelCase (e.g., getUserData)
- Constants: SCREAMING_SNAKE_CASE (e.g., MAX_RETRIES)

### File Organization
- Components in /src/components/
- Utilities in /src/utils/
- Types in /src/types/
- One component per file

### Code Style
- Use functional components with hooks
- Prefer arrow functions
- Always handle errors explicitly
- No console.log in production code

Claude reads this file when starting in your project directory. These instructions become part of its context for that session.

Where to Place It

There are two locations:

Global level: ~/.claude/CLAUDE.md

Applies to ALL projects
Use for personal preferences and general coding style
Loaded first

Project level: <your-project>/.claude/CLAUDE.md (or CLAUDE.md in root)

Applies to ONE specific project
Use for project-specific patterns and requirements
Overrides global settings

The loading order matters. Global settings load first, then project settings can override them.

Real-World Example

I saw a Reddit post from a business owner named Agrippanux who shared their experience:

“As a business owner, it’s replaced the need for me to hire additional devs. In fact, I’m currently swamped with output from my current devs + others who are now able to add code (I have very detailed CLAUDE.md and rules and plugin setups). Adding more people to our workflow would be a net negative because the amount of output would dramatically outpace my ability to review it all.”

This caught my attention. A non-developer contributing meaningful code because of detailed CLAUDE.md setup? I wanted to see what made this work.

The key was combining CLAUDE.md with rules files. Here’s how I structured mine:

# Our Project

## Working Relationship
- I don't like sycophancy
- Be direct and concise
- Challenge incorrect assumptions
- Focus on working solutions

## Architecture
- Immutable data patterns (never mutate state)
- Repository pattern for data access
- Custom hooks for side effects
- Feature-based folder structure

## Rules
- See /rules/ directory for domain-specific guidelines
- Always read CLAUDE.md in parent directories first
- Follow existing patterns in the codebase

## Testing Requirements
- 80% minimum test coverage
- Unit tests for utilities
- Integration tests for API endpoints
- E2E tests for critical user flows

Then I created separate rule files for specific domains:

# Coding Style

## Immutability (CRITICAL)
ALWAYS create new objects, NEVER mutate:

```typescript
// WRONG: Mutation
function updateUser(user, name) {
  user.name = name  // MUTATION!
  return user
}

// CORRECT: Immutability
function updateUser(user, name) {
  return {
    ...user,
    name
  }
}

Error Handling

ALWAYS handle errors comprehensively:

try {
  const result = await riskyOperation()
  return result
} catch (error) {
  console.error('Operation failed:', error)
  throw new Error('Detailed user-friendly message')
}

Code Quality Checklist

Before marking work complete:
- [ ] Code is readable and well-named
- [ ] Functions are small (<50 lines)
- [ ] No deep nesting (>4 levels)
- [ ] Proper error handling
- [ ] No console.log statements
- [ ] No hardcoded values
- [ ] No mutation (immutable patterns used)

This structure lets me:

Set general working relationship in CLAUDE.md
Define specific patterns in rules files
Keep files focused and maintainable

Why This Works Better Than Explaining Each Time

Consistency: The same inputs produce the same outputs. Every session. No variation based on how I phrase things or what Claude “remembers.”

Efficiency: I explain once, Claude applies forever. No more spending the first 10 minutes of each session setting context.

Scalability: Team members get the same instructions. When someone new joins the project, they clone the repo and immediately have the same CLAUDE.md working for them.

Quality: Standards get enforced automatically. No more “I forgot to run tests” or “I didn’t know we use immutable patterns.”

Delegation: Non-developers can contribute. With detailed rules, even team members who aren’t primarily coders can make meaningful contributions. The rules catch mistakes and enforce patterns.

Common Mistakes I Made

Mistake 1: Being too vague

# BAD
Write good code.
Be helpful.
Care about quality.

# GOOD
Use functional components with hooks.
Run tests before every commit.
Maintain 80% test coverage.

Vague instructions produce vague results. Specific instructions produce specific outcomes.

Mistake 2: Making files too long

I initially wrote a 500-line CLAUDE.md with every possible rule. Claude started ignoring parts of it. The key is keeping it focused—200-400 lines is the sweet spot.

For detailed domain rules, use separate files in a /rules/ directory. Claude will read them when needed.

Mistake 3: No examples

# BAD
Use immutable patterns.

# GOOD
Use immutable patterns. Always create new objects, never mutate:

```typescript
// WRONG
user.name = name

// CORRECT
return { ...user, name }

Abstract rules without examples get misinterpreted. Concrete examples show exactly what you want.

**Mistake 4: Not updating when architecture changes**

I added CLAUDE.md once and forgot about it. Then we changed our testing framework from Jest to Vitest. Claude kept suggesting Jest patterns because I hadn't updated the file.

CLAUDE.md should be a living document. When architecture changes, update it.

## Layer Your Context

The most effective setup I found uses three layers:

**Layer 1: Global rules (~/.claude/rules/)**
- Personal preferences
- Working style
- General guidelines

```markdown title="~/.claude/rules/personal-style.md"
# Personal Preferences

- Be direct and concise
- Challenge incorrect assumptions
- Don't be lazy—do things the right way
- No timeline estimates in plans

Layer 2: Project CLAUDE.md

Project-specific patterns
Tech stack details
Architecture decisions

# Project Context

## Tech Stack
- Next.js 14 with App Router
- TypeScript strict mode
- Tailwind CSS
- Prisma ORM

## Patterns
- Server Components by default
- Client Components only when needed
- Server Actions for mutations

Layer 3: Directory-level instructions

Feature-specific guidance
Module-specific conventions

# Component Guidelines

- One component per file
- Colocate tests: Component.test.tsx
- Use named exports
- Props interface at top of file

This layering lets global preferences cascade down while project specifics override where needed.

Context Engineering Best Practices

I learned these patterns from experimenting and from discussions on Reddit:

Keep it focused. 200-400 lines for CLAUDE.md. Use separate files for domain-specific rules. Reference, don’t repeat.

Include examples. Show the pattern, not just describe it. Include “WRONG” and “CORRECT” examples. Use real code from your project.

Use positive instructions. “Do X” works better than “Don’t do Y.” LLMs trained on positive examples follow positive instructions better.

Update regularly. When architecture changes. When new patterns emerge. When Claude makes repeated mistakes.

Commit it. Put .claude/ directories in version control. Your team benefits from shared standards.

Summary

In this post, I showed how to set up CLAUDE.md files for Claude Code projects. The key point is that CLAUDE.md files transform Claude from a general assistant into a project-specific expert by defining clear rules, patterns, and conventions upfront.

Start simple. Create a basic CLAUDE.md covering your tech stack and coding standards. Then iteratively expand it as you identify patterns where Claude needs more guidance. The most effective CLAUDE.md files are living documents that evolve with your project.

The investment pays off quickly. After the initial setup, I saved the 10-minute context explanation at the start of every session. Claude followed my coding standards automatically. And my team members got the same consistent experience.

Final Words + More Resources

My intention with this article was to help others share my knowledge and experience. If you want to contact me, you can contact by email: Email me

Here are also the most important links from this article along with some further resources that will help you in this scope:

👨‍💻 Reddit Discussion: CLAUDE.md Benefits
👨‍💻 Anthropic: Claude Code Documentation

Oh, and if you found these resources useful, don’t forget to support me by starring the repo on GitHub!