Skip to content

Agentic Software Development

Context & Specifications

Writing Your First AGENTS.md (Without Triggering Context Rot)

From Agentic Software Development · 10 articles · latest

Diagram comparing a bloated 800-line prompt file causing attention dilution against a crisp 100-line AGENTS.md structure
Bloated 800-line instruction files dilute attention; a sharp sub-120-line AGENTS.md preserves working budget for actual code.

The worst mistake teams make right after adopting an AI coding assistant is treating AGENTS.md (or CLAUDE.md, or .cursorrules) like a municipal tax code. Whenever an agent makes one annoying mistake—forgetting a flag on pytest, picking requests instead of httpx, using camelCase in a snake_case module—someone appends another paragraph to the root instruction file. Six weeks later, you have an 850-line prose museum full of contradictory rules written by five engineers, and the agent ignores half of it.

We call that failure mode context rot. Every line you place in a root instruction file gets injected into the top of the model's attention window on every single turn, competing directly with the source files, compiler errors, and user task sitting beneath it. Once an instruction file grows past roughly 150 lines of dense prose, compliance rates drop visibly—not because the model is stubborn, but because you burned its prime instruction budget telling it how to format imports in a microservice it isn't even touching today.

Why AGENTS.md Beats Tool-Specific Rule Files

Historically every editor invented its own silo: .cursorrules, .windsurfrules, .github/copilot-instructions.md, and vendor-specific root files. Keeping three copies in sync guarantees drift within a sprint. That is why adopting the open, vendor-neutral AGENTS.md specification matters: it acts as a single, portable "README for coding agents" checked into your repository root, readable by CLI runners, IDE agents, and headless CI workers alike.

If a specific tool still insists on its own filename, symlink or one-line include it rather than maintaining duplicate rulebooks:

# Keep AGENTS.md as the single source of truth
ln -s AGENTS.md CLAUDE.md

If you run nested monorepos, keep the root AGENTS.md aggressively tiny—global commands and repo-wide invariants only—and place directory-scoped AGENTS.md files inside frontend/ or services/billing/ so agents only load billing-specific rules when working inside billing.

The Anatomy of a High-Signal Sub-120-Line AGENTS.md

Think of AGENTS.md like an emergency cockpit checklist, not an employee handbook. An effective root file fits comfortably under 120 lines and answers exactly four questions in priority order:

  1. How do I build, lint, and test quickly? (Exact commands, no guessing.)
  2. What architectural invariants must never break? (3–6 short bullets.)
  3. What am I strictly forbidden from doing? (Explicit "Never" boundaries.)
  4. Where do deep references live? (A pointer map so the agent pulls heavy docs on demand instead of loading them unconditionally.)

Here is a battle-tested template modeled directly on how we constrain workers across blogger-agent and Pressroom:

# Project Operations Guide (AGENTS.md)

## 1. Fast Verification Commands
- Unit tests (run after every edit): `pytest -q tests/`
- Single test file: `pytest -q tests/test_publisher.py -k "test_name"`
- Typecheck & lint: `ruff check scripts/ && mypy scripts/`
- Local dev server: `docker compose up -d db && uvicorn app.main:app --reload`

## 2. Repository Map
- `scripts/` — CLI entrypoints and shared client modules (`pressroom_client.py`)
- `tests/` — Pytest suite; fixtures live in `tests/fixtures/`
- `skills/` — Step-by-step runbooks for infrequent publishing workflows

## 3. Non-Negotiable Invariants
- All external HTTP calls MUST pass explicit timeouts (`timeout=15`).
- Reuse `PressroomClient` for API calls; never hand-roll `requests` calls to `/api/mcp`.
- Every public function requires concise Google-style docstrings.

## 4. Hard Boundaries (NEVER)
- NEVER modify existing database migrations under `alembic/versions/`.
- NEVER silence failing tests by relaxing assertions or deleting test cases.
- NEVER create scratch helper scripts in the repository root.
- NEVER commit secrets, API tokens (`prs_...`), or `.env` files.

## 5. Deep Context (Read Only When Relevant)
- Publishing & SEO metadata contract -> `skills/publish_to_roller/SKILL.md`
- Historical system friction & edge cases -> `PressroomFrictionPoints.md`

Notice what is missing from this template: there is no corporate mission statement, no 40-line style guide repeating PEP 8 (let ruff enforce syntax deterministically), and no tutorial on how Git works. Every line buys behavioral leverage that a linter cannot enforce alone.

Warning

Never put style formatting prose inside AGENTS.md: If a rule can be checked by ruff, eslint, prettier, or spotless, enforce it via a deterministic command in Section 1 instead of wasting prose tokens explaining indentation or quote styles.

Rule Pruning & Monorepo Scoping: Keeping Context Solvent

Once a codebase grows beyond one package, single-file rules break down even faster. If your frontend uses Next.js and Playwright while your backend uses Python and SQLAlchemy, keeping backend migration warnings inside the root AGENTS.md wastes tokens whenever an agent edits CSS. Keep the repository root strictly under ~80 lines (shared toolchain setup, security boundaries, commit format), and drop smaller 40-line AGENTS.md files inside subdirectories such as services/api/AGENTS.md or web/AGENTS.md. Most modern agent runners merge rules down the directory tree automatically—loading backend invariants only when the agent opens a backend file.

If you want your AGENTS.md to stay sharp six months from now, audit it monthly with a strict eviction rule: one in, one out once you cross ~100 lines. Whenever you notice the repo outgrowing a static cheat sheet—for instance, multi-step architectural rules or long API schemas—follow a multi-tiered context engineering hierarchy: offload deep reference material into searchable knowledge briefings as detailed in The Evolution of Wikantik 2.5 and the Wikantik Agent Context Guide, or isolate procedural checklists into skills.

Treat instruction bloat the same way you treat dependency bloat. As GitHub's own documentation on customizing repository instructions notes, concise, actionable commands consistently outperform sprawling prose guides. Pair this tight cockpit checklist with a 30-line task specification before every feature, and your agent will spend its context window reading code instead of wading through outdated rules.

Keep reading

Comments