The CLAUDE.md & AGENTS.md Guide

AI coding agents are stateless. They know nothing about your codebase at the start of each session. CLAUDE.md and AGENTS.md are how you onboard them — a README for machines.

Two Files, Same Purpose

File	Used By	Notes
CLAUDE.md	Claude Code	Anthropic's proprietary format
AGENTS.md	40+ tools	Open standard under Linux Foundation

AGENTS.md emerged in 2025 as the open alternative. It's now used by 60,000+ open-source projects and supported by Copilot, Codex, Cursor, Gemini CLI, Zed, and more.

The Numbers

150-200

Max instructions LLMs reliably follow

~50

Instructions already in Claude Code's system prompt

<300

Recommended max lines in your file

The Hidden Problem

Claude often ignores your CLAUDE.md

Claude Code injects a hidden system reminder: "this context may or may not be relevant to your tasks. You should not respond to this context unless it is highly relevant." The more irrelevant instructions you add, the more likely Claude ignores the whole file.

The Core Principle

Your instructions file should answer three questions:

WHAT — Tech stack, project structure, where things live
WHY — Purpose of the project and its parts
HOW — Commands to build, test, lint, deploy

Six Areas to Cover

Analysis of 2,500+ repositories shows top-tier agent files cover:

Commands

Testing

Project Structure

Code Style

Git Workflow

Boundaries

Best Practices

Less is More

Include only universally applicable instructions. HumanLayer's CLAUDE.md is under 60 lines.

Commands Early

Put npm test, npm run build, pytest -v at the top. Include flags, not just tool names.

Code Over Words

One real code snippet showing your style beats three paragraphs describing it.

Be Specific

"React 18 with TypeScript, Vite, and Tailwind CSS" not "React project." Include versions.

Define Boundaries

Tell agents what to never touch: secrets, vendor directories, production configs.

Progressive Disclosure

Keep detailed docs in separate files. Reference them. Let agents read only what they need.

Progressive Disclosure Pattern

Don't cram everything into one file. Create a docs folder:

agent_docs/
  ├── building_the_project.md
  ├── running_tests.md
  ├── code_conventions.md
  ├── service_architecture.md
  ├── database_schema.md
  └── deployment.md

In your CLAUDE.md/AGENTS.md, list these files with brief descriptions. Tell the agent to read relevant ones before starting work.

Prefer pointers to copies. Don't paste code snippets — they become stale. Use file:line references to point to authoritative context.

Monorepo Support

AGENTS.md supports hierarchy. Place files in subdirectories — the closest one to the edited file takes precedence. OpenAI's main repo has 88 AGENTS.md files.

repo/
  ├── AGENTS.md           # root instructions
  ├── packages/
  │   ├── api/
  │   │   └── AGENTS.md   # API-specific
  │   └── web/
  │       └── AGENTS.md   # web-specific

What NOT to Do

Don't use agents as linters. Use actual linters and formatters — they're faster and cheaper. Set up a pre-commit hook instead.
Don't auto-generate your file. /init creates bloated files. Craft it carefully — it's your highest leverage point.
Don't include code style paragraphs. LLMs are in-context learners. If your code follows patterns, agents will pick them up from examples.
Don't add task-specific hotfixes. Instructions that only apply sometimes will cause the whole file to be ignored.

AGENTS.md Tool Support

40+ Platforms

GitHub Copilot OpenAI Codex Cursor Gemini CLI Zed Aider Warp Devin Windsurf Factory Amp Jules RooCode Phoenix

TL;DR

The Rules

Keep it under 300 lines (ideally under 60)
Cover: commands, testing, structure, style, git, boundaries
Put executable commands at the top with flags
Use code examples, not explanations
Be specific about your stack and versions
Use progressive disclosure for detailed docs
Use linters and formatters, not LLMs
Don't auto-generate — craft it manually

Sources

HumanLayer: Writing a good CLAUDE.md GitHub Blog: How to write a great agents.md AGENTS.md Official Specification