The 14 documents your AI needs to build your app

If you build with AI, getting it to write code is the easy part. The hard part is giving it enough context to understand how your product has to work, how it is built and how to know it really works. Whatever you do not tell it, it makes up.

That is what these documents are for. There are fourteen, each one answers a question no other one answers, and they all describe the same made-up project so you can see how they fit together: Turnio, a booking app for hair salons.

How they are organised

AGENTS.md goes in the root, because that is what agents look for when they open a project. The rest lives in docs/. They come in three groups: what you build, how it is built and how the work is done.

turnio/
├── AGENTS.md                  ← the agent starts here
├── CLAUDE.md                  ← one line: @AGENTS.md
└── docs/
    ├── PRD.md                 what and for whom
    ├── APP_FLOW.md            where each user goes
    ├── DESIGN_SYSTEM.md       how it looks
    ├── TRD.md                 how it works inside
    ├── DATABASE.md            where the data lives
    ├── API.md                 how the pieces talk
    ├── SECURITY.md            what must not break
    ├── CODE_STYLE.md          how it is written
    ├── IMPLEMENTATION_PLAN.md in what order
    ├── TESTING.md             how you know it works
    ├── DEPLOYMENT.md          how it reaches production
    ├── DECISIONS.md           why it is this way
    └── PROGRESS.md            where we left off

You do not need all fourteen on day one. A landing page gets by with PRD, DESIGN_SYSTEM and AGENTS. An MVP adds APP_FLOW, TRD, DATABASE, IMPLEMENTATION_PLAN and PROGRESS. The rest come once there are users and money involved. What matters is that the AI has clear, ordered context instead of guessing.

In each document's file tree you can click any other one to jump to it.

1. PRD.md: what you build and for whom

It is the document every other one comes from. It tells the AI what problem the product solves, for whom, what goes into the first version and, almost more important, what does not.

The most common mistake is not writing “Out of scope”. Without that list, the AI adds whatever seems like a good idea, and within a week you have a chat, a points programme and not a single working booking.

2. APP_FLOW.md: where each user goes

It turns the PRD into journeys: which screens exist, in what order you go through them and what the user sees on each one. It stops the AI from inventing screens or forgetting the way back.

/                    landing
/[negocio]           public page
/[negocio]/reservar  service and slot
/reserva/[id]        reschedule or cancel
/entrar  /registro
/panel               today's calendar
/panel/servicios
/panel/horario
/panel/clientes
/panel/ajustes       payments and team

What almost nobody writes are the empty and error states and the alternative paths. They are exactly what the AI does not imagine on its own, and the first thing a real user runs into.

3. DESIGN_SYSTEM.md: how it looks and how it moves

Colours, typography, spacing, components and motion, with exact values. With it, every new screen looks like the previous ones; without it, each one debuts a different grey and a different radius.

The palette is not enough: write the rule for each component (“only one primary button per screen”) and how long animations last. And if you also want it not to look AI-built, here are six things that fix it.

4. TRD.md: how it works inside

The technical document: stack, architecture, folder structure and requirements with numbers. If the PRD says what, the TRD says with what and how.

turnio/
├─ app/
│  ├─ (publico)/[negocio]/   # page and booking
│  ├─ (panel)/panel/         # private area
│  └─ api/v1/                # API routes
├─ components/
│  ├─ ui/                    # adapted shadcn
│  └─ booking/               # booking pieces
├─ lib/                      # logic, no React
├─ supabase/migrations/
└─ docs/

Write down the constraints. “No separate server” or “under 50 € a month” are the sentences that stop the AI from building you microservices for a booking app.

5. DATABASE.md: where the data lives

The tables, how they relate, who can read and write each one and how the schema changes. It is the most expensive one to skip: a database mistake is not fixed with a deploy.

businesses 1──n services
businesses 1──n staff 1──n availability
businesses 1──n customers 1──n bookings
services   1──n bookings n──1 staff
bookings   1──1 payments

# Local database with the test data
supabase start && supabase db reset
# New migration
supabase migration new add_no_show_to_bookings
# TypeScript types from the schema
supabase gen types typescript --local > lib/database.types.ts

Put the rules that must never break in the database, like a staff member not having two appointments at once. A rule that only lives in the code gets skipped by the first endpoint that forgets it.

6. API.md: the contract between the pieces

Every endpoint with its method, who can call it, what it receives, what it returns and how it fails. With it, the AI writes the frontend and the backend without them contradicting each other.

{
  "serviceId": "3f2a…",
  "staffId": "9b1c…",
  "startsAt": "2026-10-14T09:30:00Z",
  "customer": {
    "name": "Laura Gil",
    "phone": "+34600111222",
    "email": "laura@correo.com"
  }
}

{
  "data": {
    "bookingId": "c71d…",
    "status": "held",
    "heldUntil": "2026-10-01T10:10:00Z",
    "checkoutUrl": "https://checkout.stripe.com/…"
  }
}

