The Chaos Tax

You've been here: the AI writes something, you correct it, the correction breaks something else, and somehow the code keeps getting harder to read. You're not building anymore — you're managing the AI's misunderstandings.

That's the chaos tax. You pay it on every feature you try to ship with AI.

The root cause isn't the AI. It's that your requirements only exist in the chat. Chat history is not a spec. The AI fills every gap with a silent guess — what the component should do at its edges, what happens on error, how many is too many. Those guesses accumulate. That's the spiral.

The fix is boring and it works: write down what you're building before you start. Not a novel — a short proposal, a list of behaviors, a few edge cases. Enough that the AI is reading from a document instead of guessing from context.

OpenSpec is a CLI tool that gives that document a home and a workflow. It lives in your repo, travels with your code, and gives AI tools something real to read.

That's what this tutorial teaches. You'll build a toast notification system — a small, real-world UI component — using OpenSpec to drive every step. By the end you'll have a pattern you can apply to anything you build. This tutorial was built with OpenSpec Claude Code (v1.3.0) and code written by hand.