Key Takeaways

  • Notion's engineers, led by Ryan Nystrom, are ditching traditional code-first development for a spec-driven approach. They start with comprehensive, plain English markdown documents, not a single line of code.
  • AI agents like Whisper (for dictation) and Codeex (for spec generation and code building) form the backbone of this system. Nystrom "yapped" a feature idea into Whisper, then fed it to Codeex to create the spec.
  • These markdown specifications are checked into version control, becoming the living "source of truth" for how features work. This visibility allows for easier iteration and understanding across product teams.
  • The shift frees engineers from "plumbing code" to focus on system architecture, design, and, most critically, building robust verification loops for AI-generated features.
  • This entirely new process is detailed in "Notion's Spec-Driven Development Workflow."

The Notion's Spec-Driven Development Workflow

  • Step 1: Ideation and Initial Dictation: I actually just opened up like whisper and just started yapping about how this feature should work.
  • Step 2: AI-Assisted Spec Generation: at the end of it I gave that I gave the YAP session to codeex and was like here's our other like spec library learn the format take my information write a spec.
  • Step 3: Spec Revision and Refinement: then it spiked the first version I did a couple uh revisions on it and I ended up with this markdown document.
  • Step 4: AI-Driven Implementation: I then opened up codeex again, pointed it at this spec file, and I said, "Build it." And it basically oneshotted this because the entire spec file is so comprehensive with code pointers with um down at the bottom we have verification.
  • Step 5: Code Review and Verification: I came back to whatever couple thousand lines, did some code review, played with it myself, and I was like, it's right. It's like done.
  • Step 6: Spec as Source of Truth and for Updates: The other beauty of this is like this is in version control. So I can go to the past changes of this spec file and I can see how the the spec has evolved. ... this is now the sort of like source of truth for how this part of notion AI works and it's just in plain English that can then be verified and implemented by agents.

When This Works (and When It Doesn't)

This workflow shines when you have well-defined system boundaries, established codebases, and clear behavioral requirements. As Ryan Nystrom puts it, “I view our job as like engineers evolving into like systems thinkers and architects and not and not even just necessarily writing like the spec and thinking about the behaviors but most importantly is like the verification loop like is it a like how should it verify correctness of this feature um or this change.” It is built for adding features or modifying existing parts of a complex system, where the AI can learn from existing patterns and a "spec library."

It might falter when tackling truly greenfield projects with entirely new architectures, highly abstract research problems, or when the problem space itself is fluid and ill-defined. The power comes from the AI's ability to "oneshot" implementation from a comprehensive spec. A vague spec will always mean vague, unusable code.

What to Do With This

This week, stop writing boilerplate code for your next feature. Instead, try a spec-first approach. Let's say you need to add a "notification preferences" section to your SaaS product.

First, open a voice recorder or a plain text document. Following Step 1, dictate everything about the feature: "Users should be able to select notification types (email, SMS, in-app) for new messages, weekly reports, and critical alerts. There should be a save button. Defaults are all on." Be as detailed as you can.

Next, pretend you have an internal "Codeex" equivalent. If you don't have an AI agent that can generate specs, take your dictated notes and manually structure them into a comprehensive markdown document, following Step 2 and Step 3. Define every component, every interaction, and most importantly, every verification step: "Verify email toggles send test emails. Verify SMS toggles send test SMS." Think about how a test suite would confirm correctness.

Finally, even without a "Build it" command, use this detailed spec as your blueprint. For Step 4 and Step 5, give it to your lead engineer or even an external contractor. Force them to "oneshot" the implementation as much as possible, using the spec as the single source of truth for all code and verification checks. This pushes you and your team into the architect and verifier roles, not just the coders.