Skip to content
Agentic SDLC

CLAUDE.md vs AGENTS.md for product teams: what goes in the repo, what goes in the brief

Claude Code reads CLAUDE.md, Codex reads AGENTS.md, and since September Claude Code can fall back to AGENTS.md too. Here is how each agent loads its instructions in 2026, a single-source setup that serves both, and the line most teams get wrong: build rules belong in the repo, while the who, why and limits of each ticket belong in a shared brief the agent reads over MCP.

Sydla Journal cover: CLAUDE.md vs AGENTS.md for product teams, showing a repository tree with AGENTS.md, CLAUDE.md and a path-scoped rule above a workspace tree with the brief, acceptance criteria, UX states and run record

The 900-line file nobody reads

Open the CLAUDE.md in a busy repository and you will often find a history of the product: the build commands, then a paragraph about the pricing page, the persona for the onboarding flow, three versions of the export spec, a warning about a customer who churned. Every line made sense the day someone added it. Together they cost context on every session, and the agent follows less of them.

Then the team adds Codex, which reads AGENTS.md, and someone copies the file across. Two files drift. A designer updates the empty state in Figma, the spec changes in Confluence or Notion, the ticket moves in Jira, and neither instruction file knows.

The fix is not a better instruction file. It is deciding what belongs in one at all. This guide covers how Claude Code and Codex load their instructions in November 2026, a setup that serves both from one source, and where the rest of your product context should live instead.

How Claude Code reads CLAUDE.md in 2026

Anthropic's memory docs describe four layers, loaded broadest first and concatenated rather than overridden:

  1. Managed policy. An organization-wide CLAUDE.md that IT deploys to a system path.
  2. User. Your personal ~/.claude/CLAUDE.md, applied to every project.
  3. Project. ./CLAUDE.md or ./.claude/CLAUDE.md, committed with the code. Claude Code also loads CLAUDE.md files from every directory above where you start it, and from subdirectories on demand.
  4. Local. ./CLAUDE.local.md for personal project notes, kept out of git.

Three details matter for teams. Imports: a line such as @docs/testing.md pulls another file in, up to four hops deep, but imports organize a file without reducing what it costs in context. Scoped rules: markdown files in .claude/rules can carry a paths field that matches files, such as the TypeScript files under src/api, and then load only when Claude reads or edits a matching file. Size: Anthropic recommends keeping each CLAUDE.md under 200 lines, because longer files use more context and reduce adherence.

And the change most teams missed: from Claude Code v2.1.277, Claude can read a repository's AGENTS.md in place of CLAUDE.md. By default that only happens when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it. A Project instructions setting can make Claude read both, and a CLAUDE.md that imports @AGENTS.md has always worked. Claude does not read AGENTS.override.md, AGENTS.local.md or a .agents folder.

How Codex reads AGENTS.md

AGENTS.md is the open format that Codex, Cursor, Gemini CLI, GitHub Copilot's coding agent, Jules, Zed, Warp and many others read. It is now stewarded by the Agentic AI Foundation under the Linux Foundation, and agents.md counts it in more than 60,000 open-source projects.

OpenAI's Codex docs describe the loading rules. In the Codex home folder it reads AGENTS.override.md if present, otherwise AGENTS.md. Then, starting at the project root, usually the git root, it walks down to your current directory and takes at most one file per directory: the override, then AGENTS.md, then any fallback names you configure. Files are joined root first, so the closest file has the last word. Codex stops adding files once the combined size reaches project_doc_max_bytes, 32 KiB by default.

That limit is the practical difference. A long CLAUDE.md costs adherence; a long AGENTS.md chain can be cut off, and the instructions in the deepest folder, the most specific ones, are the first to go.

One source, two agents: the setup we recommend

