How to Write a CLAUDE.md That Actually Works

What is CLAUDE.md?

A CLAUDE.md file is a project-level configuration file that gives Claude context about your codebase. When Claude Code or other Claude-powered tools encounter this file in your repository, they read it to understand your project's conventions, architecture, and preferences. Think of it as a README specifically for your AI assistant.

The concept is simple but powerful. Instead of repeating the same instructions in every prompt — "use JavaScript, not TypeScript" or "we use PostgreSQL with raw queries" — you write them once in CLAUDE.md and Claude applies them automatically across every interaction.

Structuring Your CLAUDE.md

An effective CLAUDE.md file is organized, scannable, and focused on actionable information. Here is a structure that works well:

Start with a Project Overview

Begin with two to three sentences describing what the project is and what technology stack it uses. This gives Claude the baseline context it needs for every interaction.

For example: "This is a SaaS application built with Next.js 16 (App Router), PostgreSQL, and Tailwind CSS v4. The codebase is JavaScript only. We use raw SQL queries via @neondatabase/serverless with no ORM."

List Key Commands

Include the commands a developer (or Claude) would need to build, test, lint, and run the project. This saves time and prevents Claude from guessing or suggesting incorrect commands.

Describe Your Architecture

Map out your directory structure with brief descriptions. Claude uses this to understand where things live and where new code should go. You do not need to list every file — focus on the top-level directories and any non-obvious organizational decisions.

State Your Rules Explicitly

This is the most important section. List the conventions and constraints that Claude must follow. Be direct and specific. Good rules include:

• Which language features to use or avoid.
• How to handle database queries (parameterized, ORM, etc.).
• Authentication patterns and security requirements.
• Styling approach and component conventions.
• Error handling and logging practices.

Common Mistakes to Avoid

Many teams write a CLAUDE.md that looks good but does not actually improve Claude's output. Here are the most common pitfalls:

Being Too Vague

Rules like "write clean code" or "follow best practices" give Claude nothing to work with. Instead, be specific: "All database queries must use parameterized SQL. Never use string concatenation for query building."

Including Too Much Detail

A 2,000-line CLAUDE.md is counterproductive. Claude has a context window, and an oversized configuration file consumes tokens that could be used for your actual task. Keep it focused on the rules and context that matter most. If you have extensive documentation, reference it with file paths rather than inlining everything.

Forgetting to Update It

A stale CLAUDE.md is worse than none at all. If your conventions change — you switch from CSS modules to Tailwind, or you adopt a new error handling pattern — update the file. Treat it like living documentation.

Mixing Instructions with Documentation

CLAUDE.md is for Claude, not for onboarding new developers. Keep it concise and imperative. If you need extensive documentation, put it in separate files and reference them from CLAUDE.md with a brief pointer like "See docs/ARCHITECTURE.md for detailed system design."

How CodeContext Complements CLAUDE.md

CLAUDE.md is a great starting point, but it has inherent limitations. It is a single static file checked into one repository. If your team works across multiple repos, you need to maintain multiple copies. If your standards change frequently, keeping every copy in sync becomes a chore.

CodeContext solves these problems by serving as a centralized, dynamic source of truth for your coding standards. Instead of duplicating rules across CLAUDE.md files, you store them in CodeContext and let Claude access them through MCP.

The two approaches work well together:

• CLAUDE.md handles project-specific context — directory structure, key commands, technology stack, and repo-level rules.
• CodeContext handles team-wide standards — coding conventions, architectural patterns, API guidelines, and best practices that apply across all your repositories.

With this setup, your CLAUDE.md stays lean and focused on what is unique to each repository, while your shared standards live in CodeContext where they can be maintained once and accessed everywhere. Claude gets the best of both worlds: deep project context from the local file and broad team knowledge from the MCP connection.

If you are already using CLAUDE.md, adding CodeContext is the natural next step to scale your AI-assisted workflow across your entire organization.