Structuring BACKLOG.md so AI agents can actually work with it

If you work with AI coding agents, your backlog is no longer just for you. The agent reads it too, and if the structure is fuzzy, its edits will be fuzzy.

A good BACKLOG.md gives the agent three things: stable identifiers, predictable sections, and enough context per item to act without guessing. Everything below is what has held up for us across projects.

One heading level, one item

Use an H3 per work item. Not H2 (those are section groupings), not a bullet list (agents lose track of which line belongs to which item).

## Next

### Add priority filter to dashboard
Why it matters: teams with 50+ items can't scan the list.
When to revisit: this week.
Notes: keep the filter state in the URL so links are shareable.

### Fix Safari drag bug on the item list
Why it matters: half of testers use Safari.
Notes: repro at github.com/example/issue/42.

The H3 title is the item's identity. Agents can find it, edit it, or move it under a different H2 without ambiguity. A bullet list would force them to guess where an item ends.

Three fields per item, in the same order

Agents do best with a small, fixed schema. Ours:

• Why it matters — one sentence on the impact.
• When to revisit — a rough date or trigger, or omit if it's active.
• Notes — anything else: links, repro steps, gotchas.

Same order every time. When the agent updates an item, it edits fields in place instead of reshuffling.

Group by status, not by area

One H2 per status: Next, Later, Done. Not by area, not by team, not by priority. Status is the thing that changes most often, and moving an item between H2s is a clean structural edit any agent can make correctly.

Areas and priorities are better expressed as inline tags (#billing, #p1) inside the item, where they don't fight the outline.

Keep metadata out of the file when you can

Pin state, snooze dates, per-user tags — these belong somewhere else (a sidecar database, your issue tracker's API, an app that manages the file for you). If you jam them into the markdown as YAML front-matter per item, the agent has to parse two formats and will occasionally corrupt one.

The rule: if a human wouldn't read it, it doesn't belong in the file.

Give the agent a header block

Start the file with a short section that explains the format. Not for you — for the agent, on the next turn.

# Backlog

Format: one H3 per item. Fields are optional but always in this order:
Why it matters, When to revisit, Notes. Group items under H2 status
headings: Next, Later, Done.

This costs a few lines and saves whole categories of misedits. When you switch agents or open a new session, the file explains itself.

What this buys you

• Agents edit items in place instead of rewriting the file.
• Diffs are small and reviewable.
• The file stays readable in a plain editor, on GitHub, in your terminal.
• You can hand it to a new tool tomorrow without a migration.

A backlog is one of the cheapest artifacts to get right and one of the most expensive to get wrong. A little structure up front pays back every time an agent touches it.