DEV Community

Cover image for Stop bloating your AGENTS.md: reference your conventions instead of pasting them
Veaceslav
Veaceslav

Posted on

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

#agentsmd #aiengineering #webdev #programming

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`
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

Windows (order is reversed):

mklink CLAUDE.md AGENTS.md
Enter fullscreen mode Exit fullscreen mode

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
Enter fullscreen mode Exit fullscreen mode

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 👇

Top comments (0)