Prompts, Context, PRDs, and Acceptance Criteria
Write executable prompts, select relevant context, and turn an idea into testable requirements.
Table of contents
A good prompt is not a magic phrase. It is a work instruction that makes the outcome, sources of truth, boundaries, and completion evidence understandable. For a large project, a prompt does not replace a PRD or repository instructions.
1. Separate Prompts, Context, and Instructions
A prompt requests the current task. Context is information that helps the model, including files, screenshots, logs, diffs, requirements, and earlier decisions. Instructions define rules such as permissions, a fixed stack, or mandatory verification commands.
Every piece of context consumes tokens. More context is not always better. Provide the most relevant files and identify the source of truth. Do not send an entire repository when the task concerns one form and one API route.
2. Write an Observable Outcome
Begin with a result that a person can inspect:
Add email validation to the registration form.
Complete when:
- an empty email shows a required message;
- an invalid format is rejected before the request;
- server errors remain visibly separate;
- form tests and typecheck pass.Requests such as "make it better" or "fix everything" do not define completion. State the behavior that changes, not only the file to edit.
3. Use a Prompt Contract
For a non-trivial task, structure the prompt around these questions:
| Part | Question |
|---|---|
| Context | What is happening and why is the task needed? |
| Outcome | What behavior must change? |
| Non-goals | What is deliberately excluded? |
| Technical rules | Which stack, patterns, and safety boundaries apply? |
| Repository evidence | Which files and documents are authoritative? |
| Acceptance | How can a person prove the result is correct? |
| Checks | Which commands or inspections must run? |
Add a stop condition. The agent should stop if sources conflict, credentials are needed, a migration could be destructive, or the change must expand beyond the agreed scope.
4. Separate Stable Rules from a Task Prompt
Stable rules such as the package manager, lint command, migration policy, and definition of done belong in AGENTS.md or the coding tool's official instruction file. Temporary details such as one bug, a current screenshot, and task acceptance criteria belong in the prompt or plan.
Never place secrets in either location. Instruction file names and discovery behavior differ across coding tools, so explicitly direct the agent to a file when automatic discovery is uncertain.
5. Create a Minimum PRD
A PRD describes a product or feature across multiple tasks. A useful beginner template is:
# Product Requirements Document
## Product Summary
## Target Users
## MVP Scope
## Non-Goals
## Main User Flows
## Business Rules
## Data
## Authentication and Authorization
## UI States
## Technical Constraints
## Acceptance Criteria
## Open DecisionsNon-goals prevent scope creep. Open decisions prevent an agent from inventing unresolved product choices. A PRD can be short, but important rules must remain consistent and traceable.
6. Make Acceptance Criteria Testable
Acceptance criteria describe behavior. For UI work, include relevant loading, empty, populated, error, validation, disabled, and permission-limited states. Include desktop and smartphone behavior when layout changes.
For data and APIs, define who may read or write, how tenants or users are isolated, how invalid input responds, and whether an operation must be idempotent. "Works well" is not an acceptance criterion.
7. Direct the Use of Screenshots
An image is context, not a complete instruction. Explain which aspects matter:
Use the screenshot as a hierarchy reference, not as a production asset.
Preserve the sidebar, page header, filter bar, data table, and detail drawer.
Use existing tokens and components.
Do not copy the logo, brand, or data shown in the screenshot.Use precise UI vocabulary. Read Website Anatomy so prompts can identify navbars, heroes, CTAs, cards, modals, drawers, and states without ambiguity.
8. Plan Large Tasks First
Split a large change into two phases. The first prompt requests an audit and implementation plan without edits. After a person reviews the assumptions, the next prompt authorises implementation within the agreed scope.
After implementation, request changed files, commands run, test results, remaining risks, and required manual steps. Still inspect the diff yourself.
9. Prompt Quality Checklist
- The outcome is observable.
- Sources of truth are explicit.
- Scope and non-goals are separate.
- Permission and security boundaries are stated.
- Acceptance covers important states.
- Verification commands are available.
- No secrets or personal data are included.
- A stop condition prevents invention of important decisions.
Official sources and references
Use these sources to confirm current commands, capabilities, prices, and limits.
Was this guide helpful?
Tell us whether the steps worked or if something needs an update.