README-First Development: Write the Docs Before You Write the Code

Why docs first: documentation is the litmus test for requirements

Most rework in vibe projects isn't slow coding — it's discovering mid-build that the requirements were never clear. "What is this button supposed to do?" "How many steps is this flow, exactly?" Questions that surface during coding are the most expensive to fix. README-first logic is simple: if you can't write a clear doc describing the feature, you haven't thought it through and don't deserve to start coding.

This is adapted from Amazon's six-page-narrative culture: write the narrative before the meeting; can't write it, don't meet. For vibe coders, the README is your six-pager — and AI loves it: hand it a finished README and the odds of one-shot code generation jump dramatically.

The README-first workflow: four steps

Step 1: write "what this is." Three sentences: what the project/feature does, who it's for, what problem it solves. Can't write it? Stop here — this is the requirements' pass/fail line.

Step 2: write "how to use it." Write the user flow as an end user would experience it: what you click first, what you see second, what the error states look like. This forces every step of the flow into clarity; many "we'll figure it out later" traps surface here.

Step 3: write "what it looks like." Describe key screens in words or ASCII sketches: which regions, where the core actions live. Doesn't need to be pretty; needs to be concrete — "an export button top-right" beats "clean beautiful UI" a hundredfold.

Step 4: feed the README to the AI. Tell the agent directly: "Implement per this README; the doc is the acceptance criteria; self-check against it when done." The README transforms from documentation into an executable spec.

Three practical tips

First, write the README for someone who wasn't in the room. Imagine the reader is a friend who heard none of the discussion — anywhere needing verbal explanation signals an unclear requirement.

Second, thinking in your native language first is fine; don't skip the thinking. Many vibe coders have AI draft the English README directly — pretty doc, fuzzy requirements. Get the logic straight in Chinese first, then have AI translate and polish.

Third, when code changes, the README changes with it. README-first's failure mode is "write and abandon" — requirements always shift during implementation. Update the README before the code on every change, and your docs stay current instead of becoming a three-month-old relic nobody trusts.

The one-line summary

README-first isn't bureaucracy; it's front-loading the most expensive thinking: one hour of docs saves ten hours of rework. For AI, a good README is the best prompt; for you, it's proof the requirements are actually clear.