If your team runs both agents, as many do after reading our Claude Code vs Codex comparison, keep one source of truth and a thin adapter:

  1. AGENTS.md at the root holds the shared rules. Build, test and lint commands, the folder map, coding conventions, what an agent must never touch, and how to verify a change. Every agent reads it.
  2. CLAUDE.md is two lines. An @AGENTS.md import, then anything only Claude needs, such as which skills or subagents to use. Because a CLAUDE.md exists, Claude reads it, and the import brings the shared rules in.
  3. Folder rules sit next to the folder. A nested AGENTS.md in a service folder for Codex, and a .claude/rules file with a matching paths field for Claude, both pointing at the same short notes.
  4. Personal preferences stay personal. CLAUDE.local.md or your user file, never the shared one.
  5. Review it like code. The file changes rarely, goes through merge requests and has an owner. If a line has not prevented a mistake in a month, delete it.

What does not belong in either file

Instruction files answer one question: how do you work in this codebase? They are poor at a second question: what are we building this time, for whom, and why? That answer changes every ticket, and it belongs to people who never open the repository.

  1. The brief. Who the change is for, the problem, the limits, what is out of scope. A product manager edits it on Tuesday; the agent must see Tuesday's version, not last month's paste.
  2. Acceptance criteria. Numbered and testable, per ticket. Our acceptance criteria guide lists six rules.
  3. Design states. Empty, loading, error and done, as reviewed in the design tool. Screenshots in a markdown file go stale the day the designer moves a button. See design-to-code handoff for AI coding agents.
  4. Decisions and history. Why the export is capped at 10,000 rows belongs in the brief or a decision record, linked from the ticket, not in a file loaded into every session.
Two columns feed one coding agent. Left, the repository: AGENTS.md with build, test, conventions and boundaries for every agent; CLAUDE.md importing AGENTS.md plus Claude-only notes; scoped rules for one folder. Right, the Sydla workspace: brief, acceptance criteria, UX Studio states and run record, reaching Claude Code or Codex through one Sydla MCP connection, with the run written back.
Instruction files carry the how. The brief carries the what and the why, fresh for every ticket.

Where product context lives in a six-tool stack

In a typical 2026 stack, that product context is spread over six tools, each with its own seat, its own AI layer and, for agents, its own MCP server and limits. Our MCP servers guide covers the per-call and per-day caps. Here is one paid seat per tool and what each holds:

One paid seat per tool, monthly USD list prices before tax, checked on 14 November 2026.
Tool and planSeat / monthContext it holds for the agentBuilt-in AI billingAgent reaches it via
Jira Standard$9.70The ticket and its statusRovo on pooled Rovo creditsAtlassian MCP, credit-metered calls
Confluence Standard$7.15The spec and decisionsRovo on the same creditsAtlassian MCP
Notion Plus$12.00Specs and notes for teams on NotionNotion AI and agents on Notion creditsNotion MCP
Figma Professional, Full seat$20.00Screens and statesFigma AI credits per seatFigma MCP, daily call limits
Miro Starter$10.00Flows and workshop boardsCreate with AI on Miro creditsMiro MCP, daily call limits
Canva Business$25.00Launch assetsCanva AI usage per memberCanva connector
Six-tool total$83.85Context in six placesUp to six AI metersSix connections, or a paste into CLAUDE.md
Sydla$19.00Brief, criteria, UX states, tickets, runs and review togetherNone billed: your own Claude Code or CodexOne Sydla MCP
Bar chart of one paid seat per tool: Canva Business $25.00, Figma Professional Full $20.00, Notion Plus $12.00, Miro Starter $10.00, Jira Standard $9.70 and Confluence Standard $7.15, totalling $83.85 per user per month, against Sydla at $19.00, a saving of $64.85.
One seat each across the six-tool stack against one Sydla seat, before any AI credits.

Faced with six connections, many teams take the shortcut: paste the spec into CLAUDE.md. That is how the 900-line file starts. Switching saves $64.85 per person per month on seats, before any credit pack; the comparison overview covers each tool and the pricing section lists every source.

The rule of thumb

If a line would still be true for the next ten tickets, it can go in AGENTS.md. If it is only true for this ticket, it belongs in the brief. If you are not sure, it belongs in the brief, where a person can see it, change it and review it.

How it works in Sydla Desktop

