DEV Community

Cover image for AGENTS.md From Facts: Author One That Can't Drift (Step by Step)
wolfejam.dev
wolfejam.dev Subscriber

Posted on

AGENTS.md From Facts: Author One That Can't Drift (Step by Step)

#ai #agents #devtools #tutorial

TL;DR — Parts I–IV got you a real AGENTS.md and the discipline to keep it honest. This is the endgame Part IV pointed at: stop hand-maintaining lines the repo already knows. Author a minimal file from detected facts, protect human notes outside markers, fail CI when it drifts, point an agent at it. Six steps. One CLI. Facts only.

Series: I · field guide → II · hands-on → III · stale → IV · keep it true → you're on V.

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. If you haven't felt the payoff (or the rot), start at Part I.

Why the file still earns its keep

Twenty seconds on why AGENTS.md exists before we automate it:

Benefit What the agent gets
Faster first move Real setup / build / test commands — no guessing the runner
Self-check loop Tests as the bar for "done" — re-derive truth from the world
Less interruption Map + conventions — fewer "where do routes go?" questions
Fewer expensive mistakes Guardrails (always / ask first / never) + definition of done
One briefing, many tools Tool-agnostic Markdown — Cursor, Claude Code, Codex, Copilot, goose, Grok, peers

Short. Current. Specific. Actionable. Parts I–II covered what and how to write it. Parts III–IV covered why it dies and the human discipline that keeps it alive.

Part IV Step 5's honest endgame: regenerate from the repo so the file can't drift. This is that tutorial.

In one line: Part II taught you to write the file · Part IV taught you to keep it true · Part V hands you the tool — stop hand-maintaining what the tree already knows. Ready?

The trap

Two failure modes, both real:

  1. Hand-written and left alone → it rots. You rename a script; the agent still runs the old one at full confidence.
  2. "Let an AI write the whole file" → it bloats. Research (Gloaguen et al., 2026) found LLM-written instruction files can reduce task success and raise cost — plausible padding the agent over-obeys.

The fix is not more vibes. Facts only: every managed line traces to something the tree already declares — real scripts, real configs, real entry points. Nothing invented. Nothing padded.

That's agents-md-facts: a small CLI that authors a minimal AGENTS.md from repo facts. Open a real project and follow along.

Step 1 — Dry-run first

Any repo with a real package.json, pyproject.toml, Cargo.toml, or go.mod:

npx agents-md-facts --dry-run
Enter fullscreen mode Exit fullscreen mode

You get the plan — orientation, setup/build, tests, map, conventions, guardrails, definition of done — without writing a file. Sanity-check: are those the commands you actually run? If not, fix the scripts/config (source of truth), not the prose later.

Optional — managed block only:

npx agents-md-facts --stdout
Enter fullscreen mode Exit fullscreen mode

Step 2 — Author (or refresh) 

npx agents-md-facts
Enter fullscreen mode Exit fullscreen mode

Writes or refreshes AGENTS.md at the repo root. Managed region:

<!-- agents:from-facts:start -->
<!-- authored by agents-md-facts — from your repo's facts, never guessed · re-run to refresh -->

# AGENTS.md — your-project

…

<!-- agents:from-facts:end -->
Enter fullscreen mode Exit fullscreen mode

Non-destructive: everything outside those markers is yours. Re-run anytime; hand-written notes survive. Put tool quirks, domain gotchas, and "don't touch this without a human" outside the block. Author the rest from facts.

Step 3 — Read it like an agent

