A vibe-coded app needs more than a README. The minimum durable documentation for a web application built with AI is a system overview, architecture and dependency map, business-rule record, data and access map, environment and deployment guide, operations runbook, test map, decision log, known-risks ledger, and instructions for future AI-assisted changes.
Documentation should describe both intent and verified behavior. Label what is confirmed, inferred, planned, deprecated, or unknown. Keep secret values and customer data out of the docs, and update the document in the same change that makes its claim stale.
The vibe-coded app documentation checklist
| Document | What it answers | Evidence to attach |
|---|---|---|
| System overview | What does the app do, who relies on it, and what is critical? | Named owner and critical workflows |
| Architecture and dependency map | Which applications, data stores, jobs, and external services participate? | Current deployment and service inventory |
| Business-rule record | Which permissions, prices, states, and lifecycle rules must remain true? | Code path, test, or observed result |
| Data and access map | What data exists, where it flows, and who may use it? | Schema, policy, role, retention, export, and deletion paths |
| Environment and deployment guide | How do development, staging, and production differ, build, deploy, and roll back? | Commands, pipeline, configuration names, and running version |
| Operations runbook | How are failures detected, contained, communicated, and recovered? | Alert test, restore result, contacts, and decision thresholds |
| Test map | Which important behavior is protected, at what level, and how is it run? | Test command and critical-path coverage |
| Decision log | Why were consequential technical choices made? | Context, alternatives, decision, and consequences |
| Known-risks ledger | What is fragile, accepted, blocked, or still unknown? | Evidence, consequence, owner, and revisit date |
| AI instruction file (AGENTS.md, CLAUDE.md, .cursor/rules) | What must an assistant read, preserve, test, and avoid? | Repository-specific commands and boundaries |
The last row is the one easiest to skip, and it is the one a vibe-coded app cannot do without: an AGENTS.md, a CLAUDE.md or a rule file under .cursor/rules is the only document on this list written for the assistant that will make the next change.
Not every app needs ten separate files. A small project can combine related sections in a few documents. Keep the headings distinct so a maintainer can find the answer without reading a long narrative from the beginning.
1. Start with a one-page system overview
Write for a technical person who has never seen the app and a business owner who does not need source-code detail.
# System overview
- Purpose:
- Users and roles:
- Critical workflows:
- Business owner:
- Technical owner:
- Production URL and environment:
- Source repository:
- Main systems and providers:
- What stops if the app fails:
- Current known risks:The overview is an index, not the complete truth. Link each claim to the detailed document or system that supports it.
2. Map architecture and runtime dependencies
Show users, the web or mobile client, server components, databases, storage, identity, queues, scheduled jobs, payment and email providers, analytics, and other important integrations. Label trust boundaries, data direction, protocols, environment, and owner.
The official C4 model offers context, container, component, and code views, while noting that context and container diagrams are enough for many teams. A small vibe-coded app usually needs one context view and one container or deployment view. More boxes do not create more understanding if they are not current.
Include the dependency name, purpose, version or plan where relevant, configuration location, data exchanged, failure effect, fallback, cost owner, and replacement difficulty. A package manifest will not reveal every hosted service, runtime call, webhook, or manual operational dependency.
3. Record business rules separately from interface behavior
The hardest knowledge to recover from generated code is often why a rule exists. Document permissions, pricing, entitlements, state transitions, limits, approvals, refunds, retention, and deletion in plain language.
## Rule: Paid access after subscription
- Intent:
- Source of truth:
- Allowed transitions:
- Server-side enforcement:
- External events:
- Failure and retry behavior:
- Tests or evidence:
- Owner:Do not use a screenshot of a hidden button as evidence that an action is forbidden. Link the server, database, or provider path that enforces the rule and the test that demonstrates the denial or transition.
4. Document data and access paths
Create a concise data dictionary for important tables, collections, file stores, and external records. Record the authoritative source, owner or tenant key, sensitivity, retention, backup coverage, exports, deletion path, and major consumers.
Map roles to actions rather than listing role names alone. For each important record, state who can create, read, update, delete, export, and administer it, and where the rule is enforced. Include privileged functions, service credentials, background jobs, and support access that bypass ordinary interface paths.
Never paste real customer data, passwords, private keys, or API secret values into documentation. For secrets, document the logical name, purpose, storage system, environments, consumers, access owner, rotation method, and revocation effect.
5. Make setup, environment, and deployment reproducible
A new maintainer should be able to identify prerequisites, install dependencies, run the app with safe development configuration, execute checks, and understand how a commit becomes production.
Document configuration names and sources without secret values. Explain which environment uses which database, storage, payment mode, email recipient policy, domains, and callback URLs. Record migration order and any manual step that the pipeline does not enforce.
The deployment guide must answer:
- Which branch or tag may deploy?
- Which build, type, test, and migration checks block release?
- How is the running version identified?
- Who approves production and data changes?
- How is a failed release rolled back or rolled forward?
- Which data changes cannot be undone by reverting code?
6. Write runbooks around decisions, not dashboards
An operations runbook starts from a symptom or alert and leads to a safe action. Cover the critical workflow, failed sign-in, payment or webhook failure, background-job backlog, third-party outage, data mistake, unusual spend, access incident, rollback, and restore.
Each runbook should state the signal, business impact, first safe checks, containment options, decision owner, communication path, recovery, verification, and escalation condition. Store a copy somewhere available when the app itself is unavailable.
Link to dashboards and logs, but do not assume the link explains which change is safe. Record the last time a test alert, rollback, or restore was successfully exercised.
7. Keep a test map and an evidence ledger
List critical workflows and the checks that protect them. Distinguish unit, integration, browser journey, direct authorization, migration, restore, and load tests. Include the command, environment, fixtures, required credentials, expected result, owner, and last successful run.
Documentation is not evidence simply because it cites a filename. Trace important claims to a path that runs or a result that was reproduced. I found the identical shape across two different apps in the corpus: a schema note claiming encryption that the running code had never implemented. That fixed-cohort observation does not establish a prevalence rate; it illustrates why a comment must be verified before another person relies on it.
The same gap shows up above the code as well as inside it. One audited app’s public pages described detailed GDPR and HIPAA compliance workflows; the checks running behind those workflows never touched anything that would have caught a real violation. They existed to satisfy the page, not the data. Another shipped race results that read as live and final, when the numbers were invented and the timestamps ignored time zone entirely, so a reader saw a finish time that had never happened. In each case the documentation, whether a schema comment, a compliance page, or a results feed, was the only thing anyone had checked.
Documentation becomes dependable when someone checks its claims against the working app before another person relies on it.
| Documentation claim | Stronger evidence |
|---|---|
| Rate limiting implemented | The production route invokes the limiter and a controlled excess request is rejected |
| Backups enabled | Representative data was restored and the app read it successfully |
| Error monitoring configured | A deliberate failure produced a useful alert in the owner’s channel |
| Tenant data protected | A second account was denied at the backend boundary |
The same shape turns up one layer over, in what happens when an app fails silently behind a 200 OK: a status code, like a doc, can be technically present and tell you nothing true about what is happening underneath it. A doc that only records intent, never checked against the code, is exactly that kind of status code.
8. Preserve decisions and known risks
Use short architecture decision records for choices that would otherwise look arbitrary later: database selection, tenant model, authentication provider, deployment target, state machine, external dependency, or a deliberate tradeoff.
The UK government’s ADR framework describes the practice of documenting architectural decisions made during system design and development. A useful entry includes context, options, decision, consequences, status, and date. Mark superseded decisions instead of silently rewriting history.
Keep accepted risks in a separate ledger with evidence, consequence, current mitigation, owner, acceptance reason, expiry or revisit date, and retest condition. “Known issue” without an owner or date is archival trivia, not risk management.
9. Leave an AGENTS.md, CLAUDE.md or .cursor/rules for the next AI session
A rules file, such as AGENTS.md, CLAUDE.md or an .mdc file under .cursor/rules, should contain commands and constraints the assistant can act on: project structure, source-of-truth files, generated areas, prohibited operations, environment rules, critical tests, style conventions, fragile boundaries, and documentation-update requirements.
Do not copy the entire human documentation set into the rules file. Link to the relevant sources and state the operational constraint. A rule that says “do not change payment state without running X” is more useful than a long history of why payments matter.
Machine instructions can also become stale. Validate file paths and commands in automation where possible, and review the rules whenever the build, deployment, or ownership model changes.
Keep documentation current without creating a second job
Most guidance on how to write documentation for a web application stops at the writing. Creating the documents is the easy half; keeping them true is the half that fails. Assign each document an owner and a change trigger:
| Change | Documentation updated in the same work |
|---|---|
| New provider or dependency | Architecture map, configuration inventory, operations and cost notes |
| Schema or access-rule change | Data dictionary, role map, migration and restore notes |
| New business workflow | Intent, rules, critical-flow test map, monitoring and runbook |
| Deployment change | Environment map, pipeline, approval, rollback, and running-version procedure |
| Incident | Runbook, known-risk ledger, relevant test, and decision record |
Review high-change documents on a schedule, but prefer event-driven updates. A quarterly reminder cannot repair a deployment guide that became false during last week’s pipeline change.
For transfer work, documenting an app for a new developer does not require all ten documents on day one. Start with the verified system overview, the environment and deployment guide, and the business-rule record plus the known-risks ledger, then expand across the rest of the checklist based on the app’s dependencies and consequence.
Writing documentation after the build is the mirror image of writing a spec before building: a spec describes what should exist before the agent generates it. Documentation records what exists now, why it exists, and what evidence supports that statement.
None of this pays down technical debt by itself, and it is one slice of whether an AI-built app is ready to launch at all. Documentation makes the system understandable and change risk visible; tests, code restructuring, access controls, recovery work, and operational practice change the system itself. A doc checked against the code closes one specific version of the drift that makes an AI-built app harder to change every week; catching a regression once the app is running is a different job, one only a test does.
Common questions about vibe-coded app documentation
What documentation does a vibe-coded app need?
Application documentation is the written record of what an app does, how it runs, and what must stay true. For a vibe-coded app that record has ten parts: a system overview, architecture and dependency map, business rules, data and access map, environment and deployment guide, operations runbook, test map, decision log, known-risks ledger, and repository-specific AI instructions. A small app can combine these into fewer files.
What should software documentation include?
Software documentation should include what the system does, how it is built and deployed, which business rules must stay true, where data lives and who can reach it, how failures are detected and recovered, what is tested, why the consequential decisions were made, what is still fragile, and what an assistant may and may not change. If you prefer the five W’s of documentation as a memory aid: what the app does, who relies on it, where each rule is enforced, when the claim was last verified, and why the decision was made.
What are the four main types of software documentation?
There is no single official list, but software documentation usually falls into four kinds: product and system documentation (what the app does and how it fits together), process documentation (how it is built, released, and recovered), user documentation (how someone uses it), and decision documentation (why the consequential choices were made and what risk was accepted). A vibe-coded app normally needs the first, second, and fourth long before it needs a polished user manual.
What are the four types of documentation?
The four types most often quoted come from the Diátaxis framework: tutorials, how-to guides, technical reference, and explanation, organized around what a reader needs at that moment, which is learning, doing, looking something up, or understanding. That split governs documentation written for a reader. The checklist above governs the record of what the app actually does and how to operate it, and an app you did not write by hand needs both.
Can AI generate the documentation?
Yes, as a draft. Give it the repository and explicit evidence requirements, then verify every material claim against code, configuration, deployed behavior, tests, or the responsible owner. Label unresolved claims as unknown instead of letting plausible prose become false documentation.
Is a README enough for a vibe-coded app?
No. A README is the entry point for purpose, setup, and common commands. It rarely captures production architecture, business rules, data ownership, release and recovery procedures, current risks, and the evidence needed to operate the app safely.
Should documentation include API keys and passwords?
No. Document secret names, purposes, storage locations, consumers, owners, rotation, and revocation. Keep values in the appropriate secrets system and grant access through named identities that hold only the permissions they need.
How often should documentation be updated?
Update it in the same change that alters its claim. Also review high-change areas periodically and after incidents. Give each document an owner and a trigger so freshness does not depend on memory.
Still the only person who can keep the app moving?
When staff or customers depend on it, AxonBuild can fix the next failure, ship the next change, and document the app so progress no longer waits on you.
