agents.md vs CLAUDE.md

They're the same thing. Well, almost. CLAUDE.md was the original filename Anthropic used for Claude Code's project-level instructions. agents.md is the newer, agent-agnostic name that works across different AI coding tools: Claude Code, Cursor, Windsurf, and others.

If you're only using Claude Code, either works. If you use multiple AI coding tools, agents.md is the better bet because it's becoming the shared standard.

What goes in it

Everything your AI agent needs to know for every session. Not task-specific stuff (that's for skill files), but the baseline rules that always apply.

A good agents.md covers:

• •Coding style. Tabs or spaces. Semicolons or not. Functional vs class components. The stuff that's consistent across your whole project.
• •Commit format. "Use conventional commits: feat:, fix:, chore:" or whatever your team agreed on.
• •Testing rules. "Always write tests before implementing." "Use vitest, not jest."
• •Architecture decisions. "API routes go in app/api/." "Database access only through the repository layer."
• •Things to avoid. "Don't use any. Don't use console.log for debugging — use the logger."

What stays out of it

Task-specific workflows. If it's only relevant when you're doing a particular thing (writing migrations, debugging memory leaks, adding new API endpoints), it belongs in a skill file.

Why? Because agents.md is read every session. Every token in it costs money and adds latency. A 500-line agents.md with instructions for 20 different tasks means Claude Code is burning context on stuff that isn't relevant to what you're doing right now.

Can you have both agents.md and CLAUDE.md?

Technically yes. Claude Code will read both. But you probably shouldn't. Pick one name and keep everything there. Two files with overlapping instructions is a maintenance headache and can confuse the agent when instructions conflict.

A real example

# Project: MyApp

## Stack
- Next.js 16 with App Router
- TypeScript (strict mode)
- Tailwind CSS for styling
- MongoDB with Mongoose

## Coding rules
- Use functional components only
- No `any` types — use `unknown` if needed
- Prefer named exports over default exports
- All async operations must have error handling

## Commits
- Format: type(scope): description
- Types: feat, fix, refactor, docs, test, chore
- Keep subject under 72 characters

## Testing
- Use vitest + testing-library
- Write tests before implementing (TDD)
- Test file goes next to source: foo.ts → foo.test.ts

That's about 20 lines. Enough to cover the essentials. Your project might need more or less, but most projects need fewer rules than people think.