Claude Code & Markdown Files

How CLAUDE.md gives AI coding agents project context

The Control File for AI Coding

Claude Code is Anthropic’s AI coding agent. It reads your code, writes code, runs commands, and makes changes across your project. But it needs context to work effectively — what to build, how your project works, what conventions to follow.

That context lives in CLAUDE.md — a Markdown file in your project root. Claude Code reads it automatically every time it starts a session.

What Goes in CLAUDE.md

A good CLAUDE.md answers the questions an AI agent would ask before writing code:

CLAUDE.md # Project Instructions ## Build & Test - `npm run dev` — start development server - `npm test` — run tests - `npm run lint` — check formatting ## Architecture - Next.js app router in `app/` - API routes in `app/api/` - Shared components in `components/` - Database queries in `lib/db/` ## Conventions - Use TypeScript strict mode - Prefer server components by default - Use Tailwind CSS, no inline styles - Test files next to source: `foo.test.ts` ## Constraints - Do not modify `lib/auth/` without review - Never commit .env files - Keep bundle size under 200KB

Why Markdown?

CLAUDE.md is Markdown because:

  • Human-readable — developers can read and edit it without special tools
  • Machine-parseable — headings, lists, and code blocks are structured and unambiguous
  • Versioned with Git — changes show up in pull requests as clean diffs
  • Renders on GitHub — team members can read it formatted in the repo
  • Token-efficient — uses fewer tokens than JSON or XML for the same information

See Why AI Tools Use Markdown for the deeper reasons behind this choice.

File Hierarchy

Claude Code supports CLAUDE.md files at multiple levels:

  • Project root (./CLAUDE.md) — global project instructions, always loaded
  • Subdirectories (./app/CLAUDE.md) — directory-specific context, loaded when working in that directory
  • User-level (~/.claude/CLAUDE.md) — personal preferences across all projects

Instructions are merged: project root + subdirectory + user-level. More specific files override more general ones.

Writing Effective Instructions

  • Be concise — Claude reads the entire file into context. Every word counts against the context window.
  • Use commands, not descriptions — “Run npm test before committing” is better than “we use Jest for testing”
  • State constraints clearly — “Do not modify the auth module” is unambiguous
  • Link to docs — reference other files (see docs/api.md) instead of duplicating content
  • Update when things change — stale instructions cause wrong behavior

CLAUDE.md vs AGENTS.md

CLAUDE.md is specific to Claude Code. It uses Claude-specific features like memory, hooks, and custom slash commands.

AGENTS.md is a broader convention — any AI coding agent (Copilot, Cursor, Windsurf) can read it. It contains universal instructions: project structure, conventions, and constraints.

Many projects use both: AGENTS.md for universal instructions and CLAUDE.md for Claude-specific settings. Claude Code reads both files.

Other Markdown Files Claude Code Uses

  • README.md — project overview, always read for context
  • CONTRIBUTING.md — contribution guidelines and PR conventions
  • CHANGELOG.md — version history, used when making releases
  • docs/*.md — documentation files, read on demand

The entire AI coding workflow — from context to output — runs on Markdown.

Related Guides

View CLAUDE.md with MDViewer

MDViewer renders CLAUDE.md with full formatting — headings, code blocks, and links. See your AI instructions the way Claude Code sees them.

Download MDViewer

Requires macOS 13.0 or later. Intel and Apple Silicon.