AGENTS.md, CLAUDE.md & Cursor Rules: How to Give Your AI Coding Agent Project Context

AGENTS.md is a plain Markdown file in your project's root that tells AI coding agents how your project works: the stack, the commands, the conventions and the rules. Agents read it automatically at the start of every task, so you don't have to repeat yourself in every prompt. It's an open standard↗ (opens in a new tab) read by OpenAI Codex, Cursor, GitHub Copilot, Google's agents, Devin and many others, and Claude Code reads it when there's no CLAUDE.md.

A good context file is the cheapest, highest-impact upgrade you can make to your vibe coding workflow.

Why context files matter

AI models are trained on millions of projects, so without guidance they write code the way the average project does, often using older library versions. That leads to familiar problems:

• Using npm when your project uses pnpm
• Writing Next.js middleware.ts when Next.js 16 uses proxy.ts
• Creating a new button component instead of using yours
• Forgetting to run tests, or running the wrong command
• Repeating the same mistake you corrected yesterday

A context file fixes all of these once.

The different context files (and which tools read them)

Recommendation: put your real instructions in AGENTS.md so every tool benefits. If you use Claude Code, you can either rely on its AGENTS.md fallback or create a CLAUDE.md containing @AGENTS.md plus any Claude-specific notes. Use tool-specific files only for tool-specific features.

AGENTS.md files can also be nested: an AGENTS.md inside packages/api/ applies to that folder, and the closest file wins. That's handy for monorepos.

What to put in AGENTS.md

Keep it short and specific. The best context files are under about 150 lines and contain things the agent can't easily figure out by reading the code.

1. Project overview: one or two sentences on what it is and who it's for.
2. Stack and versions: especially anything newer than the model's training data.
3. Commands: install, dev, build, test, lint, typecheck. Exact commands.
4. Project structure: where things live, briefly.
5. Conventions: naming, styling approach, patterns to follow (with example files).
6. Rules and boundaries: what never to do.
7. Definition of done: what the agent must check before saying it's finished.

A copy-paste AGENTS.md template

# AGENTS.md

## Project
Habit tracker web app for individuals. Next.js 16 (App Router), TypeScript,
Tailwind CSS v4, Supabase (Postgres + Auth). Deployed on Vercel.

## Commands
- Install: `pnpm install`
- Dev server: `pnpm dev` (http://localhost:3000)
- Tests: `pnpm test` (Vitest), e2e: `pnpm test:e2e` (Playwright)
- Lint + typecheck: `pnpm lint && pnpm typecheck`

## Structure
- `app/`: routes. `(marketing)` = public pages, `(app)` = logged-in pages
- `components/ui/`: shared UI primitives. Reuse these; don't create duplicates
- `lib/db/`: all database access goes through functions here
- `supabase/migrations/`: SQL migrations (never edit old ones; add new ones)

## Conventions
- Server Components by default; add 'use client' only for interactivity
- Validate all input with zod (see `lib/validation.ts`)
- Follow the pattern in `app/(app)/habits/page.tsx` for new pages
- Next.js 16: use `proxy.ts` (not middleware.ts) and always `await params`

## Rules
- Never commit secrets or edit `.env*` files
- Every table needs Row Level Security policies
- Check the user owns a record before reading or changing it
- Don't add dependencies without asking
- Don't modify existing migrations

## Definition of done
- `pnpm lint && pnpm typecheck && pnpm test` all pass
- New behavior has tests
- Summarize what changed and anything I should manually check

Tips for writing great context files

• Start with your agent's help. Run /init in Claude Code or ask any agent "analyze this repo and draft an AGENTS.md", then cut it down and correct it.
• Add rules when mistakes repeat. Every time you correct the agent twice for the same thing, add a line.
• Be concrete. "Use the Button from components/ui/button.tsx" beats "use our components".
• Explain why for important rules. "Every table needs RLS because the anon key is public" helps the agent generalize.
• Don't paste whole docs. Link to them or use a docs MCP server instead. Long files dilute attention.
• Keep it current. An outdated context file is worse than none. Review it whenever your stack changes.
• Commit it to Git so your whole team, and every agent, shares it.

Framework-generated context: the Next.js example

Frameworks are starting to write agent context for you. Since Next.js 16.2/16.3, running next dev maintains a block in AGENTS.md that points agents to the version-matched Next.js docs bundled in node_modules. Commit that block and add your own sections below it. Read more in our Next.js getting started guide and the official Next.js AI agents guide↗ (opens in a new tab).

Beyond context files: Skills and specs

• Skills↗ (opens in a new tab) are reusable packages of instructions (a SKILL.md plus optional scripts) that teach an agent how to do a specific kind of task, like "write a database migration" or "release a new version". Context files say what your project is; skills say how to do a job.
• Specs describe a specific feature before it's built. See spec-driven development.

Frequently asked questions

Do I need both AGENTS.md and CLAUDE.md?

No. Claude Code reads AGENTS.md when there's no CLAUDE.md. Use a CLAUDE.md only if you want Claude-specific features like imports or personal scopes, and have it reference AGENTS.md to avoid duplication.

Where does AGENTS.md go?

In the root of your repository. You can add more in subfolders for monorepos; the nearest one to the files being edited takes precedence.

Does AGENTS.md work with AI app builders?

Some app builders support project-level instructions in their own settings. If you sync to GitHub and continue with an agent, AGENTS.md takes over.

Can a context file make my agent less effective?

Yes, if it's too long, contradictory or outdated. Keep it short, accurate and focused on things the agent can't infer from the code.