Agentic coding: why AGENTS.md should stay lean

If you are using agentic coding seriously, one of the first things to do is not to cram as many instructions as possible into AGENTS.md or CLAUDE.md.

Do the opposite: keep those files as lean as you can.

I see it often: repositories where everything ends up inside. Policies, conventions, workflows, domain details, operational instructions, obvious notes, database structure, exceptions, naming, checklists.

The problem is not good intentions. The problem is the effect on the model.

Saturating the context window does not help

When you put everything in a single guide file, you are not helping the agent. You are saturating the context window.

You force it to process information that may not matter for that specific task. You add noise, burn tokens, and often worsen decision quality.

The agent does not automatically separate what is essential from background noise. It reads what you pass in. If you pass everything, every time, the signal dilutes.

In agentic coding, quality does not depend only on the model you use. It depends on how well you design the context in which that model works.

Often, less fixed context means more precision, because there is less noise to filter out.

An operational index, not a full manual

AGENTS.md and CLAUDE.md should be treated more like an operational index than a complete manual.

Core rules stay there: project purpose, tone, non-negotiable constraints, where to find the rest.

Everything else should be distributed.

Not because the other information does not matter. Because it should appear when it is needed, not always.

Rules: constraints and principles

Rules (in the Cursor sense, or equivalents in your stack) define stable constraints and principles.

Typical examples:

• how the database is modeled
• API conventions
• naming and folder structure
• security and secrets
• migrations
• documentation governance

These are rules you want respected consistently, often across many tasks. But the same minimum-necessary principle applies: one rule per concept, not a novel.

Skills: reusable operational procedures

Skills become reusable operational procedures, invoked when the task requires them.

For example:

• how to create an endpoint
• how to run an AI-safe migration
• how to update an existing workflow
• how to open a PR following the team process

Here the LLM does not need to read everything every time. It needs to understand what it needs, when it needs it, and retrieve only useful context.

That is a huge difference compared to one mega-file.

What changes in practice

When you design context well:

1. Focused tasks — the agent starts with a few global rules and loads skills or documents only if the work requires them.
2. Fewer overload hallucinations — fewer contradictions between sections written at different times in the same bloated file.
3. Easier maintenance — you update the migration skill without touching twenty paragraphs scattered through AGENTS.md.
4. Better human onboarding — even for people who do not use the agent, the structure stays readable.

The opposite risk is under-documentation: lean but empty files with no pointers. The index must say where to go, not pretend to be the only source.

A concrete example

In a web project you might keep in AGENTS.md:

• site purpose and tone
• stack in one line
• build/lint commands
• mental links: rules for DB/API, skills for deploy or for adding a blog post

Outside that: the pre-PR checklist, the database schema, the migration procedure, bilingual copy conventions.

The agent adding a database field does not need footer tone policy. The one writing copy does, but does not need the full migration schema.

Separating is not pedantry. It is respect for the context window.

Closing

Agentic coding is not about having the largest model or the longest instruction file.

It is about designing a system where the model receives little, relevant context at the right moment.

Slimming down AGENTS.md does not mean less discipline. It means stopping using one file as a dump for everything and starting to treat context as something you compose.

More index, less encyclopedia. More precision, less noise.