DEV Community

Cover image for AGENTS.md Series Wrap: Five Lessons, FAQs, and What I'd Do Differently
wolfejam.dev
wolfejam.dev Subscriber

Posted on

AGENTS.md Series Wrap: Five Lessons, FAQs, and What I'd Do Differently

#ai #agents #devtools #productivity

TL;DR — Five posts. One file. The whole arc: what it is → write one → why it rots → keep it true → author from facts. This is the wrap: the map of the series, five FAQs, and the lesson that stuck — facts block vs unique prose.

📚 The AGENTS.md Series · you're on Part 6 — Series wrap

  1. I · field guide
  2. II · hands-on
  3. III · stale
  4. IV · keep it true
  5. V · from facts
  6. VI · series wrap — you're here

New here? AGENTS.md is a single Markdown file at the repo root that tells AI coding agents how to work in it — commands, tests, conventions, guardrails. Open standard under the AAIF / Linux Foundation. Start at Part I if you want the full path.

What we covered

Five lessons. One job: make the briefing agents obey true.

Part Role One line
I Field guide What belongs in AGENTS.md — and what doesn't
II Hands-on Build a real file, then point an agent at it
III The threat A stale file is still obeyed — at full confidence
IV Discipline Same-PR anti-rot, verify with an agent, keep truth current
V Endgame Author from repo facts so the file can't drift

If you only read one besides this wrap: III if you've never felt rot; V if you already have a file and want it to stop lying.

Step-through: how the arc fits

Read it as a single path, not five islands.

I   What is AGENTS.md?          →  principles, shape, anti-patterns
II  Write one                   →  real file, real agent payoff
III Watch it go stale           →  why "present" ≠ "true"
IV  Keep it true by hand        →  human discipline while the code moves
V   Stop hand-maintaining facts →  regenerate what the tree already knows
VI  This post                   →  map · FAQs · the lesson that remains
Enter fullscreen mode Exit fullscreen mode

I and II get you a file that works.

III and IV get you a file that stays honest under change.

V removes the class of lines that should never have been typed by hand.

VI (here) is the map and the judgment call: what still needs a human.

The series does not argue for a longer AGENTS.md. It argues for a truer one: a concise facts block, then your prose. Overall length is yours.

Five FAQs

1. Do I need AGENTS.md if I already have README / CONTRIBUTING / CLAUDE.md?

Yes, if agents work in the repo. README is for humans browsing. CONTRIBUTING is process. Vendor files (CLAUDE.md, etc.) are tool-specific. AGENTS.md is the tool-agnostic briefing many agents already look for. Keep it short; link out for depth. Don't duplicate a novel.

2. How long should it be?

Short enough that an agent (and a human) will still trust every line. Prefer commands you can run, paths that exist, and guardrails that bite. If a section can't be verified against the tree or a one-line rule, cut it or move it.

3. What's the #1 failure mode?

Stale truth that still looks official. Renamed scripts, dead test commands, structure maps that lag the tree — the agent obeys them at full confidence. Part III is the whole point. Freshness is not a nicety; it's the product.

4. Should every line be auto-generated?

No. Generate (or check) what the repo can prove: package names, scripts, layout, CI commands. Keep human what only a human owns: judgment, product "why," team norms that aren't in the tree, "never do X" that isn't a linter rule yet. Part V is the endgame for the facts half — not a replacement for judgment.

5. Where do I start if I have nothing?

  1. Part I — shape and anti-patterns
  2. Part II — write one and verify with an agent
  3. When it starts lying, IV then V

Don't skip III forever — you'll meet it the hard way.

My lesson: facts block vs unique prose

If the series leaves one idea standing, make it this.

Facts block Unique prose
What Things the repo already knows or can prove Things only a human should assert
Examples Build/test commands, package layout, entrypoints, CI checks Why the product exists, team taste, soft norms, hard "never" that isn't encoded yet
Failure mode Drift (tree moves, file doesn't) Vagueness or lecture that no agent can act on
Fix Author/check from the tree; fail CI on drift (V) Write short, actionable, owned by a human; same PR as the change when norms move (IV)

BETTER AGENTS.md = facts that match the tree plus prose that earns its tokens.

I used to treat the whole file as "documentation I should maintain." The series taught me to split the job: automate honesty for the map; reserve human attention for judgment. That's the difference between a file that exists and a file that deserves to be trusted.

What "good" vs "BETTER" looks like in practice

Good BETTER
File exists at repo root ✓ ✓
Agent can follow setup/test Often Commands match package.json / just / CI today
Structure / map Hand-wavy or partial Matches live tree (or deliberately points at it)
Stale lines "We'll fix later" Same PR as the change, or regenerate facts
Length Long and impressive Short and true

Goose, Cursor, Claude Code, Copilot, Codex — none of them need your autobiography. They need a briefing that won't send them into a renamed script at full confidence.

Q&A / feedback

This wraps the series for the AAIF Ambassador program — A practical, vendor-free AGENTS.md guide.

I'd like to hear from you:

  • Where does your AGENTS.md rot first (commands, structure, guardrails, something else)?
  • Did you try authoring from facts (Part V) — what broke?
  • What's still missing from the open AGENTS.md conversation that these five parts didn't touch?

Comment on this post, or open a discussion on a project you care about (for example: keep that repo's Structure true to crates/ / src/). The standard gets better when real trees push back on pretty docs.

Series index (bookmark this)

  1. AGENTS.md: The One File That Makes AI Coding Agents Actually Useful — field guide
  2. AGENTS.md, Hands-On: Build One Step by Step — tutorial
  3. Your AGENTS.md Is Already Stale (And Your Agent Trusts It Completely) — the threat
  4. AGENTS.md Kept True: Stop the Rot Step by Step — discipline
  5. AGENTS.md From Facts: Author One That Can't Drift — endgame tool path
  6. This post — wrap · FAQs · facts vs prose

Further reading: the standard itself at agents.md, and a section-by-section field guide — what earns a line, ordering, length, the anti-patterns — at faf.one/agents.

Thanks for reading the series.
Ship a short true file.
Then keep it true.
👍

Top comments (0)