PRD Template for AI Coding Agents: Plan Before You Prompt

PRD template for coding agents: fill in a real example

Updated October 30, 2026

This PRD template turns a product requirements document (PRD) into something a coding agent can build from, one agent-sized task at a time. You are at Step 3 of 12 in the Vibe Coding guide. You leave with a copyable template, a filled-in example for Bookly, the data model and acceptance checks it needs, and a way to split the PRD into tasks.

A PRD written for a product team and a PRD written for a coding agent are not the same document. The agent fills every gap with its own guess, so each section must say what the agent cannot work out from the repo. This page covers the template, the current spec-driven tools and their critics, and the context files that carry the PRD into each session.

The running example is Bookly, a booking app for a small hair salon. Clients book a time slot and pay a deposit. The owner sees the day's bookings and can cancel or refund. Each section below shows what Bookly's version of that part says.

Why the Coding Agent Needs a Spec

The Hard-Coded Data Trap

When an agent cannot solve a problem, it can fabricate data instead of reporting the failure

The agent can create fake user records, fictional test results and fabricated analytics that look real.

Fortune reported that a Replit agent deleted a production database during a code freeze. Afterwards, Replit's CEO announced separate development and production databases and a planning-only mode. Bookly's PRD states that the agent never touches production data.

IEEE Spectrum published a small test by Jamie Twiss in January 2026. Nine ChatGPT versions ran 10 trials each on a task with a missing CSV column. GPT-5 filled the missing column with the row index plus 1 in every trial. The code ran, but the values had no meaning.

Solution: Set up the data structure (Supabase, Airtable, Postgres) before the agent writes any code. Otherwise, the agent hardcodes data into the frontend, and the app looks finished but is not. For Bookly, the five tables in the data model below come first.

Failure Modes Anthropic Recorded

Anthropic's notes on long-running agents name four ways a run goes wrong.

Trying to one-shot the app

The agent builds the whole product in one pass instead of one task at a time.

Declaring victory early

The agent reports the work as done while features are still missing.

Marking features done without end-to-end testing

Unit tests or curl calls pass, so the feature is marked done. The user flow was never run.

Leaving undocumented broken state

The session ends with broken code and no note about what is broken.

A spec file and a check list the agent cannot rewrite address these four failures. Long sessions also lose recall, which Anthropic calls context rot.

From Vibe Coding to Context Engineering

Andrej Karpathy endorsed the term in June 2025.

The point is to fill the context window with the right information for the next step, not with more text. Context engineering means keeping the project's architecture, standards, documentation and constraints in files the agent reads, instead of retyping them in each prompt.

A Thoughtworks essay in MIT Technology Review (November 2025) covers the same shift for software teams.

Ad-hoc Prompting

One-off instructions, inconsistent results, lost context between sessions

Prompt Engineering

Structured prompts, better outputs, still session-dependent

Context Engineering

Persistent context files, project architecture, curated documentation, constraints

PRD Template for Coding Agents

Classic PRD Sections vs What a Coding Agent Needs

Keep the classic section names. Change what goes in each one.

Section	What the agent needs	Bookly
Problem	Who has the problem and what the app must do about it	Clients book a slot and pay a deposit. The owner sees the day's bookings.
Users and roles	What each role can see, change and never do	Client and owner. A client never sees another client's booking.
Success measures	Outcomes you can test	A client books and pays without help from the owner.
Core features	A short v1 list, each feature with its checks	Book a slot, day view, cancel and refund.
Non-goals	What the agent must not build	No loyalty points, no reviews, no multi-location support.
Data model	Tables, fields, keys, unique constraints and delete rules	Five tables: clients, staff, services, bookings, payments.
Rules that cannot bend	Money, access and data rules in plain sentences	One active booking per staff member and start time. Payment keys stay on the server.
Design	The component library by name, layout rules, exact colors and fonts	Name the library in the PRD. shadcn/ui is one option.
Acceptance checks	One testable line per behavior	Six checks in acceptance.json. The agent ticks them.
Open questions and status	Decisions still open, who decides, and the status	Deposit amount per service: the owner decides.

What a PRD for an AI Builder Keeps

Questera's May 2026 guide is a vendor blog, so treat it as one view. The classic templates add a few rules of their own.