Define errors once and for all. Otherwise every endpoint fails in its own way and the frontend fills up with special cases.

7. SECURITY.md: what must not break

The security rules the code always follows, whoever writes it. The AI does not write insecure code out of malice: it writes it because nobody told it what to protect.

Content-Security-Policy: default-src 'self'; frame-src https://checkout.stripe.com
Strict-Transport-Security: max-age=63072000; includeSubDomains
X-Content-Type-Options: nosniff
Referrer-Policy: strict-origin-when-cross-origin
Permissions-Policy: camera=(), microphone=()

Write them as rules you can check (“the business_id comes from the session, never from the body”), not as wishes (“the app must be secure”). The full list is in the guide to not getting hacked.

8. CODE_STYLE.md: one way of writing

Names, folders, language and framework rules, errors and commits. It makes code from five different sessions look like the same person wrote it.

components/booking/SlotPicker.tsx      # what you see
lib/bookings/create-booking.ts         # what decides
lib/bookings/create-booking.test.ts    # what tests it
app/api/v1/bookings/route.ts           # only validates and calls lib/

// ✗ Not like this
const d = await fetch('/api/v1/slots?s=' + s).then(r => r.json()) as any

// ✓ Like this
const { data: slots, error } = await getFreeSlots({ serviceId, date })
if (error) return <SlotsError />

feat(bookings): hold the slot for 10 minutes during payment
fix(slots): slots were shifted by one hour after the clock change
docs(progress): end of the October 29 session

One “not like this, like this” example is worth ten rules. The AI imitates better than it obeys.

9. AGENTS.md: where the agent starts

The only one in the root and the first one read. It does not repeat the others: it says which one to read for each task, how work is done and what is never touched. Claude Code reads CLAUDE.md and the other agents read AGENTS.md; with one line that imports one from the other, both work.

npm run dev          # localhost:3000
npm run lint
npm run test         # Vitest
npm run test:e2e     # Playwright
supabase db reset    # clean local database

# CLAUDE.md
@AGENTS.md

The temptation is to put everything here. If AGENTS.md runs past two screens, the agent skims it. It should direct, not explain.

10. IMPLEMENTATION_PLAN.md: in what order

The project split into phases and numbered tasks, each with what has to happen for it to count as done. The AI does one task at a time, and you know exactly which one.

Read AGENTS.md and PROGRESS.md.
Implement only task 3.4 of the plan.
Before writing code, tell me which files
you will touch and how you will test it.

The mistake is asking “build me the app” in a single message. Each phase has to be testable on its own; otherwise, when something breaks, you do not know which of the forty new things it is in.

11. TESTING.md: how you know it works

Which kind of test for what, the flows tested end to end, the edge cases and when each thing runs. It turns “it seems to work” into something you can check.

npm run test               # unit and integration
npm run test -- --watch    # while you code
npm run test:e2e           # Playwright
npm run test:e2e -- --ui   # watching it in the browser

Name your product's edge cases. In a booking app they are the clock change and two people grabbing the same slot, and the AI will not test them unless you tell it to.

12. DEPLOYMENT.md: how it reaches production

It is missing from most lists and it is one of the ones that saves the most scares: what is in each environment, which variables are needed, in what order each thing ships and how to undo it.

The rollback plan is written before you need it: at eleven at night with the app down, nobody improvises it well. The thirteen checks before shipping to production complete it.

13. DECISIONS.md: why it is this way

A log of decisions, each with its context, what was ruled out and what it costs. It stops an AI with no memory from undoing in five minutes something that took you a week to decide.

## ADR-000: Short title
Date · Status: proposed | accepted | superseded
Context: what the problem was
Decision: what was chosen
Alternatives: what was ruled out and why
Consequences: what we gain and what we pay

Do not write one for everything. Only when there were two reasonable options or when undoing it is expensive.

14. PROGRESS.md: where we left off

The memory between sessions. The AI does not remember yesterday's conversation, but it can read a file: what is done, what is missing, which branch you are on and what has already failed.

The most valuable part is the known pitfalls: every mistake written down is a mistake the agent does not repeat. Close it at the end of every session with the second prompt in the article.

Getting it to read them and keeping them true

An outdated document is worse than none, because the AI believes it. Six rules so that does not happen:

• Each fact in one place. If the deposit price is in the PRD and in the database doc, one day they will say different things. One tells it and the other links to it.
• In the same commit. The code change that contradicts a document fixes it in the same commit, not “later”.
• Short. One or two screens each. Whatever does not help the agent decide is extra.
• Name them in the prompt. “Follow DATABASE.md” works better than waiting for it to find it.
• Numbers instead of adjectives. “Under 2.5 seconds” can be checked; “fast” cannot.
• Review them every month. Ask the agent to compare each document with the code and tell you where they lie.

The three prompts: the first asks you the questions and writes the documents, the second closes each session and the third checks the documentation still tells the truth.