Coding Agent Onboarding: Writing AGENTS.md That Actually Works

In August 2026, The New Stack published a sharp observation: "Your coding agent got the onboarding your developers never did." Google's 2025 State of AI-assisted Software Development report found adoption has reached 90% of organizations — a 14-point jump in a single year. But the benefits are not realized evenly. AI amplifies your existing software delivery: strong engineering systems get stronger, and dysfunctional ones get more chaotic. What determines which you get is the quality of the onboarding you write for your agents.

AI agents in the modern dev workflow

1. Agent Onboarding: What AGENTS.md Is

Coding setups for agents now include one or more files written for coding agents: AGENTS.md, CLAUDE.md, GEMINI.md. These plain-text or Markdown files contain tech stacks, build and test commands, off-limits directories, and team conventions. The New Stack notes that many organizations (such as Sourcegraph) are rushing to create and maintain these agent onboarding documents — a treatment human-facing documentation never got: shelved indefinitely, delegated to the new joiner with the least context, or left to rot until the one engineer who understood the 'why' leaves.

# AGENTS.md — the agent's onboarding document
# Best practice: keep it under 60-300 lines. Every line is
# re-read in EVERY session, so it must earn its place.
# (The HumanLayer team keeps theirs under 60 lines)

# Stack
- Next.js 16 + Tailwind + next-intl, TypeScript strict
- Tests: vitest (unit) + Playwright (e2e)

# Commands
- npm run dev       # local dev
- npm test          # unit tests, must pass before merge
- npm run build     # required before every push

# Off-limits
- src/lib/tools.ts  # 1100+ tool metadata, NEVER edit casually
- *.config.prod.ts  # production configs, human approval only

# Conventions
- i18n: every user-facing string in zh + en
- Small batches: max 5 files per PR

2. Why Agent Docs Don't Decay

Unlike developer documentation, the agent onboarding file doesn't decay after creation. Teams continuously optimize it to improve task success and reduce inference costs. The team behind HumanLayer's agent tooling keeps their file under 60 lines — well inside the sub-300-line range now considered best practice — because every line gets re-read in every session, so it needs to earn its place. Wiki-style human docs rarely get that treatment.

# CLAUDE.md / GEMINI.md: per-tool variations
# Keep the SAME core facts, tune the format per agent
---
model_hint: claude
pinned_files:
  - AGENTS.md          # always read this first
  - src/lib/schema.ts  # source of truth for data shapes
tone: concise
max_output_tokens: 4000
---
# Never invent function signatures. Verify against
# src/lib/api/client.ts before writing call sites.

3. The Faros AI Data: Context Switches Are Drowning Everyone

The strain of skipping discipline shows up in the data. Telemetry from Faros AI covering 2026 found developers working with AI assistance juggle 67.4% more pull-request contexts and 17.7% more task contexts per day than before (up sharply from 47% and 9% in the prior year), work restarts are up almost 14%, and more than a quarter of in-progress tasks now sit untouched. "Both the humans and the agents are drowning in context switches that better batching would have prevented."

# The 2026 data: why context quality is a competitive edge
# Google's 2025 State of AI-assisted Software Development:
#   adoption reached 90% of organizations (+14 pts in a year)
# Faros AI telemetry (2026):
#   devs juggle 67.4% more PR contexts per day
#   17.7% more task contexts per day
#   work restarts up ~14%
#   >25% of in-progress tasks sit untouched
# AI amplifies existing delivery systems — strong teams
# get stronger, dysfunctional ones get more chaotic.

4. Small Batches: The Shared Cure for Humans and Agents

DORA has spent a decade producing evidence that working in small batches reduces risk and speeds up delivery. This was waved off as an inconvenience when humans made the changes; but with large changesets tripping up the agents doing code review, shrinking batch size suddenly makes sense. Best practice: split features into batches of at most 5 files — agent implements, runs tests, human reviews, agent fixes per feedback. Both sides stay in the loop.

# Small-batch workflow that agents and humans can both follow
# DORA evidence: small batches reduce risk and speed delivery
def plan_work(feature):
    batches = split_into_batches(feature, max_files=5)
    for batch in batches:
        agent.implement(batch)
        agent.run_tests()
        human.review(batch)      # both sides stay in the loop
        if human.requests_changes:
            agent.fix(batch)     # small diff = fast correction
    return merge_all()

# "Both humans and agents are drowning in context switches
#  that better batching would have prevented."

5. A Practical Checklist for Writing AGENTS.md

A production-grade AGENTS.md contains at least five blocks: the stack (framework + strictness), commands (dev/test/build, noting what must run before every push), off-limits (critical files and production configs agents must not touch), conventions (e.g., bilingual i18n, PR size caps), and a fixed entry point (what to read first). Keep it between 60-300 lines; every line needs a reason to exist.

6. Treat the Onboarding Doc as a Product

The final mindset shift: treat AGENTS.md as a product, not documentation. Measure its quality with task success rates, token consumption, and rework rates; when an agent misbehaves, ask 'was the onboarding unclear?' before blaming the model. In 2026, what separates winning AI teams is often not model selection, but how much care you put into that agent onboarding document.