AGENTS.md, Hands-On: Build One Step by Step (and Watch an Agent Use It)

In the field guide I covered what an AGENTS.md is and what belongs in it. This is the hands-on follow-up: we'll build a complete AGENTS.md for a real project, one section at a time, then point an AI coding agent at it and watch the difference it makes. By the end you'll have a working file — and you'll have seen it pay off. New to AGENTS.md? It's a single Markdown file at the root of your repo that tells AI coding agents how to work in it — build steps, tests, conventions, guardrails. The "why" behind each section is in the field guide . The project we'll use We'll write the AGENTS.md for a small but real service: a URL shortener API in Python — FastAPI, SQLite, pytest. A couple of endpoints, a thin data layer, a test suite. Follow along with this, or swap in your own repo — the steps are identical. Its shape: linkshort/ app/ main.py # FastAPI routes db.py # SQLite access models.py # Pydantic models migrations/ # generated SQL — not hand-edited tests/ requirements.txt Step 0 — Start with an empty file At the repo root: touch AGENTS.md That's the whole step. We'll fill it in one section at a time, building toward a file an agent can read in thirty seconds. Step 1 — Orientation: one line Tell the agent what it's looking at. Add: # AGENTS.md A URL shortener API in Python — FastAPI, SQLite, pytest. One sentence sets the agent's priors: it knows the language, framework, and storage before it reads a single line of code. Step 2 — Setup and run The agent can't help if it can't start the project. Add the real, copy-pasteable commands: ## Setup python -m venv .venv && source .venv/bin/activate pip install -r requirements.txt ## Run uvicorn app.main:app --reload # http://localhost:8000 Use the commands that actually work in your repo — no placeholders. Step 3 — Tests: the agent's feedback loop This is the most important section, because tests are how the agent checks its own work. Add: ## Test — all must pass before a change is done pytest ruff check . mypy app Now the agent