AGENTS.md Files

By the Syncfusion DevTutorials team · Last updated October 20, 2026

Write the AGENTS.md file AI coding agents read at the start of every session. Prune a 156-line file to the facts the code cannot say, apply the always-on test, share one file with CLAUDE.md and Cursor rules, and use nested files in bigger repos.

The 160-Line File the Agent Half-Ignored

The order-support team adds an AGENTS.md file to the repo, so AI coding agents know how the project works. Everyone adds something. After a few months, it looks like this:

An AGENTS.md that grew and grew

# Order Support — Instructions for AI Agents

Welcome! This file explains everything about the order-support project.
Please read all of it carefully before you do anything.

## About the project

Order Support is a service that answers customer questions about orders, refunds and shipping.
It was started in 2021 by the support team, after the old ticket system became too slow.
In 2022 we moved from JavaScript to TypeScript. In 2023 we added the refund flow.
In 2024 we added shipping updates. In 2025 we moved hosting twice.
The project is very important to the company, so please be careful.

## General rules

- Write clean code.
- Follow best practices.
- Be careful when you change things.
- Use common sense.
- Keep the code simple.
- Make sure the code works before you finish.
- Write tests where appropriate.
- Do your best to match the existing style.
- Use TypeScript, because the project is written in TypeScript.
- Use the src folder for source code.
- Use the test folder for tests.
- Use meaningful variable names.
- Do not write very long functions.
- Add comments where the code is hard to follow.

<!-- Old rule from 2023: always use the v1 refunds API. -->

## Install

These are the same steps as in the README.

1. Install Node.
2. Clone the repository.
3. Run the install command.
4. Wait for it to finish.
5. Open the folder in your editor.

## Folder structure

- `src/` has the source code.
- `src/refunds/` has the refund code.
- `src/shipping/` has the shipping code.
- `src/orders/` has the order code.
- `src/api/` has the API routes.
- `src/ui/` has the user interface.
- `test/` has the tests.
- `docs/` has the docs.
- `scripts/` has scripts.
- `public/` has static files.

## Refund policy

Refunds are allowed within 30 days of delivery.
After 30 days, offer a voucher instead.
Damaged items need a photo before a refund.
Refunds over ₹5,000 need a manager's approval.
Gift cards cannot be refunded.
Shipping costs are refunded only for damaged items.
Refunds go back to the original payment method.
Bank transfers can take up to 5 working days.
Card refunds can take up to 3 working days.
Wallet refunds are instant.
If a customer asks twice, check the refund log first.
If the order number is missing, ask for the email address.
If the item was a gift, refund the buyer, not the receiver.
Partial refunds are allowed for multi-item orders.
Never refund in cash.

## Shipping policy

Orders ship within 2 working days.
Express orders ship the same day if placed before 2 pm.
International orders take 7 to 14 days.
Tracking numbers are sent by email.
Lost parcels are re-sent after 10 days.
Customers can change the address until the order ships.
Remote areas may take 3 extra days.
Large items ship by courier only.
Fragile items get extra packing.
Returns use the same courier.

## Code style

- Use 2 spaces for indentation.
- Use single quotes in TypeScript.
- Use semicolons.
- Use camelCase for variables.
- Use PascalCase for classes.
- Use kebab-case for file names.
- Put one class in each file.
- Sort imports alphabetically.
- Do not leave unused imports.
- Do not leave console.log calls.
- Prefer const over let.
- Prefer async and await over then.
- Keep lines under 100 characters.
- Use the shared logger.

## Testing

We have tests. Please write tests where appropriate.
Tests are in the test folder.
Make sure tests pass.
Tests are important.

## Team

- Asha leads the refund work.
- Ravi leads the shipping work.
- Meena reviews the UI.
- The team meets on Mondays.
- Ask in the team channel if you are unsure.

## Pull requests

- Write a good title.
- Write a good description.
- Link the ticket.
- Ask for a review.
- Fix review comments.
- Squash before merging.
- Delete the branch after merging.