Eight sections: target user, problem, core feature, data model, screens and flows, design, integrations and success criteria.
One to two pages, about 400 to 800 words. Use it as the first prompt.
Specify only what the AI cannot infer. Skip HTTPS, framework defaults and deployment.
Write direct specs, not user stories.
Give exact hex codes, font names and typed data fields.
Update the PRD only when the scope meaningfully changes. Skip the PRD for a tiny single-screen app.
Order the phases by value. A phase is not complete until all its requirements are met. Product School calls a PRD a living document that changes through planning, development and launch.

Copy-Ready PRD Template

Copy the block, save it as PRD.md in the repo root, and fill in each section.

# PRD: [product name] Status: WIP | In Review | Approved | Obsolete Owner: [name] Approved by: [name, date] 1. Problem Who has the problem, what they do today, and why it matters. A few sentences. 2. Users and roles For each role: what it can see, what it can change, and what it must never do. 3. Success measures Two to four outcomes, and how you will check each one. 4. Core features (v1) One short paragraph per feature. Describe what it does, not how to build it. 5. Non-goals What v1 does not do. The agent must not build these, even when they look easy. 6. Screens and flows Name each screen. Number the steps of each main path. 7. Data model Each table, its fields, its keys, its unique constraints, and what happens on delete. 8. Rules that cannot bend Money, access and data rules, in plain sentences. Copy these into the context file too. 9. Integrations Each outside service, what it receives, and where its keys are stored (server only). 10. Design Layout rules, the component library by name, and exact colors and font names where they matter. 11. Acceptance checks One testable statement per line. The agent ticks these. It does not rewrite them. 12. Tasks and phases Phase 1, then phase 2. Each task names the checks it satisfies. 13. Open questions Decisions still open, the person who decides each one, and the date it is needed. 14. Change log Date, change, and reason. Update this only when the scope changes.

Sections 1 to 4 say what to build. Sections 5 to 9 say what the agent must not do and how the data is shaped. Sections 10 to 14 say how the work is split and tested. The template works for any app. The rest of this page fills it in for Bookly.

Bookly PRD, Filled In

The same 14 sections for the Bookly salon app. It is an illustration for this guide, not a real product spec.

# PRD: Bookly, a booking app for a small hair salon Status: In Review Owner: salon owner Approved by: [name, date] 1. Problem A client needs to book a time slot and pay a deposit online. The owner needs to see the day's bookings in one place, and to cancel or refund a booking. 2. Users and roles Client: books a slot, pays the deposit, and sees only their own bookings. Owner: sees all bookings for the day, cancels a booking, and issues a refund. Nobody sees another client's bookings or any card details. 3. Success measures A client can book and pay without help from the owner. The owner can find any booking for the day on one screen. 4. Core features (v1) Book a slot: the client picks a service, a staff member and an open time, then pays the deposit. Day view: the owner sees the day's bookings by staff member. Cancel and refund: the owner cancels a booking. A refund is recorded as a new payment. 5. Non-goals No loyalty points. No client reviews. No multi-location support. No marketing email in v1. 6. Screens and flows Booking: 1. Client chooses a service. 2. Client chooses a staff member and an open slot. 3. Client pays the deposit. 4. Confirmation screen shows the booking. Owner: 1. Owner opens the day view. 2. Owner selects a booking. 3. Owner cancels, or cancels and refunds. 7. Data model Five tables: clients, staff, services, bookings, payments (see the table on this page). Deleting a client keeps that client's paid bookings and payments. 8. Rules that cannot bend Two active bookings cannot share one staff member and one start time. Payment keys stay on the server. A refund is a new payment row. Old payment rows are never edited or deleted. A booking keeps the service price it was made at. The agent never reads or writes production data. It works on a separate development database. 9. Integrations One payment provider takes the deposit and issues refunds. Its secret key lives on the server only. Its webhook checks the signature before the booking changes state. 10. Design Plain layout, mobile first. Use the component library named in this PRD (shadcn/ui is one option). 11. Acceptance checks Listed in acceptance.json. The agent ticks them. It does not edit the check text. 12. Tasks and phases Phase 1: data model and the one-booking rule. Phase 2: book a slot. Phase 3: deposit payment through the server. Phase 4: owner day view, cancel and refund. 13. Open questions Deposit amount for each service: owner decides before phase 3. Refund rules after the appointment time: owner decides before phase 4. 14. Change log [date] First draft.

