Doc-driven development · one spec, one system

Disclaimer: The content shown on this page is generated by an AI model and is for reference only. It does not constitute any guarantee of results. Actual output and Credits consumption are subject to "Usage Details" in the console.

This walkthrough uses one example to run through "doc-driven" development: instead of writing code, you write a Technical Spec — spell out the features, algorithm rules, UI requirements, and acceptance criteria item by item, and the model delivers an entire runnable system in one shot. The bar shifts from "knowing how to code" to "knowing how to write requirements." The example is a fun encyclopedia challenge game for kids aged 6-12 (animals / space / geography / body / food; wrong answers go to a mistake book, two correct answers in a row to clear), pure frontend single-file, zero backend, zero keys — click online to play. Call chain: qwen3.8-max (reads the Technical Spec → outputs the complete single-file system in one shot). Actual test passed on the first try: all 6 features implemented, all 8 acceptance criteria met, with no manual fixes.

Actual output

The kids' encyclopedia challenge system generated in one shot from the Technical Spec. It supports real answering: wrong answers go to the mistake book, two correct in a row to clear, and progress survives refresh.

Fun encyclopedia challenge system screenshot

Click to try: Fun encyclopedia challenge

Step 1: Write the Technical Spec — this step makes or breaks it

Spell out the features, algorithm rules, UI requirements, and acceptance criteria item by item:

# "Fun Encyclopedia Challenge · Technical Spec"
## 1. Project background and target users
An encyclopedia knowledge challenge mini-program for kids aged 6-12. Kids have short
attention spans and strong competitiveness. The pain point is "getting a question wrong
once and then forgetting it" — they need repeated practice on mistakes. The core is a
mistake-driven challenge loop.
## 2. Tech stack and constraints
- Pure frontend single-file HTML (HTML+CSS+vanilla JS inline), zero external dependencies,
  zero CDN, zero backend
- Persistence uses only localStorage; must not request any network API
## 3. Core features
1. Three challenge modes: sequential challenge / random challenge / mistake adventure
2. Answering interaction: correct answer highlights green + animation encouragement;
   wrong answer marks the correct option + "Why is that?" story-style explanation
3. Mistake book (core): a wrong question must be answered correctly twice in a row to be
   cleared and removed (answering wrong midway resets the count); while under 2, show
   progress stars (1 star / 2 stars)
4. Statistics panel: challenges completed / correct answers / accuracy / mistakes remaining
5. Progress persistence: all stored in localStorage, auto-restored on reopen;
   "Restart" requires a confirmation
6. Category tags: animals / geography / space / body / food
## 4. UI requirements (for kids)
- Bright colors, rounded corners, large fonts; primary palette bright sky blue + sunny
  orange + grass-green accents
- Mode switching uses large buttons rather than text labels, easy for small hands to tap
- Correct answers get CSS animation + random emoji encouragement text
- Tappable areas no smaller than 44px; show a cheerful empty state when the mistake book
  is empty
## 5. Built-in question bank (conversational + story explanations, 12 questions)
{q:"What is the fastest animal in the world?", opts:[...], answer:0, tag:"animals",
 explain:"The cheetah is the sprint champion of the animal kingdom! It can run at
 120 km/h when sprinting……"}
...
## 6. Acceptance criteria
1. Opening a single .html runs it directly, no server needed
2. Wrong answers still appear in the mistake book after refresh; stats not lost
3. A mistake must be answered correctly 2 times in a row before it is cleared and removed;
   only 1 correct answer must not remove it
4. All three modes switchable; cheerful empty state when the mistake book is empty
5. Each question shows its category tag　6. Correct answers have animation + encouragement
7. Bright colors, large fonts, tappable areas ≥44px

Step 2: Build instruction

Paste the full Technical Spec text at the end of the instruction and send it to qwen3.8-max:

You are a senior frontend engineer. Strictly follow the Technical Spec below to build
a complete, directly runnable single-file HTML kids' fun encyclopedia challenge system.
Requirements: HTML/CSS/JS all inline; zero external dependencies; strictly implement
the three modes, the mistake-challenge rules (two correct answers in a row to clear and
remove, wrong answer midway resets the count, and show progress stars), category tags,
correct-answer animation and encouragement text, the statistics panel, and localStorage
persistence and reset; the UI must be for kids aged 6-12: bright colors, large fonts,
rounded corners, tappable areas no smaller than 44px; for details that need a decision,
implement them reasonably per the spec defaults without asking me.
Only output the complete single-file HTML source itself, starting from <!DOCTYPE html>.
[Technical Spec] {paste the full text above}

View actual output · 8 acceptance criteria verified one by one (real browser operations, 14 checks all passed)

The spec spelled out the algorithm rules and acceptance criteria. Each was verified by
real operations in the browser:

[Acceptance 1 · Wrong answer auto-enters mistake book + story explanation] Passed
Deliberately answered question 1 wrong ("fastest animal" chose "tiger") → tiger marked
wrong, cheetah marked correct; explanation used a story tone: "The cheetah is the
sprint champion of the animal kingdom! It can run at 120 km/h when sprinting, about the
speed of a car on a highway. But it can only run for a short while before getting tired."
Top stats synced: mistake book remaining 1

[Acceptance 2 · Correct answer has animation + encouragement text] Passed
Question 2 answered correctly (Saturn) → marked correct, "Great job! Here's a little red
flower" popped up, celebration animation appeared on the page

[Acceptance 3 · Progress not lost after refresh (localStorage)] Passed
Refreshed page → completed 2 / correct 1 / accuracy 50% / mistake book remaining 1,
fully preserved, not cleared

[Acceptance 4 · Mistake needs 2 correct in a row to clear (core rule)] Passed
Switched to "Mistake Adventure" → the previously wrong cheetah question appeared
First correct → mistake book still 1, showed "Got 1 star! One more correct and it's
cleared!"
Second correct → showed "Cleared! This mistake is gone!", mistake book became 0
Empty state: "Awesome! All mistakes are cleared! The mistake book is empty now ~ You're
a memory master!"

Conclusion: one call produced the output, all 8 acceptance criteria / 14 checks met,
with no manual fixes. This is the value of "doc-driven" — writing the algorithm rules
(two correct in a row to clear), UI requirements (tappable areas ≥44px), and acceptance
criteria into the doc makes the output verifiable, not just "roughly works." Conversely:
whatever the doc doesn't spell out, the model won't invent for you.

Notes

Write the doc clearly so it can be verified: Writing the algorithm rules (two correct in a row to clear), UI requirements (tappable areas ≥44px), and acceptance criteria into the doc makes the output verifiable, not just "roughly works"; whatever the doc doesn't spell out, the model won't invent for you.
Consumption: This playbook involves text generation (qwen3.8-max, one call produces an entire system). Generating a complete app is a long-output task; for reasoning models, thinking tokens dominate (this run used 24484 tokens, about 70% of total output), so single-call consumption is noticeably higher than ordinary Q&A — this is normal.
Hard constraint: A Token Plan Personal Edition API Key is only for interactive use within a coding/agent tool and must not be placed in automated scripts or application backends for non-interactive calls. This example was deliberately chosen as a zero-dependency, backend-free, single-file solution whose output contains no keys.

​Actual output

​Step 1: Write the Technical Spec — this step makes or breaks it

​Step 2: Build instruction

​Notes

Actual output

Step 1: Write the Technical Spec — this step makes or breaks it

Step 2: Build instruction

Notes