## Glossary

- Order: something a customer bought.
- Refund: money paid back.
- Voucher: credit for a later order.
- Courier: the company that delivers.
- Parcel: the box that is delivered.
- Ticket: a customer question.
- Agent: a person, or an AI, who answers tickets.
- SLA: how fast we must reply.
- Customer: the person who placed the order.
- Delivery: when the parcel arrives.
- Return: a parcel sent back.
- Policy: a rule the team agreed on.
- Escalation: passing a ticket to a lead.
- Backlog: work not started yet.
- Release: a new version of the app.
- Hotfix: an urgent fix.
- Staging: a test copy of the app.
- Production: the live app.

## One more thing

Money is stored in paise as an integer, never as a decimal.

## Final notes

Thank you for reading this far.
Please remember all of the rules above.
Write clean code and follow best practices.
If anything is unclear, use common sense.
Good luck!

Open the Checks tab. Four AI-native rules fire:

• AGT001: the file is 160 lines. It is read in full at the start of every session.
• AGT002: it never says how to run the tests. "Run the install command" names no command.
• AGT003: lines like "Write clean code" and "Use common sense" tell an agent nothing it would not do anyway.
• AGT004: an old rule hides in an HTML comment. The page hides it. The agent still reads it.

Now open the Agent view tab. A simulated agent that reads only this file tries six everyday tasks, and gets none of them right:

• It missed how to install, test, run one test and check a change: the file never gives the commands.
• It ignored the money rule: the one useful line is at the very end, past line 150, buried under everything else.
• It misread the refund rules: the only instruction is the old one hidden in a comment.

The whole file also costs every session more than 1,100 tokens, before the agent has read one line of code. And most of it is either obvious, already in the README, or only needed for one kind of task.

The agent does not ignore the file on purpose. A long file full of vague rules buries the few that matter.

In this lesson, you will learn what an AGENTS.md file is for, what belongs in it, and how to cut it down to the facts an agent cannot work out on its own.

In simple words: AGENTS.md is a short note for AI agents about your project. It should hold only what the code cannot tell them.

TL;DR

• AGENTS.md is a Markdown file at the root of a repo. Many AI coding agents read it at the start of every session.
• It is plain Markdown. There are no required fields or headings.
• Put in it what the agent cannot work out from the code: commands, hidden conventions, gotchas, the checks to run before finishing.
• Leave out what the code already says, what the README already says, and rules that only matter for one task.
• Ask of every line: does this apply to almost every task? If not, it belongs in a skill, not here.
• Tool-specific files like CLAUDE.md can import it with one line: @AGENTS.md.

A Real-World Example

Think about a new team member joining a project.

A useful welcome note explains how to start the project, which command runs the tests, which important rules to follow, and where to ask for help. It contains only the information needed to begin working safely.

A poor welcome note includes details that are already clear from the code, long explanations about old decisions, and instructions that apply only to rare situations. The important rules become difficult to find.

The new team member can read the code to understand how a function works. However, the code may not reveal the command required to run the project or a project-specific rule that must always be followed.

AGENTS.md serves as that welcome note for an AI coding agent. It should contain the essential project instructions that the agent cannot easily discover from the code itself.

What You Will Learn

In this lesson, you will learn:

1. What AGENTS.md is, and which tools read it.
2. Why its size matters more than any other Markdown file.
3. What to put in it, and what to leave out.
4. The always-on test: when a rule belongs in a skill instead.
5. How tool-specific files like CLAUDE.md and Cursor rules fit in.
6. How nested AGENTS.md files work in bigger repos.

Cheat Sheet

A good AGENTS.md for order-support

# AGENTS.md

Order Support answers customer questions about orders, refunds and shipping. TypeScript, Node 20.

## Commands

- Install: `npm ci`
- Run the app: `npm run dev`
- Run all tests: `npm test`
- Run one test file: `npm test -- test/refunds/window.test.ts`
- Lint and type-check: `npm run check` (must pass before you finish)

