The CLAUDE.md Standard: How Project Instructions Are Shaping AI Workflows

Every AI coding tool eventually asks the same question: "What kind of project is this?" You can answer it every single session -- repeating your tech stack, your coding conventions, your test commands -- or you can write it down once in a file the agent reads automatically.

That file, for Claude Code, is CLAUDE.md. And in 2026, it has become the blueprint for an entire category of project instruction files that are quietly reshaping how developers work with AI agents. Cursor has .cursorrules (now .mdc files). GitHub Copilot has .github/copilot-instructions.md. OpenAI Codex contributed AGENTS.md to the Linux Foundation. Every major AI coding tool now expects a markdown file telling it how to behave in your project.

This isn't just configuration. It's a new layer of developer communication -- one that sits between documentation (for humans) and configuration (for machines). Get it right, and your AI agent acts like a teammate who read the onboarding docs. Get it wrong, and you're correcting the same mistakes every session.

📋 What You'll Need

• An AI coding tool -- Claude Code, Cursor, GitHub Copilot, or any agent that supports project instruction files
• A real project -- instruction files are pointless without an actual codebase to apply them to
• 10-15 minutes -- writing a good instruction file takes less time than you think (the hard part is knowing what to leave out)
• A text editor -- these are just markdown files; no special tooling required

🗺️ The Landscape: Every AI Tool Has Its Own File

Before we go deep on CLAUDE.md specifically, let's map the territory. In 2026, every major AI coding agent reads project-level instructions from a markdown file. The names differ, the formats are nearly identical, and the concept is converging fast.

Notice the pattern? They're all markdown. The tooling around them differs -- Cursor's .mdc format adds YAML frontmatter for glob patterns and auto-attach rules, CLAUDE.md supports a three-level hierarchy -- but the core idea is identical: give the agent persistent context it can't infer from source code alone.

The Convergence: AGENTS.md

In August 2025, OpenAI released AGENTS.md as an open-source, tool-agnostic standard for project instructions. In December 2025, it was donated to the Agentic AI Foundation under the Linux Foundation, with Anthropic, Block, Google, Microsoft, and AWS as founding members.

AGENTS.md has been adopted by over 60,000 open-source projects. Its value proposition is simple: write one instruction file that works across Codex, Cursor, Copilot, Claude Code, Gemini CLI, Devin, and others. Whether it actually replaces tool-specific files remains to be seen -- most teams still maintain a CLAUDE.md alongside AGENTS.md because each tool has features the universal format can't express.

📐 Anatomy of a CLAUDE.md File

A CLAUDE.md file is plain markdown. No special syntax, no schema to validate against, no build step. Claude reads it at the start of every session and treats its contents as persistent context.

Here's what a well-structured one looks like for a real Django project:

# CLAUDE.md

## Commands
- Dev server: `python manage.py runserver --settings=myapp.settings.local_dev`
- Run tests: `pytest`
- Lint: `flake8`
- Type check: `mypy src/`
- Deploy: `./deploy_prod.sh` (never run locally)

## Architecture
- Settings split: common.py -> local_dev.py / local.py / prod.py
- Article content supports HTML and Markdown (article_content_format field)
- New articles use markdown format with article-details-base-page.html template
- UUID primary keys on all models

## Code Style
- Function-based views, not class-based
- Type hints required on all public functions
- All API endpoints need token authentication
- Use django-environ for env vars -- never hardcode secrets

## Git
- Branch naming: feature/short-description or fix/short-description
- Always run pytest before committing
- Never commit .env files or API keys
- Squash merge to main

## Important
- NEVER modify migration files manually
- Settings files in fundesk/settings/ inherit from common.py
- The prod.py settings are deployed on Railway -- test locally with local_dev.py

That's 30 lines. It takes Claude about two seconds to read. And it prevents the five most common mistakes Claude would otherwise make in this project.

The Golden Rule

For every line in your CLAUDE.md, ask: "Would removing this cause Claude to make a mistake?" If the answer is no, cut it.

Claude already knows Python conventions. It already knows what Django is. It can read your requirements.txt and figure out your dependencies. What it can't figure out by reading source code is that your team uses function-based views instead of class-based, or that deploy_prod.sh should never run locally, or that migration files are off-limits.

What NOT to Include

• Things Claude can infer by reading your code ("This is a Django project using PostgreSQL")
• Standard language conventions Claude already knows ("Use meaningful variable names")
• Entire API documentation (link to it instead with @docs/api-reference.md)
• Your life story, project mission statement, or company values
• Anything over 150 lines -- Claude's official guidance is to keep it under 300 lines, but shorter is always better

