agents.md for Claude Code

agents.md is a configuration file you put in your project root that tells Claude Code how to behave. Think of it as a job description for your AI coding agent. Every time Claude Code starts a session in your project, it reads this file first.

If you don't have one, Claude Code still works — it just doesn't know your project's conventions, testing setup, or preferred patterns. It'll make assumptions, and some of those assumptions will be wrong.

What goes in agents.md

Instructions that are true for every session. Not task-specific stuff — that goes in skill files. Think of the things you'd tell a new developer on their first day:

• •Coding standards and naming conventions
• •Testing framework and where tests live
• •Commit message format
• •Deployment steps and environments
• •Files that should never be modified
• •Project-specific architectural decisions

Example agents.md

# Project: E-commerce Platform

## Stack
- Next.js 16 (App Router), TypeScript, Tailwind CSS
- PostgreSQL via Prisma ORM
- Redis for caching, Bull for job queues
- Deployed on Vercel (staging) + AWS (production)

## Code Style
- Use TypeScript strict mode. No `any` types.
- Functional React components with hooks only.
- Named exports, no default exports.
- Use Zod for runtime validation on all API inputs.

## Testing
- Vitest for unit tests, Playwright for E2E
- Tests go in `__tests__/` next to the source file
- Write tests before implementation
- Minimum 80% coverage on new code

## Git
- Conventional commits: feat:, fix:, docs:, chore:
- Never commit directly to main
- Include ticket number in commit messages

## Architecture
- /app — pages and layouts (Next.js App Router)
- /lib — shared utilities and helpers
- /components — reusable UI components
- /services — business logic layer
- Never put business logic in page components

agents.md vs CLAUDE.md

They're the same thing. CLAUDE.md is Anthropic's default filename, agents.md is the community convention. Claude Code reads both. Pick one and stick with it — having both is redundant.

Some teams prefer agents.md because it's more descriptive. The file tells your AI agentwhat to do, so the name makes sense. Others use CLAUDE.md because that's what the docs say. Either works.

agents.md vs skill.md

This is the distinction that matters most:

The practical test: if an instruction applies to every file in every session, put it in agents.md. If it only matters when you're doing a specific task, put it in a skill file.

Keep it short

Every line in agents.md is read by Claude Code at the start of every message. A 300-line agents.md means 300 lines of context consumed per turn. That costs money and makes the agent slower.

Aim for 50-100 lines. If you're going over that, move task-specific instructions to skill files. Your agents.md should only contain rules that are universally true for the project.