Web Development · Planning & documentation
The Best Prompt for Writing a Technical Specification
The best prompt for a technical spec makes the model ask before it writes, because a spec built on guessed requirements wastes reviewers' time. This prompt has the model put a small number of questions to you first, then produce a document with explicit non-goals, a design described at the level reviewers need, real alternatives with reasons for rejecting them, and a rollout and rollback plan. Missing facts are marked TBD with an owner, not filled in.
Technical Specification Prompt
Interviews you briefly, then drafts a reviewable spec: goals and non-goals, design, alternatives, rollout, risks and open questions.
- Works with
- ChatGPT, Claude, Gemini
- Difficulty
- Intermediate
- Complexity
- Conversation
- Variables
- 6
- Version
- 1.0
Customize this prompt
Fill in what you know. Anything left blank stays as a [bracketed placeholder]. Nothing you type leaves your browser.
6 variables · fields marked * matter most
I need to write a technical specification that engineers will review and then build from. Act as a staff engineer helping me draft it. Your job is clarity and completeness, not persuasion. What I know so far - Project or feature: [Project or feature] - Problem and background: [Problem and background] - Goals, and anything explicitly out of scope: [Goals and out-of-scope items] - Current system and constraints: [Current system and constraints] - Approaches already discussed: [Approaches already discussed] - Who will read this: [Audience] Round 1: questions Do not draft yet. Ask me up to six questions, the ones whose answers would most change the design. Prioritize: how success will be measured, scale and data volumes, failure behavior, compatibility with existing clients or data, security and privacy, and deadlines. Number them, and for each say in a few words why it matters. Then wait. Round 2: the spec After I answer, write the document with these sections. 1. Summary: one paragraph a busy reader can stop after. 2. Background and problem: what is true today and why it is not good enough. No solution yet. 3. Goals and non-goals: goals as outcomes that can be checked. Non-goals are things a reader might reasonably expect that this work will not do. 4. Proposed design: components, data flow, changes to data models and interfaces, and behavior when things fail. Describe a diagram in text where one would help. Include detail in proportion to risk: more for what is novel or irreversible, less for what is routine. 5. Alternatives considered: at least two, including doing nothing, each with the reason it was not chosen. 6. Rollout: migration steps, feature flagging, how to roll back, and what to monitor. 7. Testing: what will be verified and at which level. 8. Risks and mitigations: a table. 9. Open questions: each with a suggested owner role. Rules for the draft - Use only facts from my notes and answers. Where something is missing, write TBD and say who would know. Never fill a gap with a plausible number, service name or date. - Write for the stated audience. Define any term they would not know. - Do not present an alternative that is obviously weak just to make the proposal look good. - Plain declarative sentences. No marketing language. - No time estimates unless I supplied them.
Use it when you are
- Turning rough notes or a chat thread into a spec that is ready for engineering review
- Writing a design doc for a change that touches data models or public interfaces
- Documenting a decision after the fact so new team members can see why it was made
- Finding the questions you have not answered before a review meeting does
Why this prompt works
Questions before prose
A model given thin notes will still produce a full-length document, and the gaps get filled with reasonable-sounding inventions. The first round moves that guessing into the open as questions, capped at six and ordered by how much the answer would change the design, so you spend two minutes answering instead of an hour correcting.
Non-goals are defined in a useful way
Many specs list non-goals nobody would have expected anyway. Defining them as things a reader might reasonably assume are included makes the section do its real job, which is preventing scope arguments during review and after launch. It also tells the model what to leave out of the design.
Detail follows risk
The design section is told to spend words on what is novel or irreversible and stay brief on routine parts. That is how experienced authors write, and it keeps the document from giving equal space to a new data migration and a standard CRUD endpoint.
Alternatives have to be real
Reviewers discount a spec whose alternatives are straw men. Requiring at least two, with doing nothing among them, and forbidding deliberately weak options, pushes the model to state the actual trade-off that led to the proposal, which is the part reviewers most want to examine.
TBD with an owner beats a confident guess
An invented throughput figure or service name can survive into implementation. The rule that gaps become TBD entries naming who would know keeps the draft honest and gives you a list of people to talk to before the review, instead of errors to find afterward.
How to use it
- Paste your raw material into the problem and system fields: ticket text, notes, a rough sketch in words. Accuracy matters more than polish.
- State at least one thing that is out of scope, even if it seems obvious to you.
- Send the prompt and answer the questions it asks. If you do not know an answer, say so; it will become a TBD.
- Read the alternatives section critically. If the real runner-up is missing, name it and ask for that section again.
- Have someone who knows the system check every factual statement about how it works today.
- Resolve or assign the open questions, then move the text into your team's document template.
AI model compatibility
| Model | Status | Notes |
|---|---|---|
| ChatGPT | Expected to work | Answer the Round 1 questions in a numbered list that matches the model's numbering. It makes it easy to see later which answer a section of the spec was based on. |
| Claude | Expected to work | If you paste long notes, a ticket thread or an existing document as background, wrap each in XML-style tags such as <notes> so the model can tell source material from your instructions, as Anthropic's guidance recommends. |
| Gemini | Expected to work | If the draft arrives before any questions, restate that Round 1 must come first; Google's prompting guidance favors explicit, ordered instructions, so a direct reminder is usually enough. |
“Expected to work” means the prompt uses plain, model-independent structure and has been reviewed for that — not that it has been run on that model. A model is marked Tested only when a test record is published below.
Worked example
Scenario: An illustrative case: a team with a Rails API and mobile clients wants to change how image uploads work.
I need to write a technical specification that engineers will review and then build from. Act as a staff engineer helping me draft it. Your job is clarity and completeness, not persuasion. What I know so far - Project or feature: Move image uploads from the app server to direct-to-storage uploads - Problem and background: Uploads pass through the Rails app, which holds a worker for the whole transfer. Large photos from mobile connections time out, and users report failed uploads. - Goals, and anything explicitly out of scope: Images up to 50 MB upload reliably from mobile. App servers stop proxying file bytes. Out of scope: video, in-app image editing, changing the storage provider. - Current system and constraints: Rails API, React web client, React Native apps, S3 for storage. Image records live in an attachments table linked to posts. Older app versions must keep working for 90 days. - Approaches already discussed: Presigned upload URLs; a separate upload microservice; raising timeouts and adding workers - Who will read this: Engineers on other teams Round 1: questions Do not draft yet. Ask me up to six questions, the ones whose answers would most change the design. Prioritize: how success will be measured, scale and data volumes, failure behavior, compatibility with existing clients or data, security and privacy, and deadlines. Number them, and for each say in a few words why it matters. Then wait. Round 2: the spec After I answer, write the document with these sections. 1. Summary: one paragraph a busy reader can stop after. 2. Background and problem: what is true today and why it is not good enough. No solution yet. 3. Goals and non-goals: goals as outcomes that can be checked. Non-goals are things a reader might reasonably expect that this work will not do. 4. Proposed design: components, data flow, changes to data models and interfaces, and behavior when things fail. Describe a diagram in text where one would help. Include detail in proportion to risk: more for what is novel or irreversible, less for what is routine. 5. Alternatives considered: at least two, including doing nothing, each with the reason it was not chosen. 6. Rollout: migration steps, feature flagging, how to roll back, and what to monitor. 7. Testing: what will be verified and at which level. 8. Risks and mitigations: a table. 9. Open questions: each with a suggested owner role. Rules for the draft - Use only facts from my notes and answers. Where something is missing, write TBD and say who would know. Never fill a gap with a plausible number, service name or date. - Write for the stated audience. Define any term they would not know. - Do not present an alternative that is obviously weak just to make the proposal look good. - Plain declarative sentences. No marketing language. - No time estimates unless I supplied them.
What a good response should contain
- A first reply containing only numbered questions, for example about file validation and scanning, orphaned uploads and how old clients will be supported
- A spec whose non-goals include items a reader might expect, such as resumable uploads, if the answers put them out of scope
- A design section that gives the most space to the new upload flow, failure cases and the compatibility window
- Alternatives that treat raising timeouts as a real option with a specific reason for rejecting it
- TBD entries with a suggested owner for anything not supplied, such as current upload failure rates
This is an illustrative scenario showing how to fill in the prompt and what to look for. It is not a recorded model output. Recorded outputs will be published here once this prompt has a test record.
Testing and editorial review
Status: Untested. Reviewed for structure and clarity by the editorial team. No recorded model test yet.
No test record has been published for this prompt yet. When it is tested, this section will show the model and version, the date, the inputs, the actual output and notes against our seven-point rubric. We do not publish numerical scores.
| Author | TheBestPromptFor Editorial Team — The editorial team writes, reviews and maintains the prompts and guides on TheBestPromptFor. Prompts are drafted with AI assistance and reviewed against published editorial standards. |
|---|---|
| Published | November 15, 2026 |
| Last reviewed | November 15, 2026 |
| Last tested | Not yet tested |
| Version history |
|
Limitations and things to check
- The model knows your system only through what you write. Statements about current behavior need checking by someone who works on it.
- It can structure trade-offs but cannot weigh them with your team's priorities, budget or history.
- Security, privacy and compliance sections are prompts for review by the right people, not a substitute for it.
- Very long specs may be cut off. Ask for the remaining sections by number if that happens.
Alternative prompts
Web Development
REST API Design Prompt
Turns a description of your domain and consumers into a consistent REST contract: resources, endpoints, errors, pagination and open decisions.
- ChatGPT
- Claude
- Gemini
Web Development
Relational Database Schema Prompt
Designs a relational schema from your entities, rules and real queries: relationships, DDL, constraints and indexes that each trace to a query.
- ChatGPT
- Claude
- Gemini
- Cursor
Web Development
Next.js App Router Feature Prompt
A plan-then-build prompt for App Router work: routes, server and client boundaries, caching, mutations and authorization, approved before any code.
- ChatGPT
- Claude
- Gemini
- Cursor
Productivity
Structured Decision-Making Prompt
A two-round prompt: the model questions you first, then weighs your options against your criteria and argues against the one you already favor.
- ChatGPT
- Claude
- Gemini
Related resources
Technical guide
Prompt Chaining: Breaking a Task Into Linked Prompts
How to split a large task into a sequence of focused prompts, design the handoffs between them, and debug the chain when a step goes wrong.
Guide
How to Write a Good AI Prompt
The five parts of a complete prompt (goal, context, task, constraints, output format), with a worked rewrite and a pre-send checklist.
Guide
Prompt Templates vs Prompts: What Is the Difference?
A prompt is one complete request; a template is a reusable prompt with named variables. When to use each and how to turn one into the other.
Frequently asked questions
What is the difference between a technical spec and a product requirements document?
A requirements document says what should be built and why it matters to users. A technical spec says how it will be built: components, data, interfaces, rollout and risks. This prompt assumes the what is mostly settled and concentrates on the how.
Can I skip the question round?
You can, by telling the model to proceed without questions, but expect more TBD entries. The questions exist because the answers usually change the design section. If you already have a thorough brief, paste it and the model should need fewer of them.
How long should the finished spec be?
As long as the risk requires. A contained change might need a page; a data migration with compatibility constraints needs more. The prompt asks for detail in proportion to risk, so a short result for a small change is working as designed.
Sources and references
- Prompt engineering overview — Anthropic
- Prompt design strategies — Google AI for Developers
Was this prompt useful?
No account needed. Do not include personal information.