{"slug": "stop-bloating-your-agents-md-reference-your-conventions-instead-of-pasting-them", "title": "Stop bloating your AGENTS.md: reference your conventions instead of pasting them", "summary": "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.", "body_md": "Stop bloating your AGENTS.md: reference your conventions instead of pasting them\n\nMost 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.\n\nThe fix is simple: keep AGENTS.md as a thin index, move the details into separate docs, and reference them.\n\nHere is the real AGENTS.md from my current project (invoice management SPA):\n\n```\n# AGENTS.md\n\n## Project\nIOD Invoice — invoice management SPA.\nReact 18 + TypeScript + Vite, Ant Design 6, Redux Toolkit (RTK Query),\nstyled-components, i18next (EN/RO), OIDC/Keycloak auth.\n\n## Commands (npm; Node 18+)\n- `npm run dev` — dev server\n- `npm run build` — tsc + production build\n- `npm run test` — vitest watch; `npm run test:ci` — run + coverage\n- `npm run lint` — eslint, zero warnings tolerated\n\n## Architecture\nSee `docs/architecture.md`\n\n## TypeScript Conventions\nSee `docs/typescript-conventions.md`\n\n## Style\nSee `docs/style-conventions.md`\n\n## React Components\nSee `docs/react-components.md`\n```\n\nAnd in `docs/` live the actual conventions — architecture decisions, TypeScript rules, styling rules, component patterns.\n\nThe 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.\n\nMany 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.\n\nThe fix is a symlink, so both names point at one file:\n\n**macOS / Linux:**\n\n```\nln -s AGENTS.md CLAUDE.md\n```\n\n**Windows (order is reversed):**\n\n```\nmklink CLAUDE.md AGENTS.md\n```\n\nEdit one file, both agents see the update. No drift, no duplicated maintenance.\n\nIn a monorepo, put an `AGENTS.md` in each subfolder:\n\n```\napp/\n├── AGENTS.md          # shared rules\n├── client/\n│   └── AGENTS.md      # frontend-specific rules\n└── backend/\n    └── AGENTS.md      # backend-specific rules\n```\n\nWorking 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.\n\nYour 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.\n\nIf this was useful:\n\n👉 **More React + AI tips daily** in my Telegram channel: t.me/novamind_hub\n\nI'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.\n\nBuilding with coding agents? Drop your biggest AGENTS.md pain in the comments — curious which conventions you enforce first 👇", "url": "https://wpnews.pro/news/stop-bloating-your-agents-md-reference-your-conventions-instead-of-pasting-them", "canonical_source": "https://dev.to/veaceslav/stop-bloating-your-agentsmd-reference-your-conventions-instead-of-pasting-them-b2i", "published_at": "2026-09-22 17:28:35+00:00", "updated_at": "2026-09-22 17:53:10.920672+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools"], "entities": ["Claude Code", "NovaMind", "Telegram"], "alternates": {"html": "https://wpnews.pro/news/stop-bloating-your-agents-md-reference-your-conventions-instead-of-pasting-them", "markdown": "https://wpnews.pro/news/stop-bloating-your-agents-md-reference-your-conventions-instead-of-pasting-them.md", "text": "https://wpnews.pro/news/stop-bloating-your-agents-md-reference-your-conventions-instead-of-pasting-them.txt", "jsonld": "https://wpnews.pro/news/stop-bloating-your-agents-md-reference-your-conventions-instead-of-pasting-them.jsonld"}}