Section 7 is the data model, and section 8 holds the rules the agent must not break. Those two sections do the most work. A vague section 8 lets the agent make the payment and booking rules up as it goes.

Bookly Data Model

Five tables. Each row lists its key fields, its relationships and its rules.

Table	Key fields	Relationships and rules
clients	id, name, email, phone	One client has many bookings. Deleting a client keeps paid bookings and payments.
staff	id, name, role	One staff member has many bookings.
services	id, name, duration, price	A booking uses one service. Changing a price does not change past bookings.
bookings	id, client_id, staff_id, service_id, starts_at, status	Unique constraint: one active booking per staff member and start time. Foreign keys to clients, staff and services.
payments	id, booking_id, amount, status, provider_reference	A deposit and a refund are separate rows. A refund row points to the payment it refunds.

Decide the delete rule first. A cascade delete removes child rows when the parent row is deleted, so paid bookings and payments can vanish with a client record. Bookly keeps them, so that rule goes in section 7 before the first migration.

Acceptance Checks: A List the Agent Can Tick but Not Rewrite

Each Bookly check is one behavior the app must show.

[ { "id": "book-slot", "check": "A client picks an open slot and sees a confirmed booking.", "passes": false }, { "id": "no-double-booking", "check": "A second client cannot book a slot that is already booked.", "passes": false }, { "id": "deposit", "check": "A paid deposit moves the booking to paid.", "passes": false }, { "id": "client-scope", "check": "A client can read only their own bookings.", "passes": false }, { "id": "owner-cancel", "check": "The owner can cancel a booking and record the refund as a new payment.", "passes": false }, { "id": "webhook-signature", "check": "A payment webhook with a bad signature is rejected and changes nothing.", "passes": false } ]

Anthropic's long-running agent setup uses this pattern. Each feature has a passes field that starts as false. Coding sessions may change only that field, and it is unacceptable to remove or edit tests. Anthropic chose JSON because models alter it less than Markdown.

Each check must run as a test. A line that says a booking "should work" gives the agent nothing to pass. The tests themselves belong to TDD with AI.

Review against the spec

Agent code needs review against the checks. The review loop, the published data on AI co-authored pull requests, and the review tools that run on every pull request are on the Workflow and Git page.

Feature-Level Specifications

For each feature, write the user story in this format:

"As a [role], I want to [action], so that [outcome]."

For Bookly: "As a client, I want to book an open slot, so that I keep my appointment."

Acceptance Checks

Conditions that must be true for the feature to be complete. Each one becomes a line in acceptance.json.

Edge Cases

Empty inputs, network errors, unauthorized access and duplicate submissions. For Bookly: two clients submit the same slot at once.

Data Requirements

Fields, validations and relationships. Define these before any code is generated.

Common PRD Mistakes

Overly long AI-generated PRDs. Product leader Aakash Gupta observed that "PMs started using LLMs to create overly long PRDs that said nothing." A bloated, vague spec is worse than a short, precise one, because the agent fills every gap with its own assumptions.
Missing data architecture. Without explicit tables, keys and API contracts, the agent hardcodes data into the frontend.
Too many features for v1. A May 2026 template guide from Questera says 12 features overwhelm an AI app builder. Cut the core list to what the first launch needs.
No non-goals. Without a list of what to leave out, the agent adds features it thinks are useful. Bookly's section 5 names what v1 leaves out.
Vague technical context. Name the framework, the database, the auth method, the hosting and the error handling. Name a version only where the version changes the code.

Turning the PRD Into Agent-Sized Tasks

A task is one agent-sized unit: one slice of a feature, one or two checks and one session.

Data model: create the five Bookly tables and the one-booking rule. No feature code yet.
Book a slot: the client picks a service, a staff member and an open slot, and sees a confirmed booking. Satisfies book-slot and no-double-booking.
Deposit: the payment runs through the server, and the webhook checks its signature. Satisfies deposit and webhook-signature.
Owner day view: the owner sees the day, cancels a booking and records the refund. Satisfies owner-cancel and client-scope.

Each task gets a fresh session, its own branch and its own checks. The spec tools in the next part use the same shape: a spec, a plan, then tasks. The branch and commit habits are on the Workflow and Git page.