## Project map

- `src/refunds/` refund rules. The rules themselves live in `docs/refunds.md`; read it before changing this folder.
- `src/api/` HTTP routes. Every route needs a test in `test/api/`.
- `scripts/` one-off tools. Do not import from here in `src/`.

## Conventions the code does not show

- Money is stored in paise as an integer (`12999` = ₹129.99). Never use floating point for money.
- All dates are UTC in the database and in the API. Convert only in `src/ui/`.
- Use the v2 refunds API (`src/refunds/v2/`). v1 is kept only for old reports.

## Gotchas

- `npm test` needs the `TZ=UTC` environment variable; the script sets it. Do not run `vitest` directly.
- The refund log is append-only. Never write code that updates or deletes a row in `refund_log`.

## Before you finish

1. Run `npm run check` and `npm test`.
2. If you changed a rule in `src/refunds/`, update `docs/refunds.md` in the same change.

Open the Checks tab: nothing fires. Open the Agent view: about 33 lines, read every session, and the simulated agent gets all six tasks right. Every line is a fact the agent could not guess from the code, or a command it must run.

What AGENTS.md Is

A README for Agents

The README is written for people. It says what the project is and how to start. AGENTS.md is written for AI coding agents. It says how to work on the project safely: the exact commands, the hidden rules, and the traps.

It is an open format. It started as a joint effort by several AI coding tool makers, and it is now looked after by the Agentic AI Foundation, under the Linux Foundation. Codex, Cursor, Jules, Aider, VS Code and many other tools read it. Claude Code reads it too, when the project has no CLAUDE.md.

There are no required fields. It is just Markdown. Headings like ## Commands and ## Gotchas are a habit, not a rule. Use whatever headings make the file easy to scan.

Why Size Matters So Much

Most Markdown files are read when someone opens them. AGENTS.md is different. It is loaded into the agent's context at the start of every session, whatever the task is.

That has two costs:

• Tokens. Every line uses part of the agent's context window, in every session, for every task.
• Attention. The more rules there are, the less weight each one gets. A key rule in a long file is easier to miss than the same rule in a short one.

Claude Code's own docs advise keeping such files under 200 lines, because longer files "reduce adherence". This course uses a stricter budget of 150 lines. The AGT001 check uses it.

What to Put In, What to Leave Out

The One Question

For each line, ask: could the agent work this out by reading the code?

If yes, delete the line. The agent will read the code anyway.

If no, keep it. That is exactly what this file is for.

The Four Kinds of Line That Earn a Place

Look again at the good file in the cheat sheet. Every line is one of four kinds:

1. Commands. The exact install, run, test and lint commands, including how to run one test. These are the facts an agent most often gets wrong by guessing.
2. Conventions the code does not show. Units, time zones, which of two APIs to use, what never to import.
3. Gotchas. The trap that cost someone a day: a missing environment variable, a table that must not be changed.
4. Before you finish. The checks that prove a change is done.

What Goes Elsewhere

Link to these files instead of copying them. docs/refunds.md stays the one true copy of the refund policy. AGENTS.md just points to it.

The Always-On Test

Some rules matter a lot, but only sometimes. The refund policy is a good example. It is vital when an agent works on refunds. It is noise when the agent fixes a button colour.

Here is the test: does this rule apply to almost every task in the repo?

• Yes: it belongs in AGENTS.md, which loads every time.
• No, only for some tasks: it belongs in a skill, which loads only when a task needs it. You will write one in the next lesson.

This one question removed most of the 160-line file at the top of the lesson.

Tool-Specific Files

CLAUDE.md and the Import Line

Some tools have their own rules file. Claude Code uses CLAUDE.md. If a project has both files, Claude Code reads CLAUDE.md and not AGENTS.md.

You do not want to keep two copies of the same rules. So make CLAUDE.md a thin shim: one import line, then anything that only applies to Claude Code.

A CLAUDE.md that shares AGENTS.md

@AGENTS.md

## Claude Code only

