AGENTS.md / CLAUDE.md - The way I like to work with AI Agents

Every time you start a new agent session, the model walks in with amnesia. Your carefully tuned workflow forgotten. Your team's "we don't do that" rule never heard of it. By turn three the agent has confidently rewritten a piece of your codebase using patterns you abandoned six months ago, and your only recourse is to re-type the same orienting context you've typed fifty times this week.

There's a single boring markdown file that solves this. It's not a prompt. It's checked into your repo. It's called AGENTS.md or CLAUDE.md, depending on your tool.

And it's the highest-leverage thing you can add to a codebase that's touched by agents.

The Per-Session Amnesia Problem

Agents don't remember you between sessions. Every new conversation, every new branch, the model cold-starts with zero context about your project beyond what's visible in the current turn.

That's fine for one-off tasks. It's catastrophic for anything that spans more than an afternoon.

The workaround most people land on is prompt-heavy: paste the same conventions into every chat, pin context, maintain a Notion page they copy-paste from. Every approach has the same structural problem it's session state pretending to be project state.

The File That Doesn't Get Lost

AGENTS.md (or CLAUDE.md, or .cursorrules, depending on the tool) is the file the agent reads automatically on every session. It's checked into the repo. It follows the branch. It gets code-reviewed when it changes.

Functionally, it is your project's memory between agent sessions.

And that reframe matters more than the file format itself. The value isn't "I wrote good instructions once." It's "the agent now walks into the project the way a senior teammate would already knowing where things live, what we don't do, what's currently in flight."

What Belongs in the File

The first AGENTS.md most people write is too long. They try to document the whole codebase in one file, the agent reads 4000 tokens of history before doing anything, and the value collapses under its own weight.

Here's what actually earns its place.

1. Architecture at a glance

Not every file. The shape.

• Monorepo vs single project
• Which directories matter
• Where business logic lives vs infrastructure
• What each subsystem is responsible for

Three paragraphs. If you need ten, you're documenting the codebase instead of orienting the agent.

2. The rules you actually enforce

Not "write clean code" (useless). The specific, opinionated rules you'd call out in code review:

• "Never mock the database in integration tests."
• "All async functions take an AbortSignal."
• "We don't use barrel exports."
• "Server Components by default 'use client' requires justification."

If you wouldn't bother flagging it in a PR, it doesn't belong here.

3. Workflow commands

The agent needs to know how to run the thing, not just modify it.

• pnpm test:unit vs pnpm test:int
• How to start the dev server
• How the build is configured
• How to check types (and whether types are authoritative)

Without this, you end up with agents that edit code confidently and then can't verify any of it worked.

4. Current state

This is the part nobody writes and it's the most valuable thing in the file.

What is the project right now? What's the active branch doing? What migration are you mid-way through? Which module is being rewritten and shouldn't be touched?

Prompts are transient. Architecture is slow-changing. Current state is what stops an agent from making confidently wrong assumptions about work that's in flight.

5. Forbidden patterns

Explicit "don't do this." Stronger than "prefer that."

LLMs respond to clear negatives better than soft preferences. "Don't use class components" beats "we prefer functional components" every time. The prefer-form invites the model to weigh it against other considerations. The negative-form is just a wall.

Loading Into Agent Context

Top path: what a good AGENTS.md buys you. Bottom path: what most codebases leave on the table.

The Maintenance Trap

Here's the uncomfortable part. AGENTS.md is not write-once-and-forget.

Every stale entry in the file is active misinformation. The agent trusts it completely. A rule that was true six months ago but quietly became wrong say, "we use Webpack" when you migrated to Turbopack in January is worse than having no rule at all. The agent will confidently regress the codebase to follow a convention you forgot you wrote.

So AGENTS.md has to be treated like code:

• It lives in the repo
• It gets reviewed when it changes
• Stale entries are bugs
• "Current state" expires either update it when you merge, or date-stamp the section

The teams getting the most value from AGENTS.md are the ones that have added a soft rule: touching a project convention means touching this file in the same PR.

A Real AGENTS.md Example

Shape, not scripture. Your sections will differ.

# Project Agent Guide

## Stack
- Next.js 16 (App Router, Cache Components)
- pnpm monorepo, 3 workspaces
- Supabase + Postgres, Drizzle ORM
- Runs on Vercel (Fluid Compute)

## Rules
- Server Components default. `"use client"` requires justification in PR.
- No mocked DB in integration tests  use the test Postgres container.
- Keyset pagination only. We removed OFFSET-based pagination in Q1.
- Every mutation returns the updated row. No separate re-fetches.

## Workflow
- `pnpm dev`  full stack dev
- `pnpm test`  unit + integration, ~45s
- `pnpm typecheck`  authoritative, must pass before commit
- Migrations: `pnpm db:gen`, then commit the generated file

## Current (as of 2026-02)
- Mid-migration: removing `lib/legacy-auth/`. Do not extend it.
- Active PR: rewrite of `/api/search`  don't touch `app/search/` this week.
- Flag: `ENABLE_AGENT_MODE` is being ripped out, ignore references to it.

## Don'ts
- Don't add barrel exports (we removed them for TTI reasons).
- Don't use `any`. `unknown` + narrowing.
- Don't add another CSS framework. Tailwind only.

Four hundred words. Does more for the agent than three thousand tokens of mid-conversation prompting ever will.

The Verdict

People writing long, repeated prompts are solving the wrong problem. The issue isn't that the agent doesn't understand this session it's that it doesn't understand your project across sessions.

AGENTS.md is the cheapest, highest-leverage thing you can add to a codebase that's touched by agents. It's a static file. It takes an hour to write. It pays back on every session, on every branch, with every teammate's agent, forever.

The prompt is the car. AGENTS.md is the road.

Frequently Asked Questions

What's the difference between AGENTS.md and CLAUDE.md?

Same idea, different tool conventions. CLAUDE.md is what Anthropic's Claude Code reads automatically. AGENTS.md is the more general emerging standard adopted by multiple tools (OpenAI Codex, others). Cursor uses .cursorrules, Aider uses CONVENTIONS.md. Pick whichever your primary tool reads or maintain one canonical file and symlink the rest, since the content is tool-agnostic.

Should I put every coding convention in AGENTS.md?

No. Every token the agent reads before acting is a token it's spending to orient instead of execute. Keep it tight only the rules that would change what the first action looks like. A style guide your team doesn't actively enforce in PRs has no business in this file; it won't change behavior, it'll just bloat context.

Does a long AGENTS.md hurt performance?

Yes, in two ways. First, context cost a 4000-token file is 4000 tokens the agent can't spend on the actual task. Second, selective attention the longer the file, the more the model "skims" rather than applies. A tight 300–500 line file is followed more consistently than a 2000-line one.

How do I keep it from going stale?

Treat it like code. Review it in PRs when it changes. Add a soft team rule: if you're changing a convention, you're changing AGENTS.md in the same commit. Mark time-sensitive sections (like "Current") with dates so stale entries are obvious at a glance.

Can I use AGENTS.md to reduce agent sycophancy?

Partially and it's one of the highest-ROI uses of the file. Rules like "No praise preamble," "No validation of my question," and "If my approach has a real flaw, say so first" do real work when loaded once at session start, and you stop burning tokens re-typing them every turn. It won't fully eliminate sycophancy that's structural to RLHF but it moves the baseline meaningfully.