PRD Generator: What to Do With the Output

Draft a PRD in the builder below, or open the standalone tool at /tools/prd-builder.

Tool

Choose a Starting Template

Pick an app archetype to pre-fill features, screens, data models, and roles. You can customize everything later.

Step 0 of 17

A generated PRD is a first draft. Check it before the agent sees it, and look for these five faults:

Features you did not ask for.
No non-goals section, or one that is empty.
No acceptance checks, or checks that cannot be run as a test.
No data model, or tables with no keys and no delete rules.
Bracketed placeholders still in the text.

AI PRD Generator: Interview First, Then Write the PRD

Let the agent ask the questions. Then it writes the document from the answers.

Harper Reed's workflow starts with an interview prompt that asks one question at a time, and the answers become spec.md. Anthropic gives the same advice for Claude Code: interview until the agent could write the spec, then write it to a file. The interview prompt is in the prompt library below. The output still needs the five checks above, because an AI draft can be long and say little.

Wireframes and Design System

Give the agent an exact layout to match. Sketch each screen in any tool, such as Figma, Whimsical or Excalidraw, then write the screen list, the component names and any exact colors or font names into section 10 of the PRD. The cost calculator on the tools page includes Figma's plans; check Whimsical and Excalidraw on their own pricing pages.

Name the component library in the PRD

shadcn/ui

shadcn/ui calls itself AI-ready. It ships an MCP server, skills and an llms.txt file for coding agents, so the agent can read the component code directly.

Database Design: The Spreadsheet Analogy

Tables = Spreadsheets

Each table is a spreadsheet: clients, staff, bookings. Separate concerns into separate tables.

Rows = Records

Each row is one record: one client, one booking, one payment. Each row gets a unique ID.

Columns = Fields

Each column is a field: name, email, starts_at, status. Define the data type for each.

Relationships

Connect tables with foreign keys. A booking has a client_id column that points to the clients table.

Common Data Models

SaaS: Users, Organizations, Subscriptions, app-specific data tables
E-commerce: Products, Categories, Orders, OrderItems, Payments, Addresses
Content platform: Users, Posts, Comments, Tags, Likes
Booking (Bookly): clients, staff, services, bookings, payments

Common Database Mistakes

No relationships defined: The agent creates disconnected tables with no foreign keys.
No unique constraints: Duplicate bookings for one slot. Bookly needs one active booking per staff member and start time.
Missing indexes: Queries on frequently searched fields become slow.
No cascade rule: What happens to paid bookings when a client is deleted? Bookly keeps them. Decide this in the PRD.

Spec-Driven Development Today

Size the spec to the task

A one-line fix does not need a spec tool. A booking feature that several sessions share does. The critique below shows what happens when the spec is larger than the task.

Plan Mode in Each Tool

Plan mode lets the agent read and plan before it edits. Each tool turns it on differently.

Claude Code

Press Shift+Tab, type /plan before a prompt, or start with claude --permission-mode plan. The agent reads and writes a plan, but it does not edit source until you approve. Ctrl+G opens the plan in your editor. Plans are saved in ~/.claude/plans/ unless the plansDirectory setting changes it.

The opusplan alias uses a larger model to plan and a smaller one to build.

OpenAI Codex

Use /plan or Shift+Tab. For complex or unclear work, ask Codex to interview you first. For long work, keep a PLANS.md file. Codex details are on the Codex page.

Cursor

Press Shift+Tab in the chat input. The agent asks clarifying questions, researches the codebase and writes a plan you can edit. Plans are saved in your home directory by default, so click Save to workspace to keep one in the repo. If the result is wrong, revert, make the plan more specific, and run it again.

Interview Me, Write SPEC.md, Build in a Fresh Session

Anthropic's recommended spec flow for Claude Code

Ask the agent to interview you: "Interview me until you could write the spec, then write it to SPEC.md."
Read SPEC.md. Cut what the agent can work out from the repo. Keep the data model, the rules that cannot bend and the checks.
Start a fresh session to build from SPEC.md. The build starts with a clean context and a written definition of done.
Have a review subagent compare the diff with SPEC.md and report the gaps.

Before you leave a run unattended, answer five questions:

Does the agent know what done looks like?
Can it check its own work?
What may it touch?
What stops it, such as a turn limit (--max-turns) or a budget cap (--max-budget-usd)?
Where does the result go, and who signs off?

