AGENTS.md: How I Make My Repos AI-Agent Friendly (Claude Code Now Reads It Too)

Before we dive in, why not take a quick peek at my portfolio: https://priyalraj.com

📋 TL;DR: What You’ll Learn Here

• What AGENTS.md is & why 60k+ open-source projects already use it.

• What changed on September 18, 2026, when Claude Code v2.1.277 started reading it.

• The CLAUDE.md gotcha that makes Claude Code silently ignore your AGENTS.md.

• A copy-paste AGENTS.md template for a Next.js project, plus the exact setup I use in my own repos.

🤖 The Problem: Every AI Tool Wanted Its Own File

If you use more than one AI coding tool, you know this pain.

• Claude Code wanted CLAUDE.md.

• Cursor wanted .cursorrules, then .cursor/rules/.

• Copilot wanted .github/copilot-instructions.md.

• Gemini CLI wanted GEMINI.md.

Same instructions, copy-pasted four times, & slowly drifting apart. You update the test command in one file, forget the other three, & suddenly one agent keeps running npm test in a Bun project.

📄 What Is AGENTS.md?

AGENTS.md is an open format that’s basically a README for AI agents.

Your README.md is for humans: what the project is, how to get started. AGENTS.md is for agents: the exact commands, conventions & rules they need to work on your code without breaking stuff.

Some quick facts:

• It’s plain markdown. No required fields, no special syntax.

• It came out of a collaboration between OpenAI Codex, Amp, Google’s Jules, Cursor & Factory.

• It’s now stewarded by the Agentic AI Foundation under the Linux Foundation.

• 60,000+ open-source projects already use it.

• It’s supported by tools like Codex, Jules, Gemini CLI, GitHub Copilot, Cursor, Windsurf, JetBrains Junie, Aider, goose, opencode, Zed, Warp & VS Code.

One file, every agent. That’s the whole idea.

🎉 What Changed: Claude Code Joined the Party

For a long time, Claude Code was the odd one out. It only read CLAUDE.md. The GitHub issue asking for AGENTS.md support collected around 3,200 upvotes, which tells you how many of us were tired of maintaining two files.

On September 18, 2026, Claude Code v2.1.277 finally shipped it. If your project has no CLAUDE.md, Claude Code now reads AGENTS.md instead. The Hacker News thread on it hit 741 points, so yeah, people cared.

When it kicks in, you’ll see a line like this at session start:

no CLAUDE.md found; AGENTS.md loaded: /home/you/repo/AGENTS.md

⚠️ The Gotcha: It’s a Fallback, Not a Merge

This tripped up a lot of people, so read this twice.

Claude Code reads AGENTS.md only when there’s no CLAUDE.md. If any of these exist in your working directory or any folder above it, AGENTS.md is skipped completely:

• CLAUDE.md

• .claude/CLAUDE.md

• CLAUDE.local.md

That last one is sneaky. Say your team uses AGENTS.md, & you add a personal CLAUDE.local.md for your own notes. Boom, Claude Code now ignores the team’s AGENTS.md for you.

What doesn’t block it: your global ~/.claude/CLAUDE.md, org-managed instructions, & .claude/rules/ files. Those load alongside AGENTS.md.

Here’s a quick summary from the official docs:

🛠️ Want both files read?

Open /config in Claude Code & change Project instructions to one of these:

• claude-md-or-agents-md: the default fallback behaviour.

• claude-md-and-agents-md: reads both, CLAUDE.md first, AGENTS.md after.

• claude-md: CLAUDE.md only, ignores AGENTS.md.

🔗 My Setup: One File, Symlinked

In my own repos (including this portfolio), I keep one source of truth:

# write everything in AGENTS.md, then point CLAUDE.md at it
ln -s AGENTS.md CLAUDE.md

Now every tool reads the same content, & I only ever edit AGENTS.md. Claude Code sees a CLAUDE.md, other agents see an AGENTS.md, & they’re literally the same file.

If symlinks are a pain on your setup (hello, Windows), use an import instead. Create a CLAUDE.md with just this line:

@AGENTS.md

Claude Code expands @path imports at launch, so it pulls in AGENTS.md automatically. You can still add Claude-specific extras below that line.

✍️ What Should Go in AGENTS.md?

Rule of thumb: write what a new senior dev would need on day one, but would never guess. Don’t explain what React is. Do explain that you use Bun, not npm.

Here’s a template I’d use for a Next.js project:

# AGENTS.md

## Setup
- Runtime: Bun (never use npm or yarn)
- Install: bun install
- Dev: bun run dev (port 3000)

## Checks (run before saying a task is done)
- Type check: bun run check
- Lint: bun run lint
- Tests: bun run test

## Code style
- TypeScript strict mode, no `any`
- Server-only code lives in src/lib/server/, never import it from client components
- Use the shared fetch wrapper in src/lib/api.ts, not raw fetch

## Rules
- Never commit .env files or hardcode API keys
- After any DB mutation in an API route, call revalidatePath()
- Do not edit generated files in src/generated/

## PRs
- Title format: feat|fix|chore: short description
- Keep PRs small, one concern per PR

💡 Tips that actually make a difference

• Commands first. The most useful thing for an agent is knowing how to verify its own work. Lint, type-check & test commands are gold.

• Be specific with “never”. “Don’t touch public/style.css” beats “be careful with styles”.

• Keep it short. Every line gets loaded into the agent’s context on every session. Long files eat context & agents follow them less reliably.

• Monorepos: drop an AGENTS.md inside each package. Per the spec, the closest AGENTS.md to the edited file wins.

• Treat it like code. When an agent makes the same mistake twice, add a line. Review it in PRs like anything else.

🔒 One Security Note

AGENTS.md is instructions that AI agents follow. So if you clone a random repo & run an agent on it, that repo’s AGENTS.md is effectively giving orders to your agent.

Before running any agent with broad permissions on someone else’s code, open AGENTS.md (and CLAUDE.md) & read it first. It takes 30 seconds.

Final Thoughts

AGENTS.md is one of those tiny things that pays off every single day. One file, every agent, no drift.

If you already have a CLAUDE.md, rename it to AGENTS.md & symlink it back. Takes two commands, & now Cursor, Codex, Copilot & Claude Code all read the same rules.

If you enjoyed this article, please make sure to follow me on Twitter.