Open the file. Shape for a small Node/TS example (exact style from the tool's examples):

Orientation

TypeScript · Node.js · npm package manager · v1.0.0

Setup & build

npm install    # install dependencies
npm run build    # build
npm run dev    # dev
Enter fullscreen mode Exit fullscreen mode

Run the tests

npm run test
npm run lint
Enter fullscreen mode Exit fullscreen mode

Where things live

  • package.json
  • src/index.ts
  • tsconfig.json

Conventions

  • TypeScript strict mode (tsconfig.json)
  • ESM modules (type: module)
  • Style enforced by ESLint · Prettier — obey the configs

Guardrails

  • Always OK: read files, run the tests (npm run test), build the project.
  • Ask first: dependency installs, deletions, migrations / schema changes.
  • Never: force-push, commit secrets.

Definition of Done

Done when: npm run lint exits 0 · npm run test passes · committed with a clear message.

Part IV rules, automated:

  • Commands copy-pasteable and backticked as literals
  • Tests where the agent needs a feedback loop
  • Conventions point at configs — don't restate "use 2 spaces"
  • Guardrails enable-first (always / ask / never)
  • Definition of Done mechanically checkable

If a line wouldn't resolve an ambiguity for a fresh agent, the tool drops it. Short by construction.

Step 4 — Human layer (outside the markers)

Facts can't know product judgment. Below the end marker (or above the start), add what only you know:

<!-- agents:from-facts:end -->

## Project notes (human)

- Prefer the query builder in `src/db/` — no raw SQL in handlers.
- Feature flags live in `src/flags.ts`; don't hardcode rollout in routes.
- Billing code is off-limits without a human in the loop.
Enter fullscreen mode Exit fullscreen mode

Next refresh leaves this intact. Machine-owned facts inside · human-owned judgment outside.

Step 5 — Make drift a build failure

Part IV's anti-rot rule: AGENTS.md changes in the same PR as the code. Automate it.

Local / CI:

npx agents-md-facts --check
Enter fullscreen mode Exit fullscreen mode

Exits 1 if missing or the managed block is stale vs the repo.

GitHub Action:

# .github/workflows/agents-md.yml
name: AGENTS.md
on: [push, pull_request]
jobs:
  check:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: Wolfe-Jam/agents-md-facts@v0.1.0
Enter fullscreen mode Exit fullscreen mode

Pre-commit:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/Wolfe-Jam/agents-md-facts
    rev: v0.1.0
    hooks:
      - id: agents-md-facts
Enter fullscreen mode Exit fullscreen mode

Then: pre-commit install.

When scripts or layout change, fix in the same PR:

npx agents-md-facts
Enter fullscreen mode Exit fullscreen mode

Treat the file like code — because your agent already does.

Step 6 — Verify with an agent

Same proof as Parts II and IV. Small real task:

"Add a tested /health endpoint."

Watch for:

  1. It reads AGENTS.md first.
  2. It runs the exact test/lint commands from the file.
  3. It respects Always / Ask / Never.
  4. It hits Definition of Done without you re-explaining the toolchain.

If it runs the wrong command or ignores a convention, the file (or the underlying scripts) lied — fix the fact source, re-author, re-check. Don't scold the agent for trusting the briefing you gave it.

What this does not replace

Still yours Why
Judgment outside markers Facts don't know billing, legal, or when to "ask the Owner first"
README for humans AGENTS.md = how to work; README = what/why
Code review A true file helps the agent; humans still ship
Lint of your prose Complements bloat-linters — this authors clean from truth

You can still hand-write the whole file (Part II). You can still run Part IV without a generator. The CLI is for lines that should never have been hand-copied from package.json in the first place.

The loop, closed

Part What you learned
I What belongs · anti-patterns · short > complete
II Build section by section · watch an agent use it
III Stale cache worse than empty · facts only
IV Same-PR updates · point-at-config · enable-first guardrails
V (this) Author from facts · markers · --check · CI · agent verify

Short. Current. Specific. Actionable. And now re-derivable from the tree — so the agent stops inheriting last sprint's lies.

Where to go deeper

Series: I · II · III · IV · V (you are here)

⭐ If this saved you a hand-written or LLM-bloated AGENTS.md, a star on the repo helps others find it.

Keep the facts honest. Your agent only ever trusts the last true thing you told it.

Top comments (0)