Here’s a pattern we see constantly: a developer spends 15 minutes wrestling with an AI tool, getting output that doesn’t match their project’s conventions, manually fixing imports and naming and error handling patterns — then complaining that AI coding tools “don’t work.”

The tool works fine. The developer just never told it the rules.

The context problem

Every codebase has invisible rules. Not the ones in your linter config — the ones in your team’s heads:

You know these rules. Your teammates know them (mostly). Your AI tool has absolutely no idea.

When you ask Claude or Cursor to add a feature, it generates perfectly valid code that violates every unwritten convention in your project. Then you spend more time fixing the conventions than the AI saved you writing the code.

The fix is embarrassingly simple: write the rules down.

What is CLAUDE.md

CLAUDE.md is a file in your repository root that Claude Code reads automatically at the start of every session. It’s your project’s instruction manual for AI. Other tools have equivalents — Cursor uses .cursorrules, and some teams create custom system prompts.

The name doesn’t matter. The concept does: project-level AI documentation that gives the tool your codebase’s context before it writes a single line.

Here’s a real example:

# CLAUDE.md

## Architecture
- Next.js 14 App Router, no Pages Router
- API routes in src/app/api/ using Route Handlers
- Prisma ORM with PostgreSQL
- Auth via NextAuth.js v5

## Conventions
- Use server actions for mutations, not API routes
- All database access through src/lib/db/ repository functions
- Error handling: throw AppError with status code and message
- Zod schemas for all input validation (src/lib/schemas/)

## File Structure
- Components: src/components/{feature}/{ComponentName}.tsx
- Keep components under 150 lines; extract sub-components
- Co-locate tests: ComponentName.test.tsx next to source

## Commands
- Dev: pnpm dev
- Test: pnpm test
- Lint: pnpm lint (ESLint + Prettier)
- Type check: pnpm typecheck

That’s it. Roughly 20 lines that save 20 minutes per AI session.

Why it works so well

When Claude Code starts a session, it reads CLAUDE.md and treats it as ground truth for your project. The effect is dramatic:

Without CLAUDE.md:

You: Add a create-user endpoint
AI: *creates a Pages API route, uses raw SQL, 
     throws generic errors, puts tests in /tests*

With CLAUDE.md:

You: Add a create-user endpoint
AI: *creates an App Router route handler, uses 
     the Prisma repository layer, throws AppError, 
     puts tests next to the source file*

Same prompt. Completely different output. The AI didn’t get smarter — it got informed.

What to put in your project docs

Not everything belongs in CLAUDE.md. Here’s what actually moves the needle:

High-value content

Low-value content (skip it)

The sweet spot is 50-150 lines. Enough to establish conventions. Short enough that the AI actually processes all of it.

Beyond CLAUDE.md: the documentation ecosystem

Different tools, same principle:

.cursorrules — Cursor’s equivalent. Lives in your project root. Cursor reads it for every interaction. Same format — just write your conventions in natural language.

.github/copilot-instructions.md — GitHub Copilot’s project-level instruction file. Less powerful than CLAUDE.md since Copilot operates at a smaller context window, but still worth having.

Custom system prompts — Some teams maintain a shared prompt document that everyone pastes at the start of AI sessions. It works, but it’s manual and fragile.

Project-level AGENTS.md — A newer convention where teams document how AI agents should interact with the codebase, including which directories are off-limits and which patterns to follow for different types of changes.

The key insight: treat these files as living documentation. They go in version control. They get updated when conventions change. They’re part of your codebase, not an afterthought.

Building a CLAUDE.md from scratch

If you’re starting from zero, here’s a 15-minute process:

Step 1 (5 min): Ask your AI tool to analyze your codebase and generate a first draft:

Analyze this project's architecture, conventions, and 
patterns. Generate a CLAUDE.md that would help an AI 
assistant write code that fits this project's style.

Step 2 (5 min): Review the draft. The AI will get 70% right. Fix the parts that are wrong or missing. Add the conventions that live in your head but aren’t obvious from the code.

Step 3 (5 min): Test it. Start a new AI session, let it read the CLAUDE.md, and ask it to generate a feature. Does the output match your conventions? If not, add what’s missing.

Iterate over the next week. Every time the AI gets something wrong that it should have known, add it to the file.

The compounding effect

Here’s what makes project documentation for AI genuinely powerful: it compounds.

Week one, the AI gets your file structure right. Week two, you add error handling conventions and the AI starts throwing the right exception types. Week three, you add testing patterns and the AI writes tests that actually match your style.

By month two, you’re barely correcting AI output. It writes code that looks like your team wrote it. New team members read the CLAUDE.md to learn the project’s conventions — it’s useful for humans too.

This is what separates developers who “use AI” from developers who’ve integrated AI into their development process. The documentation is the integration layer.

Write the file. Commit it. Your future self will thank you every single session.

Share your project docs

The Coductor community shares CLAUDE.md templates, .cursorrules examples, and patterns for different stacks. Join us and steal the best ideas.

Join the Community

Documentation CLAUDE.md Best Practices Cursor Developer Productivity