CLAUDE.md: The Instruction Manual for Your Code Assistant

You hired a senior developer. Brilliant, knows dozens of languages, learns fast, works 24 hours. But he doesn’t know your project. Doesn’t know your conventions. Doesn’t understand why you do certain things a specific way.

The CLAUDE.md is the welcome letter you write for that developer.

What Is CLAUDE.md

CLAUDE.md is a markdown file that Claude Code reads automatically at the start of each session. It works as the agent’s long-term memory — the instructions it should always follow, regardless of what you ask in the moment.

Think of it this way: the prompt you type is today’s task. CLAUDE.md is the employee onboarding.

Where Claude looks for the file:

1. CLAUDE.md in the project root (most common)
2. .claude/CLAUDE.md (alternative organization)
3. ~/.claude/CLAUDE.md (global instructions for all projects)
4. CLAUDE.local.md (personal, should be in .gitignore)

The hierarchy is respected. Global instructions load first, then project, then local. The most specific takes precedence.

The WHY-WHAT-HOW Structure

An effective CLAUDE.md answers three questions:

WHY — Why Does This Project Exist

Claude works better when it understands the purpose. Doesn’t need to be long.

## Purpose

Corporate credit management system for the US market.
Focus: mid-market companies with revenue between $10M and $500M.
Differentiator: native integration with credit bureaus and banking APIs.

The “why” helps Claude make decisions when instructions don’t cover a specific case.

WHAT — What Exists Here

Map of the territory. Claude needs to know where to find things.

## Project Structure

src/ ├── domain/ # Business logic (DDD) │ ├── credit/ # Credit analysis │ └── customer/ # Customer management ├── infra/ # Technical implementations │ ├── database/ # Repositories (Postgres) │ └── external/ # External APIs └── api/ # Controllers and routes

**Main technologies:**
- Node.js 20 + TypeScript 5.3
- PostgreSQL 15 with Prisma ORM
- Jest for tests, Vitest for fast unit tests

Tip: Use file:line references instead of copying code. Claude can read files directly.

See repository example at `src/infra/database/CustomerRepository.ts:15-45`

HOW — How to Do Things

Commands, conventions, workflows. What Claude needs to execute.

## Commands

```bash
npm run dev          # Development server
npm run test         # All tests
npm run test:watch   # Tests in watch mode
npm run lint         # ESLint + Prettier check
npm run db:migrate   # Apply pending migrations

Conventions

• Commits: Conventional Commits
  • feat: add CNPJ validation
  • fix: correct credit score calculation
• Branches: feature/, fix/, refactor/
• PRs: Always with description and test checklist

Verification

Before considering any task complete:

1. npm run lint passes without errors
2. npm run test passes
3. Changes are covered by tests

## Best Practices

### 1. Be Concise

The recommended limit is **300 lines**. The ideal is **under 60**. LLMs reliably follow between 150-200 instructions. After that, adherence drops.

**Bad:**
```markdown
## Code Rules

Always use const instead of let when variable won't be reassigned.
Always use arrow functions for callbacks.
Always use template literals instead of concatenation.
Always use destructuring when possible.
Always use optional chaining when accessing nested properties.
... (50 more rules)

Good:

## Code Style

We follow the `@company/eslint-config` preset. Don't repeat linter rules here.

2. Don’t Use as Linter

CLAUDE.md is for what can’t be automatically verified. Formatting rules should be in ESLint, Prettier, or equivalent.

Use CLAUDE.md for:

• Architectural decisions
• Business conventions
• Workflows
• Context that machines don’t infer

Don’t use for:

• Indentation rules
• Import order
• Spacing
• Anything a deterministic tool validates

3. Progressive Disclosure

Not everything needs to be in CLAUDE.md. Reference external documentation.

## Documentation

- Architecture: `/docs/architecture.md`
- API: `/docs/api.md`
- Deployment: `/docs/deploy.md`

Consult these files when you need specific details.

Claude reads files on demand. You keep CLAUDE.md lean.

4. Iterate Constantly

Treat CLAUDE.md as living code. Every time Claude makes a recurring error, ask: “Should this be in CLAUDE.md?”

Improvement cycle:

1. Claude makes mistake
2. You correct manually
3. You identify if it’s recurring
4. You add instruction to CLAUDE.md
5. Repeat

Some teams ask Claude itself: “What should be in CLAUDE.md that would have prevented this error?“

5. Use Context Markers

Organize with clear headings. Claude processes structured information better.

## FORBIDDEN

- Never commit `.env` files
- Never push directly to `main`
- Never modify migrations already applied in production

## REQUIRED

- Every endpoint must have integration test
- Every error handler must log context
- Every feature must have feature flag

Essential Commands

/init — Automatic Creation

In the terminal, inside the project:

claude

Then type:

/init

Claude analyzes your project and generates an initial CLAUDE.md. Review and adjust — what’s generated is a starting point, not final destination.

/permissions — Access Management

