Claude Code now reads AGENTS.md if there is no Claude.md

Claude Code Now Reads AGENTS.md When Claude.md Is Absent

If you’ve been using Claude Code with a Claude.md file to set project context, system prompts, or coding conventions, there’s a quiet but useful behavior change worth knowing: Claude Code now checks for an AGENTS.md file when no Claude.md exists in the project root.

This isn’t just a rename—it’s a meaningful distinction in how Anthropic positions these files, and understanding the difference changes how you should structure project instructions.

The Simple Rule

Claude Code’s file resolution logic now works like this:

Project has Claude.md?     → Read Claude.md
No Claude.md, but AGENTS.md exists?  → Read AGENTS.md
Neither exists?            → No project instructions loaded

That’s it. The priority is explicit, and the behavior is predictable. If you want Claude Code to read project-level instructions but prefer AGENTS.md as your filename (or vice versa), you now have that flexibility.

Why AGENTS.md Exists

Claude.md was designed as a single, authoritative configuration file for Claude Code. You drop it in your repo, and Claude Code picks it up automatically.

AGENTS.md leans into a different mental model. In many developer workflows, especially those involving multi-agent systems or complex pipelines, you might have instructions that are specifically meant for agentic interactions—long-running tasks, tool use, multi-step reasoning—rather than general code review or editing.

The naming reflects that intent: AGENTS.md signals “here’s how to behave when operating autonomously,” while Claude.md reads more like “here’s what this project is.”

In practice, the content can be identical. But the naming convention opens up some interesting patterns.

Concrete Setup Examples

Minimal AGENTS.md

If you want Claude Code to understand your project but don’t have (or want) a Claude.md:

# Project: Order Processing Service
## Tech Stack
- Node.js 20
- PostgreSQL 15
- Prisma ORM

## Key Conventions
- Use TypeScript strict mode
- Prefer async/await over raw promises
- Never commit directly to main

## API Behavior
- All endpoints return { data, error, meta } structure
- Errors are logged before throwing

Claude Code reads this on every invocation in this directory.

Distinguishing File Purposes

You could use both files for different purposes:

Claude.md (general project context):

# Order Processing Service

## Overview
Handles order creation, fulfillment, and returns for our e-commerce platform.

## Codebase Structure
/src/api - Express routes
/src/services - Business logic
/src/models - Prisma schema
/tests - Jest integration tests

AGENTS.md (agentic behavior instructions):

# Agent Behavior Guidelines

## When Planning
- Always check /src/services before modifying routes
- Query the database schema before writing Prisma queries
- Run `npm test` before suggesting changes to business logic

## Tool Use Preferences
- Prefer `Edit` over `Bash` for small changes
- Use `Bash` for running tests, migrations, and npm scripts
- Never run destructive database commands without confirmation

## Long-Running Tasks
- Break tasks into steps and report progress
- Ask before modifying more than 5 files in one pass
- Summarize changes at the end of each session

Both files coexist. Claude Code reads both, with Claude.md providing context and AGENTS.md shaping how it operates.

Cross-Model Portability

If you’re working across Claude, GPT, and Gemini models—something common when routing requests through a single interface like AI Prime Tech—the AGENTS.md naming convention has a practical advantage. Many agent frameworks and tooling use AGENTS.md as a de facto standard, making your instructions more portable if you switch between providers or run multi-model pipelines.

# A project structure that works across different agent systems
/
├── AGENTS.md           # Universal agent instructions
├── CLAUDE.md           # Claude-specific additions (optional)
├── src/
│   └── ...
└── tests/
    └── ...

Trade-offs and Gotchas

Content Overlap

A common mistake is duplicating content across both files and then losing track of which one Claude Code is actually following. Pick one approach:

1. Single file: Use only Claude.md or only AGENTS.md for simplicity
2. Layered approach: Use Claude.md for static project facts, AGENTS.md for behavioral rules
3. Avoid duplication in layered setups—it creates maintenance burden

File Location

Both files must be in the project root (where you invoke Claude Code). Subdirectory placement doesn’t work. If you’re in a monorepo, each package that needs agent instructions needs its own file.

Token Budget

Aggressive AGENTS.md usage adds to your context. If you’re routing through APIs with token limits, keep these files focused. A 500-word AGENTS.md is fine; a 3000-word manifesto isn’t. Every word is context you pay for.

For teams using multiple models—Claude for planning, GPT-6 for code generation, Gemini for long-context reasoning—centralized agent instructions help maintain consistent behavior without replicating the same rules across model-specific config files.

Relating to API Development

When building with the Claude, GPT, or Gemini APIs directly (not through Claude Code), you handle this same problem manually: passing system prompts, project context, and behavioral instructions in the messages array.

The pattern looks like this in Python:

from anthropic import Anthropic

client = Anthropic()

system_prompt = open("AGENTS.md").read() if os.path.exists("AGENTS.md") else ""

messages = [
    {"role": "user", "content": "Refactor the order validation logic"}
]

response = client.messages.create(
    model="claude-opus-4",
    system=system_prompt,
    messages=messages,
    max_tokens=1024
)

Building AGENTS.md into your tooling—checking for it at startup, injecting it as the system prompt—gives your API integrations the same project awareness that Claude Code provides out of the box. If you’re managing costs across multiple model providers, platforms like AI Prime Tech offer consolidated access that lets you apply this same pattern uniformly.

Best Practices

Start simple. A 200-word AGENTS.md that captures your tech stack, coding conventions, and one or two key workflows is more valuable than a 2000-word document nobody maintains.

Version control your agent instructions. Treat AGENTS.md like code—commit it, review changes, enforce consistency. Stale agent instructions are worse than none.

Keep it specific, not exhaustive. “Use error objects with code, message, and context fields” beats “always write good error handling.”

Test the output. Run Claude Code on a familiar task and verify it’s respecting your instructions. If it misses something, add a specific example or counterexample.

Practical Takeaways

• Claude Code now reads AGENTS.md as a fallback when Claude.md is absent—use whichever naming fits your workflow
• Both files can coexist; Claude.md typically holds project context while AGENTS.md shapes agent behavior
• The AGENTS.md naming aligns with cross-model conventions, useful if you’re routing requests across Claude, GPT, and Gemini
• Keep token usage in mind: focused instructions beat lengthy manifestos
• Build the same file-checking pattern into your own API tooling for consistent project context across model calls

The underlying principle here is the same whether you’re using Claude Code or calling APIs directly: structured, well-scoped project instructions dramatically improve outcomes. The file format is secondary to the discipline of maintaining them.