Scene Hook

Last Wednesday at 11pm, I was at home revising a landing page AI wrote for me—the 7th pass and still not right. I asked AI to change the button color, and it rewrote the entire layout. That moment I realized—I never told it what I wanted; I was just iterating by trial and error.

I've been stuck in this state too. The more I revised, the messier it got. I'd finish one version, toss it, and by the end even what I wanted had become blurry. The original author calls this "AI psychosis"—getting dragged around by AI's output, losing your own judgment.

What It Is + Who's Using

The solution is refreshingly simple: before letting AI touch any code, write a spec document in YAML first.

What's YAML? A plain text format that uses indentation to organize information—simpler than Excel:

landing_page:
 hero:
 headline: "Help freelancers manage clients"
 cta_button: "Sign up now"
 pricing:
 plan_free:
 price: 0

The original author, Andy, builds indie products in San Francisco. He used to describe things verbally every time he asked AI to write code—AI would half-understand, half-guess, wasting tons of time going back and forth. Later he started writing YAML specs first—listing out the page structure, field names, button text before handing it to AI. Accuracy doubled instantly.

I messed this up at first too. My specs were too detailed—I even specified font sizes, which actually constrained AI. Then I learned: specs should only define "what," not "how."

Replicate Cost Today

Money: $0. Time: 20-40 minutes to write a spec for a simple project, saving at least 2 hours of revision time. Technical barrier: if you can use Notepad, you're good. First step: open any text editor (TextEdit on Mac or Notepad on Windows), write your project name, then indent two spaces and list the main modules—that's your first spec. This isn't for everyone—if you're happy with AI's output on the first try, don't bother. No pressure to try it now.

Advice by Stage

Just starting out: If you're still using AI for single landing pages or simple copy, you can skip the spec. But if you've already gone through 3 revisions and still aren't satisfied, I'd suggest stopping to spend 20 minutes writing a spec—just list what sections this page has and what content goes in each.

Have 1-2 clients: I once built a mini-program for a client without writing a spec. The client said "this isn't what I meant," and I had to start over. Now I write a YAML spec first and send it to the client for confirmation—only after they confirm do I let AI start coding. This eliminated 80% of rework.

Scaling up: If someone on your team is also using AI, spec documents become your shared language. No need to verbally sync every time—drop a YAML file in the group chat and anyone can read it, anyone can edit it. This is the cheapest management tool I've used this year.