Turn a spoken feature idea into a versioned Markdown spec, then let a coding agent implement and verify it. Future changes start in the spec, which records the behavior and its history.
Source episode · 32:00
How I AI: Ryan Nystrom's 3 Notion Workflows for Engineering Velocitywith Claire Vo
Ryan shows Notion's agent-specs folder, turns a Whisper brain dump into a Markdown spec, tells Codex to build it, and uses a CLI-backed verification section to test the feature.
A committed Markdown spec plus an implementation that the agent can test against the behaviors and verification steps defined in that spec.
OpenAI's cloud-based AI software engineering agent that can execute code, run tests, and handle complex multi-file tasks autonomously.
AI pair programmer
Step by step
Follow the sequence once, then adapt the prompts, checks, and handoffs to your own setup.
6 steps
Describe how the feature should behave without polishing the wording. Ryan opened Whisper and talked through Ask Mode, including what users could do and what should be restricted. Include examples, edge cases, and anything you are unsure about in the raw material.
Give the transcript to the coding agent with examples from your existing spec library. Ask for the same structure and require behavior, non-goals, code pointers, edge cases, and a Verification section with commands the agent can run.
Read the raw feature transcript below and the example specs in [spec library path]. Write a Markdown spec in the same format. Define user-visible behavior, non-goals, edge cases, relevant code pointers, and a Verification section with exact commands and expected results. Flag unresolved decisions instead of guessing. [Paste the transcript here]
Review the spec for behavior and testability, then commit it to the repository's spec folder. Ryan's team uses /agent-specs/. Use a descriptive filename and include the spec change in normal version control.
Point the coding agent to the committed spec and ask it to implement that document. The command can stay short because the requirements and verification loop already live in the repository.
Implement the feature defined in /agent-specs/[feature-name].md. Follow its code pointers and run every command in the Verification section. Update the implementation until the documented checks pass, then summarize the changed files and results.
Let the agent run the build and verification loop. Ryan's team gave Codex a CLI that could start Notion AI, send prompts, toggle Ask Mode, and inspect the response. Review the recorded commands and outputs, not only the final code diff.
When behavior changes, edit and commit the Markdown spec first. Ask the agent to bring the implementation and tests back into agreement, then preserve the spec revision and verification results in the same pull request.
The behavior in /agent-specs/[feature-name].md has changed. Update the implementation and tests to match the current spec, run the full Verification section, and report any code behavior that still conflicts with the document.
Turn an idea into a PRD, user stories, and a plan.
After the steps
How to recover when the loop fails and where human judgment helps.
Recover
Keep building
Use ChatGPT's multi-modal capabilities to automatically edit user-generated content (UGC) style videos. The AI can transcribe clips, select the best takes, assemble a narrative, and redact sensitive on-screen information.
use ChatGPT Sites to generate, build, and deploy a fully functional, data-backed website on a `chatgpt.site` domain using a single detailed prompt.
Use ChatGPT Voice with screen-aware context to delegate and parallel-process complex logistical tasks like booking travel and filing expense reports, all through a single conversation.
Join 100,000+ product managers who use ChatPRD to write better docs, align teams faster, and build products users love.