Stop bloating your AGENTS.md: reference your conventions instead of pasting them

A developer advocates keeping AGENTS.md files as thin indexes that reference separate convention docs rather than pasting full rules inline, arguing that every line in the file is passed to the LLM on every task and consumes context tokens. The approach uses symlinks so CLAUDE.md and AGENTS.md share one file, and per-subfolder AGENTS.md files in monorepos so agents load only the shared and stack-specific rules they need.

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. 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. 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. 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. 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 👇