← back to the archiveCover illustration for “AGENTS.md and CLAUDE.md: instructions for coding agents”
TERM7mo ago·Published · Updated ·by Andy Padia

AGENTS.md and CLAUDE.md: instructions for coding agents

In short: AGENTS.md and CLAUDE.md are project files that give coding agents your commands, conventions and rules at the start of every session.

AGENTS.md and CLAUDE.md are plain Markdown files in a repository that give AI coding agents standing instructions: build and test commands, coding conventions, folders to avoid and rules to follow. The agent reads them at the start of each session. AGENTS.md is the cross-tool format, used by over 60k open-source projects according to its site in November 2026; CLAUDE.md is Claude Code's own file.

AGENTS.md in plain words

The README is for humans joining the project. AGENTS.md is the onboarding note for the AI teammate: the house rules it would otherwise have to guess.

How it works

When a session starts, the agent loads the file into its context. Some tools also load nested files from subfolders and user-level files from your home directory; the AGENTS.md site says the nearest file in the directory tree takes precedence.

Claude Code's memory documentation, read in November 2026, says Claude Code reads CLAUDE.md at the start of every session and, from version 2.1.277, reads a repository's AGENTS.md when no CLAUDE.md is present. A CLAUDE.md can also import AGENTS.md. The same page suggests keeping each file under 200 lines, because longer files consume more context and reduce adherence.

Example

# AGENTS.md
## Commands
- Install: pnpm install
- Test: pnpm test (run before every commit)
- Lint: pnpm lint --fix

## Rules
- Never edit files in /generated.
- Use the existing logger in lib/log.ts, not console.log.
- Database changes need a migration in /migrations.

Where you'll meet it

  • Claude Code, which reads CLAUDE.md and falls back to AGENTS.md
  • OpenAI Codex, opencode, Cursor, Gemini CLI and other agents listed on the AGENTS.md site
  • Open-source repositories adding agent guidance next to CONTRIBUTING.md
  • Monorepos with per-package files

What it changes for you

For developers, it is a cheap fix for repeated mistakes: write the correction down once. For tech leads, it turns tribal knowledge into versioned, reviewable rules. For teams, it should be reviewed in pull requests like code, because a wrong rule is followed confidently every time.

AGENTS.md vs README

README explains the project to people. AGENTS.md gives operational instructions to agents: exact commands, hard rules, things not to touch.

Common mistake

My view: turning the file into a style guide essay. Agents follow short, testable rules ("run X before committing") far better than paragraphs of philosophy. Claude Code's documentation says the file is treated as context and is not enforced, so if a rule matters, also enforce it with a hook or a CI check.

Claude Code · Agent memory · Claude Code hooks · Agent skills · Context engineering

Keep the instruction file short and testable, and back any rule that matters with a hook or a CI check.

#field-guide#coding-agents#claude-code#developer-tools#conventions

Sources

  1. agents.md
  2. code.claude.com/docs/en/memory
← older drop
Small language model (SLM): compact AI for narrow jobs
newer drop →
Claude Code hooks: shell commands at agent lifecycle points

related drops

explore all 557 drops →
← back to the archiveday 175