If you're using AI coding tools like Claude, Cursor, or GitHub Copilot to build software, you've probably experienced the frustration:

The AI puts files in the wrong place. It uses a different coding style than the rest of your project. It forgets things you told it yesterday. It breaks something that was working fine.

The problem isn't the AI. The problem is context.

AI assistants are incredibly capable, but they don't know your project. They don't know where your components live, what your database schema looks like, or that one weird bug that happens when you forget to check for null on the user object.

The solution? A single markdown file that gives your AI everything it needs to be a productive team member.

I call it CLAUDE.md.

What is CLAUDE.md?

CLAUDE.md is a documentation file that lives in the root of your project. Its sole purpose is to give AI coding assistants the context they need to work effectively on your codebase.

Think of it as onboarding documentation — but for AI.

When I first started using Claude to build our client portal at Pyrus, my CLAUDE.md was 11 lines:

That's it. And honestly, things were rough.

Claude would create components in random folders. It would use inline styles when we use CSS variables. It would write API routes that didn't match our response format. Every task required extra back-and-forth to fix the basics.

After two weeks of iteration, our CLAUDE.md grew significantly:

And the difference is night and day.

The 12 Essential Sections

Here's what I've learned should be in every CLAUDE.md:

Let me break down the most important ones:

1. Pre-commit Rules (Critical)

This is the one section you absolutely cannot skip. These are the non-negotiable rules that prevent broken builds from reaching production.

# BEFORE committing or pushing any code, you MUST: 1. Run `npm run build` and verify zero errors 2. Fix ALL errors before committing 3. Never commit code that doesn't pass a clean build  # Do not skip this step. # Do not assume it will build. # Actually run it and verify.

5. Key Patterns

Document the code patterns your project follows. Include actual code snippets — AI learns better from examples than descriptions.

### API Response Format  // Success return NextResponse.json({ data: result })  // Error return NextResponse.json(   { error: 'Message' },    { status: 400 } )

10. Common Gotchas

This might be the most valuable section. Document the mistakes that have burned you:

• Framework-specific quirks
• Auth edge cases
• Database gotchas (Row Level Security, anyone?)
• State management pitfalls

Every production bug should get added here so you never make the same mistake twice.

"We learned this one the hard way after a subscription update accidentally reset client data. Now we have a checklist for any code that touches billing."

Pro Tips

The ROI of Good Documentation

I know what you're thinking: "284 lines of documentation? That sounds like a lot of work."

It is. But consider the alternative.

Without CLAUDE.md, every AI interaction requires more context, more corrections, and more back-and-forth. You spend time fixing basic mistakes instead of building features.

With CLAUDE.md, the AI shows up to work already knowing your codebase. It follows your patterns. It puts files in the right places. It catches itself before making mistakes you've documented.

Get Started

You don't need to write all 12 sections today. Start with the critical ones:

1. Pre-commit rules — prevent broken builds
2. Project structure — tell AI where things go
3. Key patterns — show how you write code

Then add sections as you encounter friction. Every time Claude does something wrong, ask yourself: "What could I add to CLAUDE.md to prevent this?"

Over time, you'll build a comprehensive guide that makes AI-assisted development feel like working with a teammate who actually knows your codebase.

And that's when vibe coding really starts to pay off.