BACKLOG.md vs GitHub Projects: when a plain file beats a board

GitHub Projects is a proper product management surface. Custom fields, saved views, roadmaps, automation, the whole thing. BACKLOG.md is a text file at the root of your repo.

Those are not the same tool, and the choice matters more than it looks. Here is how they compare on the things that decide day-to-day work.

Source of truth

GitHub Projects stores items in GitHub's database. You reach them through the web UI, the GraphQL API, or a few third-party clients. If GitHub is down, or you move to a different host, or you want to grep your backlog from a shell, the data is not where your code is.

BACKLOG.md sits next to your code. It travels with the repo, ships in every clone, opens in every editor, and diffs in every pull request. When a teammate asks "what were we going to do about that Safari bug", the answer is grep -n Safari BACKLOG.md.

For teams whose real source of truth is the codebase, a file beside the code is a better fit than rows in someone else's database.

Editing friction

GitHub Projects is designed for adding items one at a time. Great for a product manager working through a triage session. Rough for a developer who wants to knock out five status updates between compiles.

A markdown file opens instantly, edits with the same muscle memory as any other file, and commits with the change that closed the item. No context switch, no separate tab, no waiting on a spreadsheet-style UI to hydrate.

If your backlog updates happen while you are already in the editor, a file wins on friction every time.

Views and filters

This is where Projects earns its complexity. Multiple boards, filtered tables, group-by-anything, iteration planning, custom fields. If your team runs sprints against a real roadmap, that structure pays for itself.

A plain file has none of that. You get one linear document with H2 sections. If you need burndown, custom statuses per team, and a monthly roadmap view, a file will feel thin fast.

A good compromise: use a file for the working list, and use Projects for the quarterly view. The file is where work moves; the board is where planning lives.

Readability for AI coding agents

This is the part that shifted recently. Agents like Cursor, Claude Code, Aider, and Copilot Chat read the files in your repo. A BACKLOG.md at the root is right there in context, no auth, no API, no rate limit. The agent can quote it, prioritize against it, and update it in the same commit as the code it wrote.

GitHub Projects is reachable through the GraphQL API, but most agents do not touch it by default. It sits behind a token, a schema, and a query. Even when an agent can reach it, the round trip is slower and the write path is riskier than editing a file.

If you want the agent to work from your real backlog, the backlog needs to be in the repo.

History and diffs

Projects has an event log. You can see who changed a field and when. It is fine, but it lives in a separate UI from your commits.

A file gets you git blame and git log -p BACKLOG.md for free. Every change is attached to a commit, an author, and usually a code change that explains it. When you want to know why an item was reprioritized, the answer is often in the same diff that reprioritized it.

Automation

Projects has real automation: move an item when a PR merges, auto-add issues that match a filter, iteration rollovers. If your team relies on that, do not walk away from it for a text file.

A file automates through git hooks and CI. Simpler, less magical, and it works with any host. It does not replace Projects automation, but for most small teams the manual edit is fine and the queue never gets long enough for automation to matter.

How to pick

Use GitHub Projects when:

• You run sprints or iterations with real ceremony.
• Multiple non-engineers edit the backlog (product, design, support).
• You need custom fields, saved views, or a roadmap surface.
• Cross-repo planning is a regular part of the week.

Use a BACKLOG.md file when:

• Engineers are the primary editors.
• You want backlog changes to ride in the same commits as code.
• AI coding agents are part of the loop and should see the list.
• Portability matters (self-hosted, air-gapped, or "we might move hosts someday").

Both is fine too. A lot of teams keep a file for active work and a Project for the quarterly view. The file changes hourly. The board changes on Monday.

The short version

GitHub Projects is a database with a good UI. BACKLOG.md is a file with git. If your work lives in code and your teammates (human and AI) live in the editor, the file has the shorter path to every decision that matters.