Stop bloating your AGENTS.md: reference your conventions instead of pasting them
Most AGENTS.md files I see are bloated walls of text. Here is the problem: your agent reads this file at the start of every task. Everything you put in there is passed to the LLM with every prompt. A 400-line AGENTS.md burns context tokens on every single action — even when the agent only needs one rule from it.
The fix is simple: keep AGENTS.md as a thin index, move the details into separate docs, and reference them.
What it looks like in practice
Here is the real AGENTS.md from my current project (invoice management SPA):
# AGENTS.md
## Project
IOD Invoice — invoice management SPA.
React 18 + TypeScript + Vite, Ant Design 6, Redux Toolkit (RTK Query),
styled-components, i18next (EN/RO), OIDC/Keycloak auth.
## Commands (npm; Node 18+)
- `npm run dev` — dev server
- `npm run build` — tsc + production build
- `npm run test` — vitest watch; `npm run test:ci` — run + coverage
- `npm run lint` — eslint, zero warnings tolerated
## Architecture
See `docs/architecture.md`
## TypeScript Conventions
See `docs/typescript-conventions.md`
## Style
See `docs/style-conventions.md`
## React Components
See `docs/react-components.md`
And in docs/ live the actual conventions — architecture decisions, TypeScript rules, styling rules, component patterns.
The agent loads the index plus only the docs it actually needs for the current task. A TypeScript task? It reads one conventions file, not your entire wiki. That is the whole trick: your conventions stay detailed, your context stays clean.
One gotcha: the CLAUDE.md twin problem
Many of us run more than one agent. Claude Code reads CLAUDE.md, everything else reads AGENTS.md — and the two files slowly drift apart until each agent works from different rules.
The fix is a symlink, so both names point at one file:
macOS / Linux:
ln -s AGENTS.md CLAUDE.md
Windows (order is reversed):
mklink CLAUDE.md AGENTS.md
Edit one file, both agents see the update. No drift, no duplicated maintenance.
Bonus: monorepos want nested AGENTS.md files
In a monorepo, put an AGENTS.md in each subfolder:
app/
├── AGENTS.md # shared rules
├── client/
│ └── AGENTS.md # frontend-specific rules
└── backend/
└── AGENTS.md # backend-specific rules
Working inside client/, the agent loads both — the root file and the subfolder file. Shared conventions live once, stack-specific rules live next to the code they govern.
The takeaway
Your AGENTS.md is not documentation — it is a context budget. Every line in it is paid on every task. Index + references keeps the rules detailed and the context cheap.
If this was useful:
More React + AI tips daily in my Telegram channel: t.me/novamind_hub
I'm building NovaMind — an AI assistant in Telegram that debugs errors from screenshots (the reason my AGENTS.md files matter so much): t.me/mindrorgebot_bot — 30 messages/day free.
Building with coding agents? Drop your biggest AGENTS.md pain in the comments — curious which conventions you enforce first
