A new coding-agent session starts in an odd position. It can read every line of code and none of the discussion that led to it.
Ask it to change a feature you built two weeks ago and familiar questions come back:
Why does this form have only three fields? Why does the free plan stop here? Why does this screen ask for approval before continuing?
The answers may be in an old chat. They may be in your head. Neither is a good place for a decision that the next session needs.
AI lets a small team make more changes, but those changes also pass through more short-lived conversations. At Journeys, we decided to keep the useful parts of those conversations in the same repository as the code.
A backlog the agent can open
Most software backlogs live in Jira, Linear, GitHub Issues, or another planning tool. That is where they belong for most teams. Those products provide comments, notifications, assignments, roadmaps, and reporting that a folder of text files does not. GitHub itself treats Issues and Projects as planning tools connected to a repository, rather than files within it. See GitHub’s guides to planning work and Projects.
Our backlog has a narrower job: give the person or agent implementing a task the reason behind it.
Every feature, bug, or larger chore is one Markdown file in the repository. The file explains:
- the problem we are trying to solve;
- what someone must be able to do when the work is finished;
- constraints the change must respect; and
- decisions and verification recorded along the way.
A repository-native backlog is a product brief that travels with the product it describes.
The folders carry status:
backlog/
todo/
doing/
parked/
done/2026-08/Starting work means moving a task into doing. Finishing means recording what
was completed and moving it into done with the code change. A script produces
the readable queue, so nobody maintains a second status table by hand.
We are not trying to create a new project-management category. We want the brief to be available where the coding agent already works.
I could not find credible industry-wide data showing how many teams keep their backlog this way. There are examples, but not enough evidence to call it a standard practice. Emerging is more accurate.
The repository becomes product memory
Coding agents can search files, trace behavior, run tests, and propose changes. They cannot recover a product conversation that was never written down.
A task file fills part of that gap. Before changing a feature, the agent can read why the task exists and what the outcome must be. A human can review that brief before implementation creates momentum around the wrong assumption.
The file survives a new session, a different coding tool, a branch change, or a founder forgetting the detail six months later.
Repository instruction files help the agent find it. Codex reads AGENTS.md;
Claude Code uses CLAUDE.md. Those files are useful for stable rules such as
the architecture, commands, and workflow. See the official documentation for
Codex project instructions
and
Claude Code project memory.
We do not paste the whole backlog into those files or every prompt. Our project instructions point to a compact work index, and the agent opens the one ticket it needs. The rest remains searchable without crowding the session.
The idea has older roots. Docs-as-code already keeps documentation with the system and reviews its changes. Architecture decision records preserve the context and consequences of choices that would otherwise be forgotten. See GitLab’s documentation workflow and Microsoft’s ADR guidance.
AI-oriented tools are extending the same pattern. Kiro stores requirements,
design, and task files under .kiro/specs/ and recommends version-controlling
them so both a team and an agent can use them during implementation. See
Kiro’s specification guidance.
This does not make the agent correct
Good context does not rescue poor implementation. An agent can misunderstand a clear requirement, introduce a regression, or fail at work that requires more skill than context.
The available research is mixed. A controlled study of 288 evaluations across Claude Code and Codex found no measurable correctness improvement from always-loaded or selectively retrieved context files on its 17 tasks. The authors found that implementation skill was often the limiting factor. See Do Context Files Help Coding Agents?.
Another observational study associated more structured repository practices with smaller increases in complexity and static-analysis warnings after teams adopted coding agents. Its authors identify possible reverse causality and other limitations. See A Few Pages of Markdown.
We can defend a smaller claim from our own experience: the reason for a change no longer disappears with the chat. Tests, product judgment, and technical review still have to prove the result.
This practice is not for every product
A repository-native backlog works best when a founder or small team controls a Git-backed codebase and coding agents handle a regular share of the implementation.
It gets awkward when many teams need one roadmap, customers submit work, commercial plans are confidential, or non-technical colleagues must manage the queue. A hybrid may be enough: keep planning in the normal tool and commit only the implementation-ready brief beside the code.
If your AI website builder does not expose a repository, you cannot use this workflow. You still need an answer to the same question: where will the next session find the reason behind today’s decision?
“Somewhere in the chat history” is not a dependable answer.
Try it with one feature
Do not migrate your whole roadmap.
Pick one feature you are about to build. Add a text file containing the problem, the successful outcome, the constraints, and the unresolved questions. Ask the agent to read it first. Review the file before asking for code.
When the work is complete, record what changed and how you checked it.
Return in a later session. If the file saves you from reconstructing the same conversation, keep it. If it only duplicates a tracker that already gives the agent enough context, remove it.
For us, that is enough. The next agent can find the decision without asking us to retell the conversation.