- Use plan mode for any change to `src/refunds/`.

The line @AGENTS.md tells Claude Code to load AGENTS.md in its place. Now one file holds the shared rules, and every tool sees the same ones.

Cursor Rules

Cursor reads AGENTS.md too. It also has its own rules files in .cursor/rules/, with the extension .mdc. Each one starts with frontmatter that says when it applies.

A Cursor rule for one folder

---
description: Refund rules for code in src/refunds
globs: src/refunds/**
alwaysApply: false
---

Read `docs/refunds.md` before changing refund code.
Never update or delete rows in `refund_log`.

globs says which files the rule is for. With alwaysApply: false, the rule is used only when the agent works on matching files. That is the always-on test, built into the tool.

Which File Each Tool Reads

Pick your tool below to see its paths. The same choice changes the paths in the next lessons and in the capstone kit.

Tools change often. Check each tool's docs before you rely on a detail.

Nested AGENTS.md Files

A big repo can have more than one AGENTS.md. Put one in a subfolder for rules that only apply there. When an agent edits a file, the nearest AGENTS.md in the folder tree takes precedence.

Nested AGENTS.md files

order-support/
├── AGENTS.md              rules for the whole repo
└── apps/
    └── billing/
        ├── AGENTS.md      extra rules for billing only
        └── src/

A folder-level AGENTS.md

# Billing

- Run only the billing tests: `npm test -- apps/billing`
- Invoices are immutable once sent. Create a credit note instead of editing one.

This is another way to pass the always-on test: billing rules load only when the agent works in the billing folder.

A message you type to the agent in the chat overrides all of these files. They are defaults, not locks.

Pruning a Real File

Go back to the 160-line file at the top of this lesson. Prune it with the one question, the four kinds of line, and the always-on test:

1. Delete the history, the welcome, the thanks and every filler rule.
2. Delete what the code shows: TypeScript, folders, indentation, naming.
3. Delete the install steps; the README has them.
4. Move the refund and shipping policies to docs/ and to skills.
5. Delete the old comment. If the rule is still true, write it as a real line.
6. Add what was missing: the real commands.

Watch the Checks tab, the line count and the six tasks in the Agent view as you go. You should end with something close to the good file in the cheat sheet.

Watch This Space

New Markdown conventions for AI tools appear every few months. Two you may meet:

• DESIGN.md: a file that describes a project's visual design (colours, spacing, components) for AI tools that build user interfaces.
• Markdown-for-agents toolchains, such as MDA, that check AGENTS.md and SKILL.md against a schema and build one source into the files each tool expects.

Neither is a settled standard yet. The rules in this lesson still apply to them: short, specific, and only what the code cannot say.

Where This Is Used

• Every repo that AI agents work in: the root AGENTS.md.
• Monorepos: one AGENTS.md per app or package.
• Teams with several tools: one AGENTS.md, plus thin CLAUDE.md or Cursor rule files.
• Code review: a change to AGENTS.md changes how every future agent session behaves, so review it like code.

Common mistakes

Quick Check

Exercises

What to Remember

• AGENTS.md is a short Markdown note for AI coding agents, read at the start of every session.
• It is plain Markdown, with no required fields.
• Keep only what the code cannot say: commands, hidden conventions, gotchas, and the checks to run before finishing.
• Leave out filler, history, anything the code or README already says.
• The always-on test: if a rule applies to only some tasks, put it in a skill or a linked doc.
• One shared AGENTS.md; tool files like CLAUDE.md import it with @AGENTS.md.
• The nearest AGENTS.md to the edited file takes precedence; a chat message overrides them all.

Further Reading

• AGENTS.md: the open format, with examples and FAQs.
• Claude Code: how Claude remembers your project: CLAUDE.md, imports and how Claude Code reads AGENTS.md.
• Codex: AGENTS.md guide: how Codex finds and merges AGENTS.md files.

Next: Skills and Subagents, where you write a SKILL.md with frontmatter, test which prompts load it, and write a reviewer subagent file.