Skip to content

Document an AI-built app: a template

Step 7 of 10 in the builder spine.

The minimum is the one-page app record: purpose, tier and why, people, data (classes, sources and where it's stored), how it works at a high level, connections, tests and checks, decisions made, and where the change log lives. From Important, add a runbook that says how to run, restart and restore the app and what its known limits are. Update both with every change, so someone other than you can run the app from them.

Who this is for

Builders writing the record for their own app, and app owners who must sign it off. You get each field with the reason it's there, what an AI tool may draft and what a person must write, and what each tier requires. About 8 minutes.

What goes on the one page?

The copyable version is the app record in the app record template. Copy it into your documents tool. This page explains each field so you fill it in properly. Get the app record template (CSV and guide); the worksheet is the file, and this page explains the fields.

Field What to write Why it matters
Purpose One or two sentences: what it does, for whom, and what it replaced Without it, nobody can judge later whether the app is still needed
Tier and why The tier, the answers to the six questions, the AI and agent modifiers, and the flags (jurisdiction, consent gate, audit scope) A reviewer can see at once whether the tier still fits (the six tier questions)
People Builder, app owner, successor, named backup, business and technical reviewers The owner and backup keep the app alive when you leave (when the builder leaves)
Data What it reads, stores and sends; the highest data class; where each piece is stored; who signed it off Data location decides who can see it, and what to delete at retirement
How it works A short description and, if you have one, a diagram A maintainer starts here
Connections Each system it reads or writes, with the credential's name, where it's held (never the value), its scope and its expiry Rotating or revoking access needs a list. Agent identities and grants go here too
Tests and checks Where the test cases are and when they last passed; the last technical check, exposure scan and restore test Shows the app was checked, and by whom
Decisions Links to the intake, downgrade and exception records, and any good-practice line skipped, with the reason The next person doesn't repeat your dead ends
Change log Where the version history lives (platform history, version control or a log) You can see what changed and roll it back

The record has no separate field for the build spec and the prompts that shaped the app. Keep them beside the record (see below) and link them from "How it works" or "Decisions", so you can change the app on purpose, not by guessing.

Don't: write documentation that describes the code

A page that explains the functions and files helps nobody who has to run the app on a bad day. Write what the app is for, who depends on it, how to tell it's working, and what to do when it isn't.

What goes in the runbook?

The runbook is for the person who has never touched the app. It answers: who to call, what "working" looks like, the first three things to check if it stops, how to restart or restore it, how to turn it off safely, who has access, how you'll know it stopped, and its known limits. The template is in the app record template.

Write the restore steps, then try them on a copy. Try them again after any change to where the data lives and at each scheduled review, and record the date in "Tests and checks". A restore nobody has tried is a guess.

How do I record decisions?

Keep a short log: the date, what was decided, why, and who agreed. For a decision with real consequences, such as accepting a risk or changing the tier, use the decision record template. Choices that look obvious today are the ones a maintainer questions in a year.

What can AI draft, and what must a person write?

AI is good at drafting from a source that exists. It's weak where the truth is in people's heads or in how the app behaves in real use.

AI can draft, and you check it A person writes or verifies
The "how it works" summary, from the code or the spec Purpose, and why the app exists
Field descriptions and a glossary of terms the app uses The runbook, especially restore and shutdown steps
A diagram caption or alt text Decisions and their reasons
A change-log entry from the version history Data location, data owner and access
Tidying the wording of your own text Anything a reader might act on without checking

A runbook written by a model that has never seen the app run is plausible fiction. Have the person who will be on call read it and walk through it.

Don't: publish AI-drafted documentation nobody checked

Unverified AI output in a formal record is a documented failure pattern (AP15, in failure patterns). Put a name and a date next to each section a person has checked.

Where should I keep an app's documentation?

In the same shared, backed-up place as the app, linked from the app registry. Keep the spec, the prompts that shaped the app and the test cases beside it.

Don't: keep it in your personal drive

Documentation in one person's drive leaves with them, the same way an app on a personal account does. Orphaned apps (AP19, in failure patterns) are the result. If nobody else can open the record, the app has no owner in practice.

What does each tier require?

Tier Documentation
Sandbox None required. Keep notes if you may share it later
Team The one-page app record
Important The app record plus a runbook
Critical Both, plus IT's standard documentation

This summarizes the documentation row of the gate matrix. Review the record at every change. When the owner changes, the handover is the moment to have the new owner read the record.

Assumptions and evidence

  • No new assumptions. The tier requirements come from the gate matrix. The practice of giving documentation a named owner and a review date is the one this site's own pages follow.
  • Evidence: the site's failure-pattern research on orphaned apps and unverified AI output. Both are thin for non-developer builders, so treat the advice as good practice, not a measured result.
  • Facts on this page are as of October 2026.