🏗️ The Three-Level Hierarchy

CLAUDE.md isn't a single file. It's a hierarchy, and understanding how the levels interact is what separates a basic setup from a genuinely effective one.

Level 1: Global (~/.claude/CLAUDE.md)

This file lives in your home directory and applies to every project you open with Claude Code. Use it for personal preferences that transcend any single codebase:

# Personal Preferences
- I prefer concise commit messages (50 char subject, no body unless complex)
- Always explain trade-offs before implementing a solution
- When writing tests, include edge cases for empty inputs and null values
- Use American English spelling in comments and docs

Level 2: Project Root (./CLAUDE.md)

This is the most important file. It lives in your project root, gets checked into git, and your entire team benefits. Every section in the anatomy example above belongs here.

There's also CLAUDE.local.md -- automatically gitignored -- for personal project-level preferences that shouldn't be shared with the team. Maybe you like verbose git messages. Maybe your teammate prefers terse ones. Local files handle that.

Level 3: Subdirectory (./src/api/CLAUDE.md)

For monorepos or projects with distinct subsystems, you can place CLAUDE.md files in subdirectories. These are loaded on demand -- Claude only reads them when it's actively working in that directory.

my-monorepo/
├── CLAUDE.md                    # Root: shared conventions
├── packages/
│   ├── frontend/
│   │   └── CLAUDE.md            # React conventions, component patterns
│   ├── backend/
│   │   └── CLAUDE.md            # API conventions, database patterns
│   └── shared/
│       └── CLAUDE.md            # Shared types, utility function rules

Level 3.5: The Rules Folder (.claude/rules/)

All .md files in .claude/rules/ are automatically loaded with the same priority as your root CLAUDE.md. This is useful for organizing instructions by concern:

.claude/
├── rules/
│   ├── testing.md               # Test conventions
│   ├── security.md              # Security requirements
│   ├── frontend.md              # Frontend patterns
│   └── api-design.md            # API conventions

Precedence

More specific instructions override broader ones. If your root CLAUDE.md says "use tabs" but packages/frontend/CLAUDE.md says "use 2-space indentation," the frontend rule wins when Claude is working in that directory.

┌─────────────────────────────┐
│  ~/.claude/CLAUDE.md        │  ← Lowest priority (personal global)
├─────────────────────────────┤
│  ./CLAUDE.md                │  ← Project-wide (checked into git)
├─────────────────────────────┤
│  .claude/rules/*.md         │  ← Same priority as root CLAUDE.md
├─────────────────────────────┤
│  ./src/api/CLAUDE.md        │  ← Highest priority (loaded on demand)
├─────────────────────────────┤
│  ./CLAUDE.local.md          │  ← Personal overrides (gitignored)
└─────────────────────────────┘

⚔️ CLAUDE.md vs .cursorrules vs copilot-instructions.md vs AGENTS.md

Each tool's instruction file serves the same purpose but makes different trade-offs. Here's a side-by-side breakdown:

Cursor's Approach: Glob-Based Rules

Cursor took a fundamentally different path. Instead of a single instruction file with a hierarchy, Cursor uses individual .mdc files in .cursor/rules/ -- each with frontmatter that specifies when it applies:

---
description: React component guidelines
globs: ["src/components/**/*.tsx"]
alwaysApply: false
---

- Use functional components with hooks
- Props interface must be exported
- Each component gets its own directory with index.tsx and styles.module.css

This is more granular than CLAUDE.md's directory-level hierarchy. You can have a rule that only applies to *.test.ts files, or only to files in src/api/v2/. The trade-off is more files to maintain.

Copilot's Approach: Simple and Centralized

GitHub Copilot keeps it simple with a single .github/copilot-instructions.md file. No hierarchy, no conditional loading, no file references. What you write is what Copilot sees, every time. This works well for small-to-medium projects but gets unwieldy for large monorepos.

AGENTS.md: The Universal Standard

AGENTS.md aims to be the instruction file you write once and have every tool read. In practice, most teams use it alongside tool-specific files because each tool has features (like CLAUDE.md's @file references or Cursor's glob-based rules) that AGENTS.md can't express.

A practical multi-tool setup looks like this:

my-project/
├── AGENTS.md                        # Universal: architecture, commands, conventions
├── CLAUDE.md                        # Claude-specific: @file refs, subdirectory rules
├── .cursor/rules/
│   ├── react-components.mdc         # Cursor-specific: glob-based component rules
│   └── api-endpoints.mdc            # Cursor-specific: API pattern rules
└── .github/
    └── copilot-instructions.md      # Copilot-specific: coding style

