Guides / Building software with AI agents

Why we built QnA MD: agent questions that outlive the chat

Why an AI agent's questions and decisions belong in a Markdown file as hidden HTML-comment tags: git-friendly, invisible when rendered, offline and phone-first.

Product help

By Steven Michael Barber · Published October 19, 2026 · Updated November 3, 2026 · 6 min read

An AI coding agent working through a task will sooner or later hit something it should not decide alone: whether to drop support for an old version, which of two designs to build, whether a price is right. In a chat window it asks, and the question sits in the transcript. If the person is away, the agent either waits or guesses. If they answer an hour later, the answer is in that one conversation. The next session starts with no memory of it, and the same question comes back a week later, sometimes with a different answer.

We build our products with agents, and this happened to us often enough that we wrote a small tool for it. QnA MD is the result: a way to keep an agent's questions, and the answers to them, inside an ordinary Markdown file. This guide explains the reasons behind each design choice. The tag grammar itself is in the file format guide.

Where questions get lost

Questions from an agent end up in three places, and each has a problem.

• The chat transcript. It holds the answer, but nothing else reads it. A new session, a second agent or a colleague cannot find it, and an archived conversation takes it along.
• An issue tracker. It is durable and can hold a whole checklist in one issue. For our small decisions, though, moving questions out of the document meant another place to read and maintain. A tracker may be the better fit when a team already handles decisions there.
• Comments in the code or a pull request. They sit close to the work, but they are scattered across files and branches, and nothing lists which ones still wait for an answer.

What we wanted was one place that both the agent and the person already use, that keeps its history, and that the next session will open anyway.

Why a Markdown file

Agents already read and write Markdown all day: plans, design notes, READMEs, decision records. A Markdown file sits in the repository next to the code it concerns, so git versions it, a diff shows exactly what changed, and the next agent session reads it like any other file. Nothing has to be installed or signed into, and if QnA MD disappeared tomorrow the file would still open in any text editor.

The question then was how to put structured questions into a document without spoiling it as a document.

Why hidden HTML comments

CommonMark, the specification most Markdown renderers follow, passes HTML comments through as raw HTML, and a browser does not display a comment. So a question written as <!-- oq:choice #rel-03 … --> is invisible on GitHub, in a wiki or in a static site, while the prose around it reads normally. The same file is a readable plan for people and a question list for the agent.

Comments also let a question sit right under the paragraph it is about. QnA MD shows that paragraph above the question card, so the person answering sees the context the agent saw.

Worked example: one question, before and after

An agent preparing a release notices the upgrade guide still mentions Node 18 and stages this question in the plan file:

## Release 2.4

The upgrade guide still tells people to install Node 18.

<!-- oq:choice #rel-03
by: @agent 2026-10-14T21:10Z
to: @maria
status: open
Q: Drop Node 18 support in release 2.4?
- [ ] A. Yes, drop it in 2.4 (rec)
- [ ] B. No, keep it until 3.0
why: Node 18 reached end of life in April 2025, and two test jobs exist only for it.
ref: docs/upgrade.md
log:
-->

Rendered, the file shows only the heading and the sentence about the upgrade guide. In QnA MD, the question appears as a card with two buttons, A marked Recommended. Maria taps A, adds a short comment and taps Answer. The editor rewrites only that tag:

## Release 2.4

The upgrade guide still tells people to install Node 18.

<!-- oq:choice #rel-03
by: @agent 2026-10-14T21:10Z
to: @maria
status: resolved
Q: Drop Node 18 support in release 2.4?
- [x] A. Yes, drop it in 2.4 (rec)
- [ ] B. No, keep it until 3.0
why: Node 18 reached end of life in April 2025, and two test jobs exist only for it.
ref: docs/upgrade.md
log:
- @maria 2026-10-15T07:42Z answer: A. Yes, drop it in 2.4 — after the 2.3.2 patch ships
-->

Three lines changed: the status, the check mark and one log line. That is the whole diff git will show. The next agent session that reads the file sees a resolved question, the chosen option and the condition Maria added, without needing the conversation in which the question was first raised.

Phone first, offline, no account

Most of the time an agent's questions are waiting, the person who can answer them is away from a desk. So QnA MD is built for a phone: one question at a time, large buttons for options, a text box that accepts dictation, and a Review tab that shows only the items addressed to you.

It runs in the browser and keeps working with no signal once it has loaded. There is no account and no server: the file is opened from the device, the answers are written into it on the device, and it goes back by saving it in place, downloading it or copying the Markdown. We chose this partly for privacy, since plans and decisions are often confidential, and partly because a tool with no backend has nothing to keep running.

What the log records, and what it does not

Every answer is written as a log line with a handle and a UTC timestamp to the minute. That gives each file a readable account of who answered what, and when, which is most of what a team needs when it later asks why something was done.

The handle is a name the person types, like a git author name. It is not a verified identity and not a cryptographic signature, and anyone who can edit the file can edit the log. When provenance matters, the commit history around the file is the stronger record. The format does not pretend otherwise.

The trade-offs we accepted

A file instead of a service means no push notifications, no live collaboration and no automatic sync. If two people edit the same tag in two copies, the copies have to be merged like any other text, which is why each answer touches as few lines as possible. QnA MD does not validate an answer beyond the tag format, and it calls no AI model.

The free web app is available at /qnamd/. The tag format is at version 0.1, and its public reference describes the current draft. We plan to publish the specification under the Creative Commons Attribution 4.0 license so that other tools can read and write the same files. More about the shipped product is on the QnA MD product page.

For practical patterns, see QnA MD use cases. For how an agent can collect a whole round of questions and have them answered in one sitting, see batch processing and the agentic development life cycle.