17.1 Idea → one-page spec in 10 minutes
Overview and links for this section of the guide.
On this page
Why a one-page spec is the greenfield superpower
Greenfield projects fail because requirements are fuzzy. With AI, fuzzy requirements become fast spaghetti.
A one-page spec prevents that by giving you:
- a stable target for “done,”
- a boundary for what the model should and should not build,
- a verification target (acceptance criteria),
- a way to review plans before code exists.
It’s how you keep the vibe loop fast without losing control. A good one-page spec takes minutes and saves hours.
The 10-minute method (timeboxed)
Set a timer for 10 minutes. Your goal is not perfection; it’s clarity.
- Minute 0–2: write the goal in one sentence + the user.
- Minute 2–4: write the main workflow (inputs → outputs).
- Minute 4–6: write constraints (runtime, deps, safety, scope).
- Minute 6–8: write acceptance criteria (mini tests).
- Minute 8–10: write non-goals + risks + open questions.
Stop when the timer ends. If it feels too big, shrink scope until it fits.
If you can’t describe it on one page, your first iteration should be smaller. Vibe coding thrives on small, runnable slices.
What the spec must contain
A minimal one-page spec contains:
- Goal: one sentence outcome.
- User: who uses it and why.
- Inputs/outputs: what comes in, what comes out.
- Constraints: runtime, deps, style, security rules.
- Acceptance criteria: 5–12 bullets you can test.
- Non-goals: what you are explicitly not doing.
- Risks/open questions: what could break or is undecided.
Everything else is optional.
How to define non-goals (anti-scope creep)
Non-goals are how you prevent “helpful feature creep.” Examples:
- “We are not building auth in v1.”
- “We are not storing data persistently in v1.”
- “We are not adding a web UI until the CLI pipeline is stable.”
- “We are not optimizing performance until SP3.”
Non-goals are not pessimism. They are focus.
Acceptance criteria (mini tests)
Acceptance criteria should be observable. Good formats:
- “Given X, output Y.”
- “If invalid input, return error Z with code/status.”
- “One command runs it; one command tests it.”
Include at least one failure case. That forces defensive behavior early.
“UI should be intuitive” is not testable. Convert it into something observable and verifiable.
Prompts to draft and refine the spec
Use the model as a spec drafting assistant, not as the spec authority. Two useful prompts:
Prompt A: draft the one-page spec
Help me draft a one-page spec for this idea:
[1–3 sentences describing your idea]
Output format:
- Goal (1 sentence)
- User (who and why)
- Inputs/Outputs
- Constraints (runtime, deps, safety)
- Acceptance criteria (8–12 bullets)
- Non-goals (5 bullets)
- Open questions (3–5)
Keep it to one screen. No code yet.Prompt B: critique for ambiguity and scope creep
Here is my one-page spec:
(paste)
Task:
- Identify ambiguities and hidden assumptions.
- Identify scope creep risks.
- Propose tighter acceptance criteria.
- Ask up to 5 clarifying questions.
Do not propose implementation yet.The model can propose, but you decide. The spec is your steering wheel.
Ship point: lock the spec
SP1 is “spec locked.” That means:
- goal, constraints, and acceptance criteria are written,
- non-goals are explicit,
- open questions are either answered or deferred intentionally.
Once locked, you can ask the model to produce an architecture plan. Without this ship point, you’ll keep rewriting the spec mid-implementation.
Copy-paste one-page spec template
# One-page Spec (v1)
Goal:
User:
Core workflow:
- Input:
- Output:
Constraints:
- Runtime:
- Dependencies:
- Security:
- Scope:
- Non-scope:
Acceptance criteria:
- [ ] ...
- [ ] ...
Non-goals:
- ...
Risks / open questions:
- ...