← all projects

Agent Docs Standard (ADS)

active

A standard for documenting repositories so coding agents get the right context when they need it, and nothing stale.

Jul 2026 – Present

  • AGENTS.md
  • Markdown
  • Python
  • Claude Code

Why it exists

Coding agents go wrong on documentation in four predictable ways: too little context, too much, docs that were stale the day they were written, and docs that rotted later. ADS is a profile of AGENTS.md designed against all four.

The principles

  • Context where it's needed. Every repository and module has its own AGENTS.md, linked to its parent, its peers and its dependencies, so an agent reads what matters where it works, not one giant file.
  • The always-loaded file earns its place. Explicit tests decide what an agent reads every turn and what it pulls on demand.
  • Docs describe, issues track. Plans and to-dos live in the tracker, so a doc can't go stale because a plan finished.
  • Decisions are dated and never edited. Everything else is written to stay true without a date.
  • Adoptable and checkable. Conformance levels, a dependency-free linter, and a Claude Code skill that retrofits an existing repository.

Where it stands

A draft spec in its second major version. It grew out of agent work in my day job, where I now bring its ideas into how we set up repositories for agents.