An engineer at Notion opens a task, types a few paragraphs describing the feature he wants, drops in a screenshot, and @mentions an AI agent. Twenty minutes later a pull request comes back — the feature built, the interface checked with screenshots, a preview link ready to click. He didn't write the code. He wrote the description. The description was the work.

Ryan Nystrom walked through this on the How I AI podcast recently. Forget the plumbing behind it; the part worth copying is what his team now does with the working day. They keep plain-English spec files in the repo — a description of how a feature should behave, a few pointers to the relevant code, and a short list of steps to check it worked. When something needs to change, they change the spec and point the agent at it. The agent implements, verifies, and ships. The engineers spend their time getting the spec right.

Most of us will never have Notion's stack, and we don't need it. But the lesson underneath it applies to anyone using AI to do real work. The leverage has quietly moved from doing the thing to describing the thing well. I've made a version of this argument before, that AI hasn't turned everyone into an engineer so much as everyone into a product manager. Spec-driven development is what that looks like when a team takes it seriously. The brief stops being the annoying bit you rush through before the real work. The brief is the real work.

Two-row diagram. Old way: you describe briefly, then you do the work (highlighted), then done. New way: you write the spec (highlighted), the agent builds, you verify. The highlighted box marks where human effort now sits.

That's a different thing from keeping good context files, which I've written about before. Context helps the model remember the basics about you and how you like to work. A spec is narrower and harder: it tells the agent what a finished, correct piece of work looks like. One is a colleague who knows you; the other is a colleague who knows the job.

The uncomfortable part is that most of us are still briefing AI as if we were making small talk: a one-line prompt, a bit of back-and-forth, a shrug when the output isn't quite right. That was fine when AI was a clever autocomplete. Hand an agent something big enough to matter, though, and a vague brief bites you: you get a confident, fluent, plausible answer that's wrong in ways you won't spot until it's too late.

None of this is really about code, either. Ask an agent to draft your quarterly board update, build a pricing model in a spreadsheet, or write a run of onboarding emails, and the same discipline applies: the agent still needs an outcome to aim at, a test to measure itself against, and the right context to work from. Nobody's produced tidy before-and-after numbers for the fuzzier work yet, and it's hard to say exactly how far the discipline stretches beyond code. But the mechanics don't change with the medium, and testing it costs you a paragraph or two.

What a good brief actually contains

A spec is a different kind of object from a prompt, not just a longer one. The Notion engineers aren't writing more words for the sake of it — they're writing the few words that carry weight. If you want to borrow the discipline without borrowing the tooling, three things do most of the work.

  1. Describe the outcome, not the steps. Say what "done" looks like from the outside: what the reader sees, what the spreadsheet totals, how the email should land. Resist the urge to spell out every move; the how is exactly the part the agent is good at.
  2. Write the test. The most valuable line in any brief is the one that says how you'll know it worked. "The summary fits on one page and names every client by revenue." Give the agent a target it can measure itself against and half the drift disappears before it starts.
  3. Point at the context, don't paste it. Link the example, name the file, reference last quarter's version. Dumping everything into the prompt feels thorough, but it buries the signal — the context window wall I've written about before. The skill is choosing the smallest set of material that makes the task solvable.

The difference shows up fast in practice. A weak brief for that board update reads: "write our Q2 board update." A spec-style one reads: "Draft our Q2 board update for the board pack. Lead with revenue against plan, then cash runway in months, then the two risks we flagged last quarter and where they stand now. Neutral tone, no adjectives. It's done when a director could read it in two minutes and know whether to worry." Same request. Wildly different odds of getting back something you can actually send.

Say it out loud before you type it

One trick from the Notion workflow is worth stealing on its own. Nystrom often doesn't type his specs at all. He opens a voice recorder, talks through how the feature should work as if he were explaining it to a colleague, and hands the transcript to the agent to tidy into a proper document. It's faster than typing, but that isn't really why it works. When you talk something through out loud, you naturally explain the edge cases — the "oh, and if this happens…" bits you skip when you're typing tersely. The messiness is the point. It's where the useful detail hides.

There's a wider signal here too. The same week, one of Anthropic's own engineers, Thariq Shihipar, set off a small storm arguing that agents should stop replying in plain text and start using richer formats, so humans can keep pace with the volume they now produce. It looks like a different subject, but it's the same shift seen from the other end: the machines do more of the doing, and the human job narrows to framing the work and judging the result. The spec also matters more than it used to for a blunt, mechanical reason: models forget. Long sessions drift and decay, so a written spec becomes the one stable version of what you actually want, the thing you can point a fresh agent at tomorrow. The middle, the part we used to call the work, is being handed over.

This is good news, mostly

If that sounds like a downgrade, stay with me. Describing a piece of work clearly has always been the hard, valuable part. It's just that the effort of execution used to hide our fuzzy thinking. You can't lean on that any more. A weak brief now produces weak output at speed, which is arguably worse than no output at all. But a clear one goes further than it ever could, because you're no longer the bottleneck between the idea and the thing.

For a small business, that changes what's worth practising: not prompt tricks or chasing the newest model, but the plain, old-fashioned skill of saying exactly what you want, how you'll know you've got it, and what good looks like. The businesses that pull ahead with AI won't be the ones with the cleverest tools. They'll be the ones that learned to write a proper brief.

Quick answers

What's the difference between a prompt and a spec? A prompt is a request. A spec is a description of the finished thing, plus the test it has to pass. Prompts suit quick questions; specs suit anything you'd be annoyed to get wrong.

Do I need special tools to work this way? No. You can write a spec at the top of a chat window, in a Notion page, or in a Google Doc. The tooling makes it faster at scale, but the discipline (describe the outcome, write the test, point at the context) costs nothing to start.

Isn't this just prompt engineering under a new name? Not quite. Prompt engineering was about phrasing a request cleverly. This is about specifying an outcome clearly and letting the agent handle the how. It's closer to managing someone than wording a search.