✍️ Writing Effective Project Instructions: Patterns That Work

After six months of iterating on CLAUDE.md files across multiple projects, a few patterns consistently produce better results.

Pattern 1: Commands First

Put your build, test, lint, and deploy commands at the very top. These are the most frequently referenced instructions, and Claude reaches for them constantly:

## Commands
- Dev: `npm run dev`
- Test: `npm test`
- Test single: `npm test -- --grep "test name"`
- Lint: `npx eslint . --fix`
- Build: `npm run build`
- Deploy: `./scripts/deploy.sh` (NEVER run locally)

Pattern 2: Anti-Patterns Over Patterns

Telling Claude what NOT to do is often more valuable than telling it what to do. Claude already writes reasonable code. What it doesn't know is your project's specific landmines:

## Important -- Do NOT
- Never modify files in /migrations/ -- always use `python manage.py makemigrations`
- Never import from @/internal/ in public API modules
- Never use console.log in production code -- use the logger utility
- Never commit changes to .env.example without team discussion
- Never use any in TypeScript -- use unknown and narrow the type

Pattern 3: Progressive Disclosure

Don't dump everything into CLAUDE.md. Point to detailed documentation and let Claude load it when needed:

## Architecture
High-level: React frontend, Express API, PostgreSQL.
Details: @docs/architecture.md

## API Design
REST conventions: @docs/api-style-guide.md
Auth flow: @docs/authentication.md

## Deployment
Pipeline overview: @docs/deployment.md

This keeps your CLAUDE.md under 60 lines while giving Claude access to thousands of lines of documentation on demand.

Pattern 4: The Quick-Start Test

A well-written CLAUDE.md should pass this test: if a new developer (or a new Claude session) reads only this file, can they run the project, make a change, test it, and commit it without asking questions?

If yes, your instruction file is doing its job.

Pattern 5: Version and Date Awareness

Include versioning context that Claude can't reliably infer:

## Stack Versions
- Node 22 LTS (not 23 -- breaking changes in streams API)
- React 19 with Server Components (NOT React 18 patterns)
- TypeScript 5.7 strict mode
- PostgreSQL 16

This prevents Claude from generating code patterns from older versions that look correct but are subtly wrong in your environment.

🚀 Getting Started: The /init Command

If you're staring at a blank file wondering what to write, Claude Code can help. The /init command analyzes your codebase and generates a starter CLAUDE.md:

cd your-project
claude
> /init

Claude will scan your project structure, detect your build system, test framework, and code patterns, then generate a CLAUDE.md tailored to what it finds.

Think of /init as a starting point, not a finished product. It captures the obvious patterns but misses the nuances only your team knows. Review the output, add your project-specific gotchas, remove anything self-evident, and iterate over time.

A Practical Iteration Workflow

1. Start with /init to generate the baseline
2. Use Claude for a week and notice where it makes mistakes
3. Add instructions that prevent those specific mistakes
4. Remove instructions that Claude follows without being told
5. Check it into git so your team benefits
6. Review quarterly -- remove stale rules, add new patterns

The best CLAUDE.md files aren't written in one sitting. They evolve with your project.

🔮 What's Next

Project instruction files are still a young convention, and they're evolving fast. Here's where to go from here:

• Set up a CLAUDE.md for your main project using the patterns in this article -- start with commands and anti-patterns, iterate from there
• Explore Claude Code hooks to enforce rules deterministically rather than relying on CLAUDE.md instructions alone (see our Claude Code Workflow Guide)
• Compare instruction file approaches across tools if your team uses multiple AI agents -- our AI Coding Agents Compared breaks down the full landscape
• Look into AGENTS.md as a universal standard if you want a single instruction file that works across tools
• Read Anthropic's official CLAUDE.md guide for the latest best practices as the format continues to evolve

The bigger shift here isn't about any single file format. It's that communicating with AI agents is becoming a core development skill -- right alongside writing code, reviewing PRs, and debugging production issues. The teams that figure out how to encode their knowledge into these files effectively will move faster than teams that don't. That gap is already visible in 2026, and it's only going to widen.

Want to understand the career implications of AI-assisted development? Read The Rise of the AI Engineer for a deep dive into how these tools are reshaping engineering roles. Or check out GitHub Copilot Agent Mode Guide for the Copilot side of the project instructions story.