If you use Claude Code, you've probably discovered that it reads a file called CLAUDE.md at the start of every conversation. This file is one of the most powerful features in Claude Code, and also one of the most misunderstood. Most people either don't use it at all, or stuff it with too much content and wonder why Claude ignores half of it.
This guide covers what CLAUDE.md files are, how to structure them, what they're genuinely great at, and where they fall short. If you've hit the ceiling of what CLAUDE.md can do, the second half covers how to extend your setup with external knowledge bases.
What CLAUDE.md files are
CLAUDE.md is a markdown file that gets loaded into Claude Code's system prompt at the start of every conversation. Think of it as persistent instructions that Claude reads before you say anything. Whatever you put in this file shapes how Claude behaves, what it knows about your project, and what rules it follows.
You write it in markdown because that's what Claude natively understands. Headings, lists, bold text, code blocks: Claude parses all of it. The file becomes part of Claude's context window, meaning the content counts against your available tokens, but it's always there, always loaded, every single time.
The CLAUDE.md hierarchy
There isn't just one CLAUDE.md. There's a hierarchy of five levels, each serving a different scope. More specific files take precedence over broader ones.
1. Enterprise policy. Located at /Library/Application Support/ClaudeCode/CLAUDE.md on macOS. This is managed by IT administrators and applies system-wide across all users on the machine. If your organization has compliance rules or security policies that every Claude Code conversation must follow, they go here. Most individual users will never create this file.
2. User-level. Located at ~/.claude/CLAUDE.md. This is your personal configuration across all projects. Put your general preferences here: how you like code formatted, which languages you prefer, your communication style, any rules that apply regardless of what project you're working in.
3. Project-level. Located at ./CLAUDE.md in the repository root. This is the most commonly used level. It holds project-specific rules, architecture notes, testing conventions, and deployment instructions. Because it lives in the repo, you can commit it to git, and your entire team shares the same Claude Code configuration.
4. CLAUDE.local.md. Same locations as levels 1 through 3, but with a .local.md suffix. These files are gitignored by default, making them perfect for personal overrides. Maybe the team's CLAUDE.md says to use Prettier, but you prefer a different formatter for local development. Put your override in CLAUDE.local.md and it won't affect anyone else.
5. Child directory files. Any subdirectory in your project can have its own CLAUDE.md. These are loaded lazily, only when Claude reads files in that directory. A frontend/CLAUDE.md might contain React-specific conventions, while backend/CLAUDE.md has API design rules. Claude picks them up on demand without bloating the initial context.
The precedence rule is straightforward: more specific wins. A project-level instruction overrides a user-level instruction. A child directory instruction overrides a project-level one. A .local.md file overrides its non-local counterpart at the same level.
Best practices for CLAUDE.md
After working with these files extensively, here's what actually works.
Keep the file under 150 lines. Claude Code's auto-memory loads only the first 200 lines of CLAUDE.md. Anything beyond that risks being truncated. More importantly, shorter files get more reliable adherence. A 50-line file with clear instructions outperforms a 300-line file where important rules are buried in paragraph 47.
Put the most important instructions first. Claude processes instructions sequentially, and earlier instructions tend to carry more weight. If you have a critical rule ("never push to main without tests"), put it near the top, not at the bottom after your font preference and commit message format.
Use separate topic files for detailed notes. Your main CLAUDE.md should be an executive summary: the rules, the architecture overview, the key commands. For deep reference material (API schemas, migration guides, detailed technical notes), create separate files and reference them from the main file. Claude can read those files on demand when it needs the detail.
Be specific, not vague. "Write good tests" is useless. "Run npm test before every commit. Use Vitest with happy-dom. Test files go in tests/ mirroring the src/ structure. Bug fixes must include a reproducing test." That's an instruction Claude can actually follow.
Include common commands. Build commands, test commands, deployment commands, linting commands. Claude uses these constantly, and having them in CLAUDE.md means it doesn't have to guess or ask.
What CLAUDE.md is great for
CLAUDE.md excels at a specific category of information: project-specific developer knowledge that applies to every conversation.
Coding standards. Formatting rules, naming conventions, import order, file organization patterns. Claude follows these consistently when they're in CLAUDE.md.
Project architecture. A concise overview of your tech stack, directory structure, and key files. Not the entire codebase documentation, but enough for Claude to understand where things live and how they connect.
Testing conventions. Framework, test file locations, patterns to follow, commands to run. This is one of the highest-value categories because it prevents Claude from generating tests in the wrong framework or the wrong directory.
Style rules. Code style, but also prose style if your project involves documentation or content. Terminology choices, tone preferences, formatting standards.
Deployment instructions. How to build, where to deploy, what environment variables matter, what commands to run. Claude can execute these directly when asked.
Common gotchas. Known issues, platform-specific quirks, things that look right but break in production. If you've debugged it once, write it down so Claude never introduces the same problem.
The limitations of CLAUDE.md
CLAUDE.md is not a general-purpose knowledge base. It has real constraints that become apparent as your needs grow.
It's static. You edit the file manually. It doesn't evolve with your project automatically. When your architecture changes, when new team members join, when priorities shift, someone has to open the file and update it. In fast-moving projects, CLAUDE.md drifts out of date quickly.
It's code-focused. CLAUDE.md was designed for developer workflows in Claude Code. It handles coding standards and project architecture well. It's not designed for meeting notes, product roadmaps, competitive analysis, style guides for marketing content, or any of the broader organizational knowledge that would make AI conversations genuinely useful beyond coding.
Compacting can lose it. This is a known issue (GitHub #9796). When a conversation grows long enough to trigger compaction (around 83.5% of context usage), the compaction summary does not always preserve CLAUDE.md content. This means instructions you thought were permanent can effectively disappear mid-conversation. Critical rules you set at the start may not survive to the end of a long session.
The line limit is real. Auto-memory truncates after 200 lines. For a simple web app, 200 lines is plenty. For a complex system with multiple services, detailed architecture, strict compliance requirements, and nuanced coding standards, 200 lines is a fraction of what you need. You can work around this with child directory files and referenced topic files, but it adds management overhead.
It only works in Claude Code. CLAUDE.md has zero effect in claude.ai, Claude Desktop, or any other Claude interface. If you use Claude for non-coding tasks (writing, research, analysis, planning), or if you switch between Claude Code and the web interface, CLAUDE.md only covers part of your workflow. Your broader organizational knowledge needs a different solution.
When you need something more
CLAUDE.md handles project-specific coding rules well. But there's a category of knowledge it was never designed for: organizational context that should be available across tools, across conversations, and across team members.
This is where external knowledge bases come in, specifically through MCP (Model Context Protocol). Instead of cramming everything into a static file, you maintain documents in an external service that Claude can read on demand.
Documents that Claude can read and update. Unlike CLAUDE.md, which you edit manually, external documents can be updated by Claude itself. Ask Claude to update the project status document after a deploy, and it does. The next conversation sees the current version automatically.
Knowledge that works across Claude Code, claude.ai, and Claude Desktop. A single knowledge base serves all your Claude interfaces. Your product roadmap, style guide, and team context are available whether you're coding in the terminal or brainstorming in the browser.
Content that serves multiple purposes. The same document that gives Claude context about your product can also be published as a web page, formatted for Google Docs, converted for Slack, or shared with your team via email. Your knowledge base isn't locked inside a developer tool.
No line limits, no compaction concerns. External documents persist independently of any conversation. There's no 200-line cap, no compaction risk, and no token budget competition. Claude reads documents on demand and gets the full content every time.
The best setup: CLAUDE.md plus an external knowledge base
The two approaches are complementary, not competing.
Use CLAUDE.md for what it does best: project-specific coding rules that every Claude Code conversation should follow. Your testing framework, your directory structure, your build commands, your style rules. Keep it under 150 lines, keep it focused, and commit it to your repository so the whole team benefits.
Use an external knowledge base via MCP for everything else: product roadmaps, meeting notes, company context, competitive analysis, style guides for non-code content, project status tracking, and any knowledge that should persist across conversations and across Claude interfaces.
Unmarkdown™ provides this external knowledge base layer with a built-in MCP server. Your documents are written in markdown (the same format Claude natively understands), the AI can both read and update them, and the same documents can be published as web pages or formatted for Word, OneNote, or Plain Text using 62 templates.
The Claude integration guide walks through connecting Unmarkdown™ to Claude Code, claude.ai, and Claude Desktop. The integrations overview covers the full MCP setup, including configuration for other AI tools.
A practical example
Your CLAUDE.md (committed to the repo) handles coding rules:
# Project: Meridian Health Platform
## Tech Stack
Next.js 15, TypeScript, Tailwind, Supabase, deployed on Vercel
## Key Commands
- Build: `npm run build`
- Test: `npm test` (Vitest, happy-dom)
## Rules
- Tests mandatory for every code change
- Bug fixes must include a reproducing test first
- Run npm test before committing
Your Unmarkdown™ knowledge base (accessible via MCP from any Claude interface) handles everything else: company overview, product roadmap, architecture decisions, meeting notes, and style guide.
In Claude Code, the CLAUDE.md handles conventions automatically. When you need broader context ("What did we decide about the API rate limits?"), Claude reads from the knowledge base. When you switch to claude.ai for non-coding work, the same knowledge base provides product context and style guidance without re-explaining anything.
Related reading
- How to Build a Persistent Knowledge Base Your AI Can Always Access
- Why Your AI Keeps Forgetting (And the Permanent Fix)
- Claude Projects vs ChatGPT Projects vs External Knowledge Bases
- Context Engineering for Everyone: A Non-Developer's Guide
- Obsidian vs Unmarkdown: When You Need Documents, Not Digital Gardens
- Claude Code + Unmarkdown: Publish Docs Without Leaving the Terminal