Sydla is the workspace for the second column: briefs and criteria in Sydla Docs, screens and states in UX Studio, tickets on the plan, runs and reviews on each work item. Your repository keeps its AGENTS.md and CLAUDE.md exactly as they are.

  1. Start your own agent. Sydla Desktop launches the Claude Code or Codex CLI you already use, signed in with your own Anthropic or OpenAI account, in your local checkout. Each agent reads its instruction files the usual way. The Desktop guide covers the first run.
  2. Read the ticket's context over one MCP. Through the Sydla MCP connection, the agent fetches the work item, its brief, its acceptance criteria and the published UX Studio handoff with every state, at the version a person approved, not a copy pasted last month.
  3. Build against the criteria. The agent implements, runs the checks your AGENTS.md describes, and reports each criterion as passed or failed with evidence.
  4. Write the run back. Cost, criterion results and the merge request are recorded on the work item. Agents can request a gate; only a person decides it. Our four-pass review checklist covers that step.
  5. Keep the file short. Because the product context arrives with each ticket, the instruction file goes back to what it is good at: a short list of how to work in this codebase.

There are no Sydla AI credits and no token markup: your Claude or ChatGPT plan pays for the model and $19 pays for the workspace. For the bigger picture of what that replaces, read AI credit fatigue.

A 30-minute cleanup for your instruction files

Pick one repository this week and work through it in order:

  1. Count the lines. Over 200 in CLAUDE.md, or several AGENTS.md files adding up near 32 KiB, means something is in the wrong place.
  2. Move product context out. Specs, personas, roadmap notes and design descriptions go into the brief or a decision record linked from the ticket.
  3. Make AGENTS.md the source. Shared rules there, CLAUDE.md reduced to the import plus Claude-only notes.
  4. Scope what is local. Rules for one service move next to it, as a nested AGENTS.md and a matching paths rule.
  5. Run one ticket end to end. Give the agent a brief with criteria and states, and see whether the shorter file plus fresh context does better than the long file did. The solo founder stack post shows the same loop for a team of one.

Frequently asked questions

What is the difference between CLAUDE.md and AGENTS.md?

CLAUDE.md is the instruction file Claude Code loads at the start of a session, with managed, user, project and local layers, @imports and path-scoped rules. AGENTS.md is an open format stewarded by the Agentic AI Foundation under the Linux Foundation and read by Codex, Cursor, Gemini CLI, GitHub Copilot's coding agent and many other tools. Both tell a coding agent how to work in a repository.

Does Claude Code read AGENTS.md?

Yes, from Claude Code v2.1.277, but by default only in place of CLAUDE.md: it reads AGENTS.md when there is no CLAUDE.md or CLAUDE.local.md in the working directory or above it. A Project instructions setting can make it read both, and a CLAUDE.md containing an @AGENTS.md import loads it in any version. Claude Code does not read AGENTS.override.md, AGENTS.local.md or a .agents folder.

How should a team use CLAUDE.md and AGENTS.md together?

Keep the shared rules, such as build and test commands, conventions and boundaries, in a root AGENTS.md. Make CLAUDE.md a thin file that imports @AGENTS.md and adds only Claude-specific notes. Put folder-specific rules next to the folder, and keep personal preferences in CLAUDE.local.md or your user file.

How long should CLAUDE.md or AGENTS.md be?

Anthropic recommends keeping each CLAUDE.md under 200 lines, because longer files use more context and reduce adherence; imports organize content but do not reduce its cost. Codex stops adding AGENTS.md files once their combined size reaches project_doc_max_bytes, 32 KiB by default, so the most specific nested files are the first to be cut.

Where should product specs and designs go if not in CLAUDE.md?

In a shared brief that the agent reads per ticket: the who, why and limits, numbered acceptance criteria and the reviewed design states. In Sydla those live in Docs and UX Studio, and Claude Code or Codex reads them through one Sydla MCP connection. Sydla costs $19 per user per month against $83.85 for one seat each of Jira, Confluence, Notion, Figma, Miro and Canva, with no AI credits or token markup.

Keep reading.

All articles

ONE WORKSPACE. THE ENTIRE SDLC.

Your next project.
One $19 subscription.

Keep using your Claude Code and Codex accounts. Bring the work into Sydla.

Get SydlaUSD / user / month · Billed monthlyProvider subscriptions remain separate.