Source: Anthropic's Claude Code best practices.

Spec Tools: Spec Kit and Kiro

Two tools that keep the spec in files. Both add files you must review.

Spec Kit (GitHub)

The open-source toolkit reached version 1.0.0 on 2026-08-21 and has about 144,000 stars. Its docs list 38 coding-agent integrations. The commands are /speckit-constitution, /speckit-specify, /speckit-plan, /speckit-tasks, /speckit-implement and /speckit-converge.

uv tool install specify-cli specify init my-project --integration copilot

Needs Python 3.11 or later and uv.

The spec covers user journeys and success criteria, without stack details. The plan carries the stack and constraints. Tasks are small and independently testable.

Kiro (AWS)

Each spec is three files: requirements.md (or bugfix.md for a bug), design.md and tasks.md. A Quick Spec skips the approval gates. Analyze Requirements flags gaps and ambiguities before design. When you run all tasks, Kiro builds a dependency graph and runs independent tasks in parallel waves.

Steering files in .kiro/steering/ (product.md, tech.md and structure.md) load in every interaction. Kiro also reads AGENTS.md. Its launch post says acceptance criteria use EARS notation.

The Thoughtworks Critique

Birgitta Böckeler tested Kiro, Spec Kit and Tessl on martinfowler.com (2025-10-15).

Spec Kit produced many repetitive markdown files. The reviewer wrote: "I'd rather review code than all these markdown files."
Kiro turned a small bug into four user stories and sixteen acceptance criteria, "like using a sledgehammer to crack a nut."
The agents frequently did not follow all of the instructions in the spec.
Böckeler is "very skeptical" that lots of up-front spec design is a good idea.

Thoughtworks placed spec-driven development at Assess on its Radar (2025-11-05). For Bookly, a small fix needs a plan-mode run. The booking feature, which several sessions share, is worth a spec file.

Practitioner Flows

Two published workflows that use the same spec-then-tasks shape.

Addy Osmani (2026-01-04)

Brainstorm until the requirements are clear, then compile spec.md with requirements, architecture, data models and a testing strategy. Generate a task plan, then build in small chunks. He compares the spec step to waterfall in 15 minutes. He runs one main agent at a time, with a second agent for code review.

Harper Reed (2025-02-16)

An interview prompt produces spec.md. A reasoning model turns it into prompt_plan.md, and then a todo.md checklist. The models in that post are old. The method still works, so keep the steps and use current models.

Codex planning: the four-part prompt

OpenAI's best-practice guide asks for four parts in a prompt: goal, context, constraints and done-when. When Codex makes the same mistake twice, ask it for a retrospective and update AGENTS.md. The OpenAI cookbook's ExecPlan (now archived) is a plan written for a reader with no repo knowledge. Its living sections are Progress, Surprises & Discoveries, Decision Log and Outcomes & Retrospective, plus Validation and Acceptance.

Pick a Model by Testing It on Your Checks

Leaderboards no longer tell you which model will build your feature. Vals marks SWE-bench Verified as archived and saturated, with a top score of 97.0%. The harder SWE-bench Pro public leaderboard tops out at 61.5% on Scale's page, and Scale shows large drops on its private set. SWE-bench Verified has 500 Python problems, and Django supplies nearly half of them.

Run each candidate model on your own acceptance checks, and keep the one that passes them. For current model names and plans, see the tools page.

Context Engineering for Long Work

Code Prompting Is Specification, Not Conversation

A vague prompt to a text model gives a loose answer. A vague prompt to a coding agent gives code that compiles and does the wrong thing. Every ambiguity becomes a decision the agent makes without you, so write the decision down in the PRD.

Context Budget: Keep Only the High-Signal Tokens

Anthropic's guidance on context engineering, 2025-09-29

Context is a finite attention budget. Recall drops as the window fills. The goal is the smallest set of high-signal tokens for the next step. Four techniques help.

Compaction

The session is summarized as it nears the limit. Claude Code now runs compaction on its own.

Structured notes

Keep a NOTES.md or a to-do list outside the window. The agent reads it at the start of each session.

Sub-agents

A sub-agent does focused work and returns a summary of about 1,000 to 2,000 tokens.

Just-in-time retrieval

