Document As You Go

A drop-in system prompt and slash command that make a coding agent capture what it learns while it works — instead of letting the knowledge evaporate when the session ends.

The problem

Agentic sessions generate two kinds of documentation debt.

The familiar one is code documentation: decisions get made and constraints get discovered mid-session, and by the time anything is written down the reasoning is gone. What gets produced instead is a description of the code, which nobody needs.

The less obvious one — and the more expensive — is discovery debt. Ask an agent to pull expense data out of an accounting platform for a tax return, and it may end up reverse-engineering that platform's undocumented internal API to get the job done. The task succeeds. The API knowledge disappears. Six months later the same work starts from zero.

That knowledge was a real product of the session. It was just never treated as an output.

What this does

The prompt establishes four habits, performed without being asked and never allowed to displace the actual task:

Capture what you discover. When the agent learns something it had to reverse-engineer — an internal API's shape, an auth flow's real requirements, the true structure of an export, the sequence of steps that worked after four that didn't — it writes it down. Where depends on reach:

Reach of the finding	Home
Beyond this task, about a system that will come up again	A dedicated knowledge repository for that subject, private by default
This project only	docs/ in the current repository — written without asking
Right now only	The reply. Nothing on disk.

Document what you change. Decisions and the constraints that settled them, non-obvious constraints, workarounds with removal conditions, new configuration — shipped in the same commit as the change, routed to one durable home each.

Document what you fix. A fix is not finished when the symptom stops. Diagnosis is the expensive part of debugging and the patch is usually a line or two, so shipping only the patch discards the expensive half. The agent records what the symptom looked like, what it actually was, what fixed it, and the wrong turns — the parameter that was rejected, the field that read as authoritative and wasn't. The small findings matter most, because they are the ones nobody writes down.

Treat the repository as a workspace. A repo holds more of a project's durable output than its source: worked examples, scripts worth running again, redacted fixtures showing the real shape of the data, diagrams. The agent files those too, and where the folder it needs does not exist — docs/, examples/, scripts/ — it creates it as it files the first thing that goes in, without asking. An absent folder is an absence, not a prohibition. Structure grows behind content, never ahead of it, and nothing sensitive gets committed into any of it.

And, just as importantly, a list of what not to write: no restating the diff, no SUMMARY.md or IMPLEMENTATION_NOTES.md or dated work logs, no parallel second document on a subject that already has one. Writing nothing is frequently the correct outcome.

Contents

prompts/document-as-you-go.md   Full prompt — paste into CLAUDE.md / AGENTS.md
prompts/compact.md              Short version for tight token budgets
commands/document-as-you-go.md  Slash command — the retroactive sweep
docs/knowledge-repo-template.md Suggested layout for a knowledge repository
docs/adapting.md                Porting to Cursor, Codex, Copilot, Aider, raw API
docs/rationale.md               Why each rule is there
install.sh                      Installs the slash command

Install

The prompt

Append prompts/document-as-you-go.md (everything below the horizontal rule) to your instruction file:

• Claude Code, all projects — ~/.claude/CLAUDE.md
• Claude Code, one project — ./CLAUDE.md
• Codex, Jules, and others using the open convention — AGENTS.md
• Cursor — a new file under .cursor/rules/
• Anything else — the system prompt

Use prompts/compact.md instead if your instruction file is already large. See docs/adapting.md for per-tool notes.

The slash command

./install.sh              # → ~/.claude/commands/document-as-you-go.md
./install.sh --project    # → ./.claude/commands/document-as-you-go.md

Or copy it by hand:

cp commands/document-as-you-go.md ~/.claude/commands/

Use

With the prompt installed, capture happens on its own — the agent notices durable findings mid-task and files them, or proposes a new repository when a finding outgrows the project it was found in.

The slash command is the retroactive sweep, for sessions that ran without the prompt or wandered further than expected:

/document-as-you-go              # both passes: findings and code changes
/document-as-you-go --findings   # discoveries only
/document-as-you-go --check      # report what's missing, write nothing

It always proposes before it writes.

Design notes

• Findings are proposed, repositories are not created silently. In-repo documentation is written without ceremony; a new repository is a one-line proposal first, and private unless stated otherwise.
• Cold-readable or it doesn't count. A finding is written for someone who was not in the session: concrete endpoints and field shapes, identifiers redacted, credentials referenced rather than pasted, failures included, and an absolute verification date — undocumented APIs change without notice, and an undated finding can be neither trusted nor retired.
• Capture never displaces the task. It is a side effect of the work, not a substitute for it, and not a reason to stop mid-task.
• Structure grows behind content. The agent creates the folder it needs when it has the first file to put in it — never a scaffolded tree of empty directories, which reads as abandoned and tells a reader nothing.

Licence

MIT — see LICENSE.