/permissions

Controls what Claude can do without asking permission. Useful for:

• Allowing automatic test execution
• Allowing automatic formatting
• Restricting access to sensitive folders

/clear — Clear Context

/clear

When the conversation gets long or confused, clears history. Claude re-reads CLAUDE.md and starts fresh.

# — Ad-Hoc Instructions

During the session, you can add temporary instructions:

# I'm refactoring the payments module.
# Prefer composition over inheritance.
# Maintain compatibility with API v1.

These instructions last until session end or until you use /clear.

Magic Words

Claude Code responds to depth-of-reasoning indicators:

Word	Meaning
think	Standard reasoning
think hard	Deeper reasoning
ultrathink	Maximum reasoning (Extended Thinking)

When to use:

• think: Routine tasks, simple fixes
• think hard: Complex debugging, architectural decisions
• ultrathink: Problems you’d have difficulty solving yourself

In CLAUDE.md, you can set the default:

## Reasoning Mode

Use `ultrathink` for:
- Changes affecting more than 3 files
- Any modification to `src/domain/`
- Performance problem debugging

Recommended Workflows

Explore, Plan, Code, Commit

The most efficient flow with Claude Code:

1. Explore

Analyze the current authentication module structure.
What dependencies exist? What patterns are used?

2. Plan

I need to add SAML authentication.
Create a detailed plan before implementing.
Don't write code yet.

3. Code

Implement the plan. Start with the SAML adapter.

4. Commit

Review changes and create semantic commits.

TDD with Claude

Claude excels at TDD:

I want to implement SSN validation.
First, write the tests. Don't implement yet.

Review the tests. Then:

Now implement to pass the tests.

Cross-Verification

After complex implementation:

Critically review your own implementation.
List potential problems, uncovered edge cases,
and performance improvements.

Claude frequently finds problems it created itself.

Multi-Claude Workflows

For large projects, consider multiple instances:

Git Worktrees

# Create parallel worktree
git worktree add ../project-feature-auth feature/auth

# In one terminal
cd ../project-feature-auth && claude

# In another terminal (main project)
claude

Two Claudes working in parallel, isolated by branches.

Peer Verification

After Claude A finishes a feature:

# In Claude B
Review PR #123. Identify issues with:
- Security
- Performance
- Maintainability
- Test coverage

Two agents, different perspectives.

CLAUDE.md Examples

Node.js/TypeScript Project

# CreditFlow Project

Credit analysis system for SMBs.

## Stack

- Node.js 20, TypeScript 5.3
- PostgreSQL 15, Prisma ORM
- Express.js, Jest

## Structure

src/domain/ # Business logic src/infra/ # Implementations src/api/ # HTTP layer

## Commands

```bash
npm run dev     # Dev server (port 3000)
npm run test    # Tests
npm run lint    # Verification

Conventions

• Commits: Conventional Commits
• Tests: All code in domain/ needs tests
• Errors: Use custom error classes in src/domain/errors/

Verification

Before finishing any task:

1. npm run lint passes
2. npm run test passes
3. Changes have test coverage

### Python/FastAPI Project

```markdown
# Invoice Processing API

Service for extraction and validation of electronic invoices.

## Stack

- Python 3.11, FastAPI
- PostgreSQL, SQLAlchemy
- Pytest, Ruff

## Environment

```bash
source .venv/bin/activate
uvicorn app.main:app --reload

Structure

app/
├── domain/     # Entities and rules
├── services/   # Use cases
├── api/        # FastAPI routes
└── infra/      # DB, External APIs

Conventions

• Type hints required
• Docstrings for public functions
• Pydantic for input validation

FORBIDDEN

• Don’t use print() for debug (use logging)
• Don’t commit .env
• Don’t make direct SQL queries (use SQLAlchemy)

## Common Mistakes

### 1. CLAUDE.md Too Long

If it passed 300 lines, it's wrong. Move details to separate documentation.

### 2. Repeating Linter Rules

If ESLint already validates it, doesn't need to be in CLAUDE.md.

### 3. Vague Instructions

**Bad:** "Write clean code"
**Good:** "Functions over 20 lines should be split"

### 4. Not Updating

Outdated CLAUDE.md is worse than none. Keep it synchronized with the project.

### 5. Ignoring .local

Use `CLAUDE.local.md` for personal preferences:

```markdown
# CLAUDE.local.md (in .gitignore)

I'm John. I prefer:
- Detailed explanations
- Verbose commit messages
- Focus on performance

Conclusion

CLAUDE.md is the bridge between the model’s generic intelligence and your project’s specific knowledge. Well written, it transforms Claude from a generic assistant into a team member who knows your conventions.

Start simple. Iterate always. The perfect CLAUDE.md doesn’t exist — there’s the CLAUDE.md that evolves with your project.

---

At Victorino Group, we use Claude Code extensively to accelerate delivery without sacrificing quality. If you want to implement AI agents with governance in your team, let’s talk.