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

Here’s a frustration every regular AI-coding user hits: you spend a session teaching the AI your project — “we use Tailwind, not CSS modules,” “tests go next to the file,” “never touch the migrations folder” — and then you start a fresh session the next morning and it’s forgotten all of it. AI coding tools have no memory between sessions. Every conversation starts from zero.

Context files are the fix. They’re plain markdown files that live in your repo and get loaded automatically at the start of every session, so your AI tool always knows your stack, your conventions, and your rules without you repeating yourself. Think of one as an onboarding document for a new teammate who happens to be an AI — and who re-reads it every single time before touching your code.

This guide covers the three files that matter, the new standard that’s unifying them, and how to write one that actually improves your output instead of cluttering it.

The three files (and who reads them)

Different tools look for different filenames, but they all do the same job:

• CLAUDE.md — Read by Claude Code. Dropped in your project root (or ~/.claude/CLAUDE.md for rules that apply to every project on your machine), it’s loaded automatically at the start of each session. See Anthropic’s Claude Code docs for the details.
• .cursorrules (or files under .cursor/rules/) — Read by Cursor. Same idea, Cursor’s filename. The Cursor docs cover the newer directory-based format.
• .github/copilot-instructions.md — Read by GitHub Copilot. Repository-level custom instructions that apply across the team.

If you only use one tool, you only need its file. The headache starts when your team uses several — and that’s exactly the problem the next section solves.

AGENTS.md: the standard that ends the mess

Maintaining a separate context file for every tool means copy-pasting the same rules into three or four files and keeping them in sync forever. In 2026 the major players — including Google, OpenAI, Sourcegraph, Cursor, and Factory — converged on a single open format to stop the duplication: AGENTS.md, now stewarded by the Agentic AI Foundation under the Linux Foundation.

It’s a simple, predictable place to put context that any compliant agent will read. Two properties make it genuinely useful:

• It’s hierarchical. An agent reads the closest AGENTS.md in the directory tree, and a file in a subdirectory overrides its parent. So you can put broad project rules at the root and module-specific rules deeper in — your frontend folder and your API folder can each have their own.
• It’s one source of truth. Instead of duplicating rules across CLAUDE.md, .cursorrules, and Copilot’s file, you maintain AGENTS.md and point the tool-specific files at it.

How to write one that actually works

This is where most context files go wrong. The instinct is to write everything down — a 1,000-line document covering every rule you can think of. That backfires. LLMs have limited instruction-following capacity, and a sprawling file gets mostly ignored. A focused 50-line file outperforms a bloated 500-line one, because the model can actually hold the short one in mind and act on it.

A few rules of thumb:

• Keep it short and high-signal. If a file is over ~500 lines, assume most of it isn’t being followed. Cut to what’s universally true for your project.
• Write rules, not essays. “Use pnpm, never npm” beats a paragraph explaining your package-manager philosophy.
• Only include what’s non-obvious or project-specific. The AI already knows how to write a React component. It doesn’t know that your project bans default exports or that the staging deploy runs on a different command. Spend your lines there.
• Keep it current. A context file that describes how the project worked six months ago is worse than none — it actively misleads. Update it when conventions change.

A good starter structure

Most effective files cover a handful of sections. You don’t need all of them — use what’s true for your project:

# Project: Acme Dashboard

## Tech stack
- Next.js (App Router) + TypeScript
- Tailwind for styling — no CSS modules
- Postgres via Drizzle ORM
- Tests with Vitest, colocated next to source files

## Conventions
- Named exports only, no default exports
- Keep components under 200 lines; split if larger
- Never edit files in /migrations by hand

## Commands
- Dev: `pnpm dev`
- Test: `pnpm test`
- Never run the deploy command — that's CI's job

## Out of bounds
- Don't touch /legacy — it's being deprecated
- Don't add new dependencies without flagging it first

Short, scannable, and every line earns its place. That’s the whole art.

Context files vs skills

If you use Claude Code, it’s worth knowing where context files end and skills begin, because they solve different problems:

• Context files (CLAUDE.md / AGENTS.md) are always-on background knowledge — your stack, conventions, and rules, loaded every session.
• Skills are on-demand workflows — a /commit or /deploy command you invoke when you want a specific multi-step task run.

They work together. Put standing rules in your context file; put repeatable actions in skills. Trying to cram a workflow into a context file (or project conventions into a skill) is the most common way people make both less effective.

What to do next

A context file is one half of getting good output from AI; the other half is how you phrase each request. The two compound — a clear file plus a clear prompt is the difference between AI that fits your project and AI that fights it. Sharpen the second half with our guide to writing better AI coding prompts. And if you’re still choosing which tool to set this up in, our Claude Code vs Cursor comparison and the broader best AI coding tools roundup will point you to the right one.