Keep file paths and load a file when it is needed. CLAUDE.md loads up front. Other files load on demand.

HumanLayer's research, plan, implement workflow keeps context use in the 40% to 60% range. It turns search results into progress files and treats specs and plans as the source of truth. The author reviews those documents rather than most of the generated code.

Context Files: Where Each Tool Reads Them

A context file holds the PRD pointer, the commands and the rules that cannot bend. Keep the workflow details on the Workflow and Git page.

Tool	File	Notes
Shared (many tools)	`AGENTS.md`	Root and subfolders. Read by Codex, Cursor, GitHub Copilot, Gemini CLI, Windsurf, Devin, Zed, VS Code, Jules, Aider and Warp. Used by more than 60,000 open-source projects.
Claude Code	`CLAUDE.md`	Root or ./.claude/CLAUDE.md. CLAUDE.local.md stays out of git. .claude/rules/*.md can load only for matching paths. Reads AGENTS.md only when there is no CLAUDE.md (v2.1.277 or later).
Cursor	`.cursor/rules/*.mdc`	Plain .md files in that folder are ignored. Keep each rule under 500 lines.
Windsurf	`AGENTS.md, .devin/rules/*.md, .devin/global_rules.md`	Docs now sit at docs.devin.ai. .windsurf/rules and .windsurfrules still load but are called legacy.
GitHub Copilot	`.github/copilot-instructions.md`	Also .github/instructions/NAME.instructions.md with applyTo globs, AGENTS.md anywhere in the repo, and CLAUDE.md or GEMINI.md in the root.
Kiro	`.kiro/steering/*.md`	product.md, tech.md and structure.md load in every interaction. Kiro also reads AGENTS.md.

Put the PRD pointer in AGENTS.md if more than one agent reads your repo. If you keep a CLAUDE.md, make it import AGENTS.md.

How Long a Context File Can Be

Each tool sets its own limit. A long file makes the agent ignore lines.

Claude Code: target under 200 lines per CLAUDE.md file. Auto memory loads the first 200 lines or 25 KB.
Codex: combined AGENTS.md content is capped at 32 KiB by default.
Cursor: keep each rule under 500 lines.
GitHub Copilot cloud agent: onboarding instructions should be no longer than 2 pages.
HumanLayer: a model follows about 150 to 200 instructions reliably. Claude Code's own system prompt already uses about 50.

An @path import does not reduce the context cost, so it only organizes a long file. What to put in a context file, what to leave out, and when a rule needs a hook instead are on the Workflow and Git page.

WHAT

A short codebase map and the decisions that are not obvious from the code. The agent reads the repo itself.

WHY

The product purpose, the key decisions and the reasons for them. Point to PRD.md for the rest.

HOW

The build, test and run commands, and the checks to run before a commit.

A Bookly Context File

Under 60 lines. Commands, the rules that cannot bend, and a pointer to the PRD.

# Bookly context file Bookly is a booking app for a small hair salon. Product spec: PRD.md. Read it before you start a feature. ## Commands - npm run dev: start the app - npm test: run the test suite. Run it before every commit. ## Rules that cannot bend - Payment keys stay on the server. Never put one in client code. - Refunds are new payment rows. Never edit or delete a payment row. - Two active bookings cannot share a staff member and a start time. ## Acceptance checks - acceptance.json lists the checks. Set "passes" to true only after an end-to-end run. - Never edit the check text.

What to Stop Writing, and What to Keep

Some habits from older guides now cause problems.

Stop

ALL CAPS emphasis. The agent over-applies the rule.
"Don't be lazy" or "keep going" lines. Anthropic says these cause over-work more often than they fix a stall.
"Think hard" phrases. Use the effort setting instead.
Describing architecture the model can read. Write down only what is not in the repo.
Aggressive context management. Current models have 1M-token windows, and compaction runs on its own.

Keep

/clear between unrelated tasks.
After two failed corrections, /clear and write a better prompt.
A fresh reviewer session that reads the diff and the spec.
A check the agent can run to test its own work.

Source: Anthropic's Claude Code best practices.

Progress File and Document-and-Clear

Anthropic's pattern for long-running work

The first session creates init.sh, a progress file and an initial git commit. It expands the prompt into a feature list. Anthropic's example progress file is claude-progress.txt. When the context grows, write the progress to the file, clear the context, and start a fresh session that reads the file. The git history adds the rest.

Then the next session starts from the file, not from memory. Bookly's acceptance.json plays the feature list role in this pattern.

Memory Document Pattern: Session Notes Outside the Chat

A notes file in the repo lets a fresh session resume without the old chat.

Keep one notes file in the repo, outside the chat. It records the current feature, the files touched, the decisions and the next step. A fresh session reads it first, so the work resumes without the old conversation.

# NOTES.md Current feature: deposit rule Files touched: bookings table migration, booking form, payment webhook Decisions: a slot is confirmed only after the deposit is paid. Refunds are new payment rows. Next step: run the webhook-signature check, then update the booking form.

End of session

Before you stop, update NOTES.md. Write the current feature, every file you touched, each decision with its reason, and the next step. Change nothing else.

Start of session

Read NOTES.md and PRD.md before you touch any file. Summarize the current feature and the next step. Then wait for my go-ahead.

The per-tool context-file table above covers where each agent reads its file. Day-to-day upkeep of those files is on the Workflow and Git page.

One Task, One Check

Give the agent one task at a time, and a check it can run after each step. Anthropic's advice is to give the agent a way to check its own work. The checks in acceptance.json are that way. Tests for each check are covered on the TDD with AI page. When a check fails, name the file, describe the symptom and say what fixed looks like. The debugging loop is on the Workflow and Git page.

Managing Multi-File Changes

Plan the file list first. Then run one task per file group, each with its own check.

One rule change often touches several files. Changing the Bookly deposit rule touches the bookings table, the booking form and the payment webhook. Architect first, then implement: plan the file list, then build one group at a time.

Use plan mode for the file list. In Claude Code, press Shift+Tab, type /plan before the prompt, or start with claude --permission-mode plan. In Codex, use /plan or Shift+Tab. In Cursor, press Shift+Tab in the chat input and save the plan to the workspace. Review the list before any edit starts.

Data model group

The bookings table and its status values. Check: no-double-booking.

Booking form group

The deposit step in the booking form. Check: book-slot.

Payment webhook group

The signature check and the status change after payment. Checks: deposit and webhook-signature.

Plan the list with this prompt, then run each group with the second prompt. For a larger change, use the interview, SPEC.md and fresh-session flow from the spec-driven section above.

Plan the file list

Change the Bookly deposit rule: a slot is confirmed only after the deposit is paid. Read PRD.md section 8 and acceptance.json. List every file the change touches, grouped by area: data model, booking form and payment webhook. For each group, name the acceptance check that proves it. Do not edit any file yet.

Build one group

Work only on the data model group in your list. Make that change, run the check named for it, and stop. Do not touch the booking form or the webhook. List the files you changed.

Vibe Coding Prompts for Planning: Interview, Spec, Tasks

Each prompt does one planning step, and each one can be pasted into the agent as written. The files are PRD.md, acceptance.json and tasks.md. Run them in order, and fill in the Bookly details for your own app.

Interview

Interview me about Bookly, a booking app for a small hair salon. Ask one question at a time until you could write the PRD. Start with clients, staff, services, deposits, refunds and cancellations. Do not write any code.

Write the PRD

Write PRD.md from our interview. Use these sections in order: problem, users and roles, success measures, core features, non-goals, screens and flows, data model, rules that cannot bend, integrations, design, acceptance checks, open questions, change log. Keep it to two pages. Do not write any code.

Data model

Read section 7 of PRD.md. Propose the tables clients, staff, services, bookings and payments. For each table, list the fields, the keys, the unique constraints and what happens on delete. Explain each relationship in one sentence. Do not write migrations yet.

Split into tasks

Read PRD.md and acceptance.json. Split the checks into tasks. Each task must fit in one session, name the checks it satisfies and list the files it may touch. Write tasks.md. Do not write code.

Build one task

Work only on task 2 in tasks.md: book a slot. Write the failing test first, then the code that makes it pass. Do not edit the check text in acceptance.json. Stop when the test passes and list the files you changed.

Review against the spec

Compare this branch with PRD.md and acceptance.json. List each requirement the diff misses, each change the PRD does not ask for, and each check that has no test. Do not edit any file.

Agent Workflow Patterns and Prompting Principles

AI Agent Workflow Patterns

These patterns come from Anthropic's guide to building effective agents (2024-12-19).

Sequential Pipeline

Agent A, then agent B, then agent C

Best for clear dependencies. Each output feeds the next. For Bookly: parse the PRD, write the tasks, then run the checks.

Parallel Execution

Several agents run at the same time

Best for review. Run a security reviewer, a style reviewer and a performance reviewer at once, then combine the results. Security review prompts are on the security page.

Evaluator-Optimizer Loop

Generate, critique, refine

The generator writes the code. The critic lists the flaws. The refiner fixes them. Stop on a condition you set in advance, such as a maximum number of rounds, not on a fixed count.

The #1 Prompting Principle

"Architect first, code second." Ask the agent for a spec with milestones before any code. This stops early decisions from compounding into larger problems later.

Prompting Strategy and Decomposition

Bad prompt versus a sequence of Bookly tasks

Bad Prompt

"Build a booking app with clients, staff, services, payments, reminders and reviews."

Good Prompt Sequence

"Write PRD.md for Bookly. List the data model, screens and API routes. Do not write code."
"Build the five tables in section 7. Add the one-booking rule."
"Add the book-a-slot screen. Write the failing test first."
"Add the deposit payment through the server."
"Add the owner day view with cancel and refund."

Advanced Prompting Techniques

Specification Phase

"Before writing any code, create a detailed specification including data models, API endpoints and user flows. I will review it before you proceed."

Architecture

Constraint Forcing

"Implement this using only the existing project dependencies. Do not add new packages. Do not use microservices. Keep it in one file."

Control

Adversarial Testing

"How could a malicious user break this feature? What happens with empty inputs, negative numbers, extremely long strings or concurrent requests?"

Edge Cases

Reference Implementation

"Here is the existing auth pattern used in this project [paste code]. Follow this exact pattern when implementing the new feature."

Consistency

Incremental Complexity

"Start with the simplest version that works. I will ask for enhancements one at a time. Do not add features I have not requested."

YAGNI

Next Step

Bookly now has a PRD, a data model and acceptance checks. The next step is the daily loop that builds the first task: a branch, small commits and a rollback plan. Continue to Workflow and Git.

Common Questions

How do I write a product requirements document for an AI coding agent?

Interview yourself first, or let the agent interview you one question at a time, then write PRD.md with these sections: problem, users, success measures, core features, non-goals, screens, data model, rules that cannot bend, integrations, design, acceptance checks, open questions and a change log. Keep it to about two pages and make every acceptance check testable.

What should a PRD template for AI coding include?

Beyond a normal PRD, an agent needs three things a human team would infer: a data model with tables and relationships, acceptance checks written so a test can prove them, and rules that cannot bend, such as never touching production data. The copy-ready template on this page lists every section, and Bookly's filled-in version shows each one.

Vibe coding vs spec-driven development: which should I use?

Spec-driven development writes a spec before code, through tools such as GitHub Spec Kit, Kiro's spec files or plan mode in Claude Code, Codex and Cursor. It pays off for multi-step features. For a one-file change, a full spec is overhead; Thoughtworks called heavy spec tooling a sledgehammer to crack a nut. A short PRD plus plan mode covers most small apps.

Is there a free AI PRD generator?

Yes. GrowthVector's PRD Generator at /tools/prd-builder runs in your browser for free. You pick an app type, features, a data model and a stack, and it builds a structured PRD prompt you can paste into Claude Code, Codex or Cursor. Review the result against the template on this page before the agent starts building.

How long should a PRD be for an AI coding agent?

Aim for one to two pages. A May 2026 template guide from Questera puts a vibe-coding PRD at about 400 to 800 words and says 12 features overwhelm an AI app builder. A Thoughtworks review of spec tools found that a small bug turned into four user stories and sixteen acceptance criteria, which the reviewer called like using a sledgehammer to crack a nut. Write down only what the agent cannot work out from the repo.

Should you plan and build in the same AI coding session?

Plan in one session, write the result to a file in the repo, then build in a fresh session. Anthropic recommends starting the build from SPEC.md, so it begins with a clean context and a written definition of done. Claude Code can approve a plan and clear the planning context. In Cursor, plans are saved in your home directory by default, so click Save to workspace to keep one in the repo.