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

> Source: <https://dev.to/veaceslav/stop-bloating-your-agentsmd-reference-your-conventions-instead-of-pasting-them-b2i>
> Published: 2026-09-22 17:28:35+00:00

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 👇