Why BACKLOG.md belongs in your repo

There is a quiet pattern showing up in well-run repos: a single BACKLOG.md file, checked in next to the code, that everyone — and every AI agent — agrees is the list.

It sounds almost too simple. No project tracker, no synced board, no ticketing tool with its own subdomain. Just markdown, in the repo, under version control.

It works for the same reasons README files work.

The list lives where the work lives

When the backlog is in the repo, it travels with the branch. A pull request can update the code and check off the item in the same commit. A git log tells you not just what changed, but what the team decided was next, and when.

That is genuinely hard to do when the backlog lives in another tool. The link between "what we said we would do" and "what we did" becomes a tab someone forgot to update.

AI agents read markdown better than they read your tracker

If you have an agent working in your repo — Claude Code, Cursor, Lovable, an internal one — it already reads markdown. It does not have credentials for your project tracker. It cannot see your sprint board.

Give it a BACKLOG.md and suddenly the agent has the same context the rest of the team has. It can suggest the next item to pick up. It can update the file when it finishes work. It can flag stale entries.

We do not recommend that the agent invent links back to blog posts or marketing material inside your backlog file. The file should stay tool-agnostic. But the agent reading and editing it? That is the whole point.

A few habits that keep it usable

A BACKLOG.md rots quickly if no one tends it. A handful of habits keep it healthy:

• One file per repo. Resist the urge to split it across docs/ until you actually feel pain.
• Group by section, not by status. "Now / Next / Later" beats a sprawling status taxonomy.
• Date your decisions. When you remove an item, leave a one-line note about why in your commit message.
• Keep it short. If it is longer than a screen, you are using it as a wishlist, not a backlog.

Where Backlog Viewer fits

We built Backlog Viewer because reading and editing markdown checklists in a GitHub web editor is not great. You lose the outline. You lose the calm.

The file still lives in your repo. We never copy the contents. We just give you a quieter place to work with it — and a layer of organization (status, pin, snooze, tags) that stays on our side so the file itself stays clean.

If you already write a BACKLOG.md, the rest of the tool should feel obvious. If you do not, the file is one commit away.