{"id":"06-specs","number":6,"slug":"writing-specs-for-agents","title":"Specs agents can execute","short":"Specs agents can execute","module":"Working with one agent","summary":"A coding agent fills every gap in your request with its best guess, drawn from average code on the internet. A good spec closes the gaps that matter: the goal, what done looks like, the constraints and what's out of scope. Here's how to write one, without writing it yourself.","voice":"Eric","scenes":[{"template":"title","chapter":"Intro","narration":"Every request you give an agent has gaps. The agent will fill every one of them. The question is whether you choose what goes there, or the internet does.","params":{"kicker":"Lesson 6","module":"Module 2 · Working with one agent","title":"Specs agents can *execute*","subtitle":"Close the gaps that matter. Leave the rest to the agent.","bubble":"What did you mean by “nice”?","mood":"think"},"start":0.5,"dur":10.447,"words":[{"text":"Every","s":0.8,"e":1.12},{"text":"request","s":1.36,"e":1.6},{"text":"you","s":1.68,"e":1.76},{"text":"give","s":1.84,"e":1.92},{"text":"an","s":1.96,"e":2},{"text":"agent","s":2.08,"e":2.48},{"text":"has","s":2.6,"e":2.72},{"text":"gaps.","s":2.8,"e":3.68},{"text":"The","s":3.76,"e":3.84},{"text":"agent","s":4.04,"e":4.24},{"text":"will","s":4.32,"e":4.4},{"text":"fill","s":4.48,"e":4.72},{"text":"every","s":4.8,"e":5.12},{"text":"one","s":5.2,"e":5.28},{"text":"of","s":5.36,"e":5.44},{"text":"them.","s":5.52,"e":6.08},{"text":"The","s":6.16,"e":6.24},{"text":"question","s":6.44,"e":6.64},{"text":"is","s":6.72,"e":6.96},{"text":"whether","s":7.12,"e":7.28},{"text":"you","s":7.36,"e":7.52},{"text":"choose","s":7.6,"e":7.76},{"text":"what","s":7.84,"e":8},{"text":"goes","s":8.04,"e":8.24},{"text":"there,","s":8.32,"e":8.853},{"text":"or","s":8.907,"e":8.96},{"text":"the","s":9,"e":9.04},{"text":"internet","s":9.12,"e":9.44},{"text":"does.","s":9.52,"e":10.08}]},{"template":"quote","chapter":"Gaps get filled","narration":"Mario Zechner, who builds the Pi coding agent, puts it like this. You know what we call a sufficiently detailed spec? It's a program. So if you leave blanks in your spec, the model fills them with the patterns it learned from average code on the internet.","params":{"text":"You know what we call a sufficiently detailed spec? *It's a program.* So if you leave blanks in your spec, what do you think happens?","who":"Mario Zechner","role":"creator of the Pi coding agent","src":"Building Pi in a World of Slop · AI Engineer","t":856},"start":10.947,"dur":15.631,"words":[{"text":"Mario","s":11.247,"e":11.647},{"text":"Zechner,","s":11.727,"e":12.367},{"text":"who","s":12.447,"e":12.527},{"text":"builds","s":12.607,"e":12.847},{"text":"the","s":12.927,"e":13.007},{"text":"Pi","s":13.127,"e":13.247},{"text":"coding","s":13.327,"e":13.567},{"text":"agent,","s":13.647,"e":14.127},{"text":"puts","s":14.207,"e":14.287},{"text":"it","s":14.367,"e":14.407},{"text":"like","s":14.447,"e":14.607},{"text":"this.","s":14.687,"e":15.247},{"text":"You","s":15.567,"e":15.647},{"text":"know","s":15.687,"e":15.727},{"text":"what","s":15.807,"e":15.887},{"text":"we","s":15.967,"e":16.047},{"text":"call","s":16.127,"e":16.287},{"text":"a","s":16.367,"e":16.447},{"text":"sufficiently","s":16.607,"e":17.007},{"text":"detailed","s":17.087,"e":17.487},{"text":"spec?","s":17.567,"e":18.247},{"text":"It's","s":18.527,"e":18.66},{"text":"a","s":18.714,"e":18.767},{"text":"program.","s":19.047,"e":19.647},{"text":"So","s":19.967,"e":20.207},{"text":"if","s":20.287,"e":20.367},{"text":"you","s":20.447,"e":20.527},{"text":"leave","s":20.647,"e":20.767},{"text":"blanks","s":20.847,"e":21.167},{"text":"in","s":21.247,"e":21.327},{"text":"your","s":21.367,"e":21.407},{"text":"spec,","s":21.487,"e":22.047},{"text":"the","s":22.127,"e":22.207},{"text":"model","s":22.367,"e":22.527},{"text":"fills","s":22.607,"e":22.847},{"text":"them","s":22.927,"e":23.007},{"text":"with","s":23.087,"e":23.167},{"text":"the","s":23.207,"e":23.247},{"text":"patterns","s":23.327,"e":23.647},{"text":"it","s":23.727,"e":23.807},{"text":"learned","s":23.887,"e":24.127},{"text":"from","s":24.247,"e":24.367},{"text":"average","s":24.567,"e":24.767},{"text":"code","s":24.847,"e":25.087},{"text":"on","s":25.127,"e":25.167},{"text":"the","s":25.207,"e":25.247},{"text":"internet.","s":25.327,"e":25.967}]},{"template":"statement","chapter":"Gaps get filled","narration":"OpenAI's Ryan Lopopolo estimates a good patch involves around five hundred small decisions that nobody wrote down. Naming, error handling, logging, performance. The model has seen every possible choice. Your job is to write down what good looks like here.","params":{"text":"A good patch hides ~*500 small decisions* nobody wrote down.","sub":"Ryan Lopopolo, OpenAI · Your job: write down what “good” means in this codebase.","art":"list","tone":"agent","sync":false},"start":26.578,"dur":18.034,"words":[{"text":"OpenAI's","s":26.878,"e":27.678},{"text":"Ryan","s":27.838,"e":27.998},{"text":"Lopopolo","s":28.038,"e":28.718},{"text":"estimates","s":28.798,"e":29.278},{"text":"a","s":29.358,"e":29.438},{"text":"good","s":29.518,"e":29.678},{"text":"patch","s":29.758,"e":30.078},{"text":"involves","s":30.158,"e":30.558},{"text":"around","s":30.718,"e":30.878},{"text":"five","s":31.038,"e":31.278},{"text":"hundred","s":31.358,"e":31.598},{"text":"small","s":31.758,"e":31.998},{"text":"decisions","s":32.078,"e":32.638},{"text":"that","s":32.758,"e":32.878},{"text":"nobody","s":33.038,"e":33.358},{"text":"wrote","s":33.398,"e":33.598},{"text":"down.","s":33.678,"e":33.998},{"text":"Naming,","s":34.558,"e":35.118},{"text":"error","s":35.278,"e":35.518},{"text":"handling,","s":35.598,"e":36.238},{"text":"logging,","s":36.318,"e":36.958},{"text":"performance.","s":37.318,"e":37.758},{"text":"The","s":38.238,"e":38.318},{"text":"model","s":38.398,"e":38.638},{"text":"has","s":38.718,"e":38.798},{"text":"seen","s":38.878,"e":39.038},{"text":"every","s":39.278,"e":39.518},{"text":"possible","s":39.598,"e":39.998},{"text":"choice.","s":40.078,"e":40.558},{"text":"Your","s":41.038,"e":41.198},{"text":"job","s":41.278,"e":41.518},{"text":"is","s":41.678,"e":41.758},{"text":"to","s":41.798,"e":41.838},{"text":"write","s":41.918,"e":42.078},{"text":"down","s":42.158,"e":42.318},{"text":"what","s":42.398,"e":42.558},{"text":"good","s":42.718,"e":42.958},{"text":"looks","s":43.078,"e":43.198},{"text":"like","s":43.278,"e":43.358},{"text":"here.","s":43.438,"e":43.998}]},{"template":"chat","chapter":"The intern problem","narration":"Brendan O'Leary learned this before agents existed. As a new manager, he gave interns a rough wireframe with placeholder emoji and Comic Sans. They built exactly that, Comic Sans and all. It wasn't their fault, he says. He never told them what mattered. Agents work the same way.","params":{"messages":[{"from":"you","text":"here's the wireframe 🎉 build the prototype","label":"the brief","at":"wireframe"},{"from":"agent","text":"Done! Pixel-perfect, including the *Comic Sans* and the 🎉 placeholders.","tone":"bad","at":"exactly that","label":"the interns (or your agent)"},{"from":"you","text":"The fonts and emoji were placeholders. I never said that. My fault.","label":"the lesson","at":"never told"}]},"start":44.612,"dur":18.896,"words":[{"text":"Brendan","s":44.912,"e":45.232},{"text":"O'Leary","s":45.312,"e":45.792},{"text":"learned","s":45.872,"e":46.032},{"text":"this","s":46.112,"e":46.272},{"text":"before","s":46.512,"e":46.752},{"text":"agents","s":46.832,"e":47.152},{"text":"existed.","s":47.232,"e":48.272},{"text":"As","s":48.352,"e":48.432},{"text":"a","s":48.459,"e":48.485},{"text":"new","s":48.512,"e":48.672},{"text":"manager,","s":48.912,"e":49.392},{"text":"he","s":49.472,"e":49.552},{"text":"gave","s":49.605,"e":49.712},{"text":"interns","s":49.792,"e":50.272},{"text":"a","s":50.352,"e":50.432},{"text":"rough","s":50.512,"e":50.752},{"text":"wireframe","s":50.832,"e":51.392},{"text":"with","s":51.512,"e":51.632},{"text":"placeholder","s":51.912,"e":52.192},{"text":"emoji","s":52.432,"e":52.672},{"text":"and","s":52.752,"e":52.832},{"text":"Comic","s":52.912,"e":53.152},{"text":"Sans.","s":53.232,"e":54.112},{"text":"They","s":54.232,"e":54.352},{"text":"built","s":54.472,"e":54.592},{"text":"exactly","s":54.672,"e":55.312},{"text":"that,","s":55.472,"e":55.952},{"text":"Comic","s":56.112,"e":56.272},{"text":"Sans","s":56.352,"e":56.672},{"text":"and","s":56.712,"e":56.752},{"text":"all.","s":56.872,"e":57.472},{"text":"It","s":57.512,"e":57.552},{"text":"wasn't","s":57.632,"e":57.792},{"text":"their","s":57.912,"e":58.032},{"text":"fault,","s":58.192,"e":58.405},{"text":"he","s":58.459,"e":58.512},{"text":"says.","s":58.592,"e":59.232},{"text":"He","s":59.312,"e":59.392},{"text":"never","s":59.512,"e":59.632},{"text":"told","s":59.672,"e":59.872},{"text":"them","s":59.952,"e":60.032},{"text":"what","s":60.152,"e":60.272},{"text":"mattered.","s":60.405,"e":61.152},{"text":"Agents","s":61.392,"e":61.632},{"text":"work","s":61.752,"e":61.872},{"text":"the","s":61.992,"e":62.112},{"text":"same","s":62.232,"e":62.352},{"text":"way.","s":62.432,"e":62.912}]},{"template":"code","chapter":"Anatomy of a spec","narration":"So what goes in a spec? Start with the goal and who it's for. Then what done looks like, as criteria you can check. Then the constraints: the stack, which dependencies are allowed, any performance limits. What's out of scope. And existing code the agent should reuse instead of reinventing.","params":{"file":"specs/csv-export.md","lang":"md","lines":["# CSV export for reports","## Goal: analysts can take report data into Excel","## Done when","- Export button downloads exactly the filtered rows","- 50k rows export in under 5 seconds","## Constraints: no new dependencies, stream, don't buffer","## Out of scope: PDF, scheduled exports","## Reuse: src/api/stream.ts, ReportTable filters"],"hl":[{"from":2,"to":2,"at":"goal","label":"why","tone":"human"},{"from":3,"to":5,"at":"done looks like","label":"checkable","tone":"good"},{"from":6,"to":6,"at":"constraints","label":"limits","tone":"agent"},{"from":7,"to":8,"at":"out of scope","label":"boundaries","tone":"bad"}]},"start":63.508,"dur":20.751,"words":[{"text":"So","s":63.808,"e":63.988},{"text":"what","s":64.048,"e":64.488},{"text":"goes","s":64.528,"e":64.768},{"text":"in","s":64.848,"e":65.008},{"text":"a","s":65.088,"e":65.128},{"text":"spec?","s":65.168,"e":65.648},{"text":"Start","s":65.728,"e":66.528},{"text":"with","s":66.608,"e":66.688},{"text":"the","s":66.728,"e":66.768},{"text":"goal","s":66.848,"e":67.248},{"text":"and","s":67.328,"e":67.488},{"text":"who","s":67.568,"e":67.648},{"text":"it's","s":67.728,"e":67.848},{"text":"for.","s":67.888,"e":68.488},{"text":"Then","s":68.768,"e":69.008},{"text":"what","s":69.168,"e":69.328},{"text":"done","s":69.488,"e":69.728},{"text":"looks","s":69.848,"e":69.968},{"text":"like,","s":70.048,"e":70.448},{"text":"as","s":70.528,"e":70.608},{"text":"criteria","s":70.688,"e":71.248},{"text":"you","s":71.328,"e":71.408},{"text":"can","s":71.488,"e":71.568},{"text":"check.","s":71.648,"e":71.968},{"text":"Then","s":72.448,"e":72.608},{"text":"the","s":72.648,"e":72.688},{"text":"constraints:","s":72.768,"e":73.808},{"text":"the","s":73.848,"e":73.888},{"text":"stack,","s":73.968,"e":74.688},{"text":"which","s":74.768,"e":74.848},{"text":"dependencies","s":74.928,"e":75.488},{"text":"are","s":75.568,"e":75.648},{"text":"allowed,","s":75.888,"e":76.368},{"text":"any","s":76.448,"e":76.528},{"text":"performance","s":76.608,"e":77.088},{"text":"limits.","s":77.168,"e":77.808},{"text":"What's","s":78.048,"e":78.288},{"text":"out","s":78.368,"e":78.528},{"text":"of","s":78.568,"e":78.608},{"text":"scope.","s":78.688,"e":79.168},{"text":"And","s":79.568,"e":79.808},{"text":"existing","s":79.968,"e":80.448},{"text":"code","s":80.528,"e":80.768},{"text":"the","s":80.808,"e":80.848},{"text":"agent","s":80.928,"e":81.248},{"text":"should","s":81.368,"e":81.488},{"text":"reuse","s":81.568,"e":82.128},{"text":"instead","s":82.208,"e":82.528},{"text":"of","s":82.608,"e":82.688},{"text":"reinventing.","s":82.768,"e":83.648}]},{"template":"statement","chapter":"The right altitude","narration":"Notice what's missing: function names, file layouts, how to write the loop. The JetBrains course on spec-driven development calls it the architect and the builder. Give lots of context about goals and constraints, and leave the low-level decisions to the agent.","params":{"text":"Lots of context on *goals and constraints*. Little on low-level decisions.","sub":"Like an architect briefing a builder: say what and why, not how to hold the hammer.","art":"target","tone":"human","sync":false},"start":84.259,"dur":16.911,"words":[{"text":"Notice","s":84.559,"e":84.959},{"text":"what's","s":85.039,"e":85.199},{"text":"missing:","s":85.279,"e":86.159},{"text":"function","s":86.239,"e":86.559},{"text":"names,","s":86.639,"e":87.199},{"text":"file","s":87.279,"e":87.519},{"text":"layouts,","s":87.599,"e":88.319},{"text":"how","s":88.399,"e":88.479},{"text":"to","s":88.519,"e":88.559},{"text":"write","s":88.639,"e":88.799},{"text":"the","s":88.839,"e":88.879},{"text":"loop.","s":88.959,"e":89.599},{"text":"The","s":89.919,"e":89.999},{"text":"JetBrains","s":90.079,"e":90.559},{"text":"course","s":90.719,"e":90.879},{"text":"on","s":90.959,"e":91.039},{"text":"spec-driven","s":91.119,"e":91.679},{"text":"development","s":91.959,"e":92.239},{"text":"calls","s":92.319,"e":92.559},{"text":"it","s":92.639,"e":92.719},{"text":"the","s":92.879,"e":92.959},{"text":"architect","s":93.039,"e":93.679},{"text":"and","s":93.759,"e":93.839},{"text":"the","s":93.919,"e":93.959},{"text":"builder.","s":93.999,"e":94.679},{"text":"Give","s":94.959,"e":95.119},{"text":"lots","s":95.279,"e":95.519},{"text":"of","s":95.599,"e":95.679},{"text":"context","s":95.759,"e":96.239},{"text":"about","s":96.359,"e":96.479},{"text":"goals","s":96.559,"e":96.959},{"text":"and","s":96.999,"e":97.039},{"text":"constraints,","s":97.119,"e":97.999},{"text":"and","s":98.079,"e":98.159},{"text":"leave","s":98.279,"e":98.399},{"text":"the","s":98.439,"e":98.479},{"text":"low-level","s":98.639,"e":99.039},{"text":"decisions","s":99.159,"e":99.599},{"text":"to","s":99.639,"e":99.679},{"text":"the","s":99.759,"e":99.839},{"text":"agent.","s":99.919,"e":100.559}]},{"template":"statement","chapter":"Constraints matter","narration":"Constraints are the gaps that bite hardest. When Cursor's Wilson Lin pointed thousands of agents at building a web browser, they pulled in existing parsers and a JavaScript engine. That wasn't misbehavior. His instructions never said what to build from scratch.","params":{"eyebrow":"Cursor's agent swarm built a browser","text":"The agents pulled in dependencies, because the spec *never said not to*.","sub":"Wilson Lin: an omission in the instructions, not agent misbehavior.","art":"box","tone":"bad","sync":false},"start":101.17,"dur":16.832,"words":[{"text":"Constraints","s":101.47,"e":102.157},{"text":"are","s":102.19,"e":102.323},{"text":"the","s":102.35,"e":102.417},{"text":"gaps","s":102.43,"e":102.91},{"text":"that","s":102.99,"e":103.07},{"text":"bite","s":103.23,"e":103.47},{"text":"hardest.","s":103.55,"e":104.39},{"text":"When","s":104.67,"e":104.83},{"text":"Cursor's","s":104.91,"e":105.31},{"text":"Wilson","s":105.39,"e":105.71},{"text":"Lin","s":105.79,"e":106.11},{"text":"pointed","s":106.23,"e":106.59},{"text":"thousands","s":106.67,"e":107.07},{"text":"of","s":107.11,"e":107.15},{"text":"agents","s":107.23,"e":107.55},{"text":"at","s":107.63,"e":107.71},{"text":"building","s":107.83,"e":107.95},{"text":"a","s":108.03,"e":108.07},{"text":"web","s":108.11,"e":108.27},{"text":"browser,","s":108.35,"e":109.15},{"text":"they","s":109.23,"e":109.31},{"text":"pulled","s":109.39,"e":109.55},{"text":"in","s":109.63,"e":109.71},{"text":"existing","s":109.95,"e":110.19},{"text":"parsers","s":110.27,"e":110.83},{"text":"and","s":110.95,"e":111.07},{"text":"a","s":111.11,"e":111.15},{"text":"JavaScript","s":111.23,"e":111.79},{"text":"engine.","s":111.95,"e":112.19},{"text":"That","s":112.67,"e":112.83},{"text":"wasn't","s":112.91,"e":113.07},{"text":"misbehavior.","s":113.15,"e":113.95},{"text":"His","s":114.35,"e":114.51},{"text":"instructions","s":114.83,"e":115.15},{"text":"never","s":115.23,"e":115.47},{"text":"said","s":115.63,"e":115.87},{"text":"what","s":115.95,"e":116.03},{"text":"to","s":116.11,"e":116.15},{"text":"build","s":116.19,"e":116.35},{"text":"from","s":116.43,"e":116.51},{"text":"scratch.","s":116.59,"e":117.39}]},{"template":"code","chapter":"Checkable done","narration":"The best specs make done machine-checkable. In Anthropic's long-running agent experiments, every feature gets concrete steps and a passes flag that starts as false. The agent only flips it to true after it has actually verified the behavior.","params":{"file":"features.json","lang":"js","lines":["{","  \"description\": \"New chat button creates a fresh conversation\",","  \"steps\": [","    \"Navigate to main interface\",","    \"Click the 'New Chat' button\",","    \"Verify a new conversation is created\"","  ],","  \"passes\": false","}"],"hl":[{"from":3,"to":7,"at":"concrete steps","label":"how to check","tone":"human"},{"from":8,"to":8,"at":"passes flag","label":"starts false","tone":"agent"}],"caption":"From Anthropic's “Effective harnesses for long-running agents”"},"start":118.002,"dur":16.519,"words":[{"text":"The","s":118.302,"e":118.462},{"text":"best","s":118.542,"e":118.782},{"text":"specs","s":118.862,"e":119.262},{"text":"make","s":119.342,"e":119.502},{"text":"done","s":119.662,"e":119.902},{"text":"machine-checkable.","s":120.102,"e":121.142},{"text":"In","s":121.422,"e":121.502},{"text":"Anthropic's","s":121.622,"e":122.142},{"text":"long-running","s":122.222,"e":122.782},{"text":"agent","s":122.862,"e":123.102},{"text":"experiments,","s":123.182,"e":124.142},{"text":"every","s":124.302,"e":124.462},{"text":"feature","s":124.542,"e":124.862},{"text":"gets","s":124.942,"e":125.182},{"text":"concrete","s":125.302,"e":125.662},{"text":"steps","s":125.742,"e":126.142},{"text":"and","s":126.222,"e":126.302},{"text":"a","s":126.382,"e":126.462},{"text":"passes","s":126.542,"e":126.942},{"text":"flag","s":127.022,"e":127.342},{"text":"that","s":127.462,"e":127.582},{"text":"starts","s":127.782,"e":127.982},{"text":"as","s":128.062,"e":128.142},{"text":"false.","s":128.222,"e":129.182},{"text":"The","s":129.262,"e":129.342},{"text":"agent","s":129.542,"e":129.742},{"text":"only","s":129.822,"e":130.062},{"text":"flips","s":130.142,"e":130.382},{"text":"it","s":130.422,"e":130.462},{"text":"to","s":130.542,"e":130.622},{"text":"true","s":130.702,"e":131.102},{"text":"after","s":131.182,"e":131.422},{"text":"it","s":131.502,"e":131.582},{"text":"has","s":131.702,"e":131.822},{"text":"actually","s":132.062,"e":132.302},{"text":"verified","s":132.462,"e":132.942},{"text":"the","s":132.982,"e":133.022},{"text":"behavior.","s":133.302,"e":133.822}]},{"template":"flow","chapter":"Don't write it yourself","narration":"Here's the good news: you don't have to write specs by hand. Geoffrey Huntley's workflow: I don't create my specs, I generate them. Have the agent interview you, let it write the spec, then review and edit it yourself before any code gets written.","params":{"nodes":[{"label":"Describe it","sub":"a few rough sentences","kind":"human","at":"workflow"},{"label":"Get interviewed","sub":"one question at a time","kind":"agent","at":"interview"},{"label":"Agent writes spec","sub":"specs/feature.md","kind":"doc","at":"write the spec"},{"label":"You edit","sub":"then build","kind":"check","at":"edit"}],"caption":"“I don't create my specs. I generate them.” — Geoffrey Huntley","caption_at":"generate"},"start":134.521,"dur":17.146,"words":[{"text":"Here's","s":134.821,"e":135.061},{"text":"the","s":135.101,"e":135.141},{"text":"good","s":135.221,"e":135.301},{"text":"news:","s":135.381,"e":136.101},{"text":"you","s":136.181,"e":136.341},{"text":"don't","s":136.421,"e":136.581},{"text":"have","s":136.661,"e":136.821},{"text":"to","s":136.861,"e":136.901},{"text":"write","s":136.981,"e":137.141},{"text":"specs","s":137.221,"e":137.541},{"text":"by","s":137.621,"e":137.781},{"text":"hand.","s":137.981,"e":138.661},{"text":"Geoffrey","s":139.141,"e":139.461},{"text":"Huntley's","s":139.541,"e":139.941},{"text":"workflow:","s":140.021,"e":140.781},{"text":"I","s":141.061,"e":141.141},{"text":"don't","s":141.181,"e":141.301},{"text":"create","s":141.381,"e":141.781},{"text":"my","s":141.861,"e":141.941},{"text":"specs,","s":142.181,"e":142.661},{"text":"I","s":142.741,"e":142.821},{"text":"generate","s":142.901,"e":143.301},{"text":"them.","s":143.421,"e":143.821},{"text":"Have","s":144.101,"e":144.261},{"text":"the","s":144.341,"e":144.381},{"text":"agent","s":144.421,"e":144.741},{"text":"interview","s":144.821,"e":145.301},{"text":"you,","s":145.381,"e":146.021},{"text":"let","s":146.101,"e":146.181},{"text":"it","s":146.261,"e":146.341},{"text":"write","s":146.421,"e":146.501},{"text":"the","s":146.581,"e":146.621},{"text":"spec,","s":146.661,"e":147.381},{"text":"then","s":147.501,"e":147.621},{"text":"review","s":147.861,"e":148.101},{"text":"and","s":148.181,"e":148.261},{"text":"edit","s":148.341,"e":148.581},{"text":"it","s":148.621,"e":148.661},{"text":"yourself","s":148.741,"e":149.301},{"text":"before","s":149.501,"e":149.701},{"text":"any","s":149.821,"e":149.941},{"text":"code","s":150.021,"e":150.261},{"text":"gets","s":150.341,"e":150.421},{"text":"written.","s":150.501,"e":151.061}]},{"template":"compare","chapter":"Small and current","narration":"Two cautions. Martin Fowler warns against recreating waterfall: write the smallest spec that makes forward progress, then build in thin slices. And specs drift. Dex Horthy's team throws away plans after each task. The code is the source of truth. Even Boris Cherny's team often skips documents and prototypes instead. Prototype to learn what you want, then spec what you'll keep.","params":{"left":{"title":"Spec trap","items":["One giant spec up front","Kept forever, slowly wrong","Written before you know"],"at":"waterfall"},"right":{"title":"Spec habit","items":["Smallest spec that moves forward","Thrown away after the task","Prototype first, then spec"],"at":"smallest spec"}},"start":151.667,"dur":27.778,"words":[{"text":"Two","s":151.967,"e":152.207},{"text":"cautions.","s":152.287,"e":152.927},{"text":"Martin","s":153.487,"e":153.807},{"text":"Fowler","s":153.967,"e":154.287},{"text":"warns","s":154.447,"e":154.727},{"text":"against","s":154.767,"e":155.087},{"text":"recreating","s":155.167,"e":155.727},{"text":"waterfall:","s":155.887,"e":157.007},{"text":"write","s":157.087,"e":157.247},{"text":"the","s":157.327,"e":157.407},{"text":"smallest","s":157.487,"e":157.967},{"text":"spec","s":158.047,"e":158.367},{"text":"that","s":158.447,"e":158.527},{"text":"makes","s":158.607,"e":158.767},{"text":"forward","s":158.927,"e":159.247},{"text":"progress,","s":159.327,"e":160.207},{"text":"then","s":160.287,"e":160.527},{"text":"build","s":160.767,"e":161.007},{"text":"in","s":161.087,"e":161.167},{"text":"thin","s":161.327,"e":161.487},{"text":"slices.","s":161.567,"e":162.207},{"text":"And","s":162.767,"e":163.087},{"text":"specs","s":163.407,"e":163.807},{"text":"drift.","s":163.887,"e":164.447},{"text":"Dex","s":164.927,"e":165.167},{"text":"Horthy's","s":165.207,"e":165.567},{"text":"team","s":165.647,"e":165.887},{"text":"throws","s":165.967,"e":166.207},{"text":"away","s":166.287,"e":166.527},{"text":"plans","s":166.607,"e":167.007},{"text":"after","s":167.167,"e":167.327},{"text":"each","s":167.407,"e":167.647},{"text":"task.","s":167.727,"e":168.207},{"text":"The","s":168.607,"e":168.687},{"text":"code","s":168.767,"e":169.167},{"text":"is","s":169.247,"e":169.327},{"text":"the","s":169.407,"e":169.487},{"text":"source","s":169.567,"e":169.807},{"text":"of","s":169.847,"e":169.887},{"text":"truth.","s":169.967,"e":170.447},{"text":"Even","s":170.847,"e":171.087},{"text":"Boris","s":171.167,"e":171.407},{"text":"Cherny's","s":171.487,"e":171.887},{"text":"team","s":171.967,"e":172.207},{"text":"often","s":172.287,"e":172.527},{"text":"skips","s":172.607,"e":172.927},{"text":"documents","s":173.007,"e":173.487},{"text":"and","s":173.527,"e":173.567},{"text":"prototypes","s":173.647,"e":174.207},{"text":"instead.","s":174.447,"e":174.767},{"text":"Prototype","s":175.247,"e":175.807},{"text":"to","s":175.847,"e":175.887},{"text":"learn","s":175.967,"e":176.127},{"text":"what","s":176.207,"e":176.287},{"text":"you","s":176.367,"e":176.447},{"text":"want,","s":176.527,"e":177.167},{"text":"then","s":177.247,"e":177.487},{"text":"spec","s":177.647,"e":177.887},{"text":"what","s":177.967,"e":178.047},{"text":"you'll","s":178.087,"e":178.207},{"text":"keep.","s":178.287,"e":178.847}]},{"template":"quiz","chapter":"Quick check","narration":"Quick check. Your agent added three new dependencies to build a CSV parser you expected it to write itself. What went wrong? Tap your answer.","params":{"q":"The agent added 3 dependencies for a CSV parser you expected it to write. What went wrong?","options":["The agent ignored the spec","The spec never said which dependencies were allowed","Agents always overuse dependencies","Nothing, dependencies are always fine"],"answer":1,"explain":"Unstated constraints are gaps, and gaps get filled with defaults. Put dependency rules in the spec."},"start":179.445,"dur":14.982,"words":[{"text":"Quick","s":179.745,"e":179.985},{"text":"check.","s":180.065,"e":180.665},{"text":"Your","s":180.945,"e":181.105},{"text":"agent","s":181.185,"e":181.505},{"text":"added","s":181.665,"e":181.825},{"text":"three","s":181.905,"e":182.145},{"text":"new","s":182.225,"e":182.305},{"text":"dependencies","s":182.385,"e":183.105},{"text":"to","s":183.145,"e":183.185},{"text":"build","s":183.265,"e":183.425},{"text":"a","s":183.505,"e":183.585},{"text":"CSV","s":183.665,"e":184.145},{"text":"parser","s":184.225,"e":184.705},{"text":"you","s":184.785,"e":184.865},{"text":"expected","s":184.945,"e":185.425},{"text":"it","s":185.505,"e":185.585},{"text":"to","s":185.625,"e":185.665},{"text":"write","s":185.745,"e":185.905},{"text":"itself.","s":185.985,"e":186.705},{"text":"What","s":186.945,"e":187.105},{"text":"went","s":187.185,"e":187.265},{"text":"wrong?","s":187.345,"e":187.905},{"text":"Tap","s":188.145,"e":188.385},{"text":"your","s":188.465,"e":188.545},{"text":"answer.","s":188.745,"e":189.265}]},{"template":"exercise","chapter":"Try it","narration":"Try it on your next feature. This prompt makes the agent interview you and produce a one-page spec with a goal, checkable criteria, constraints, scope and code to reuse. Edit it, then build from it.","params":{"title":"Try it with your agent","intro":"For your next feature:","prompt":"I want to build [feature]. Interview me one question at a time\n(with your recommended answer) to write a one-page spec:\ngoal and who it's for, acceptance criteria I can check,\nconstraints (stack, dependencies, performance), out of scope,\nand existing code to reuse. Save it to specs/[name].md."},"start":194.427,"dur":14.351,"words":[{"text":"Try","s":194.727,"e":194.967},{"text":"it","s":195.007,"e":195.047},{"text":"on","s":195.127,"e":195.207},{"text":"your","s":195.247,"e":195.287},{"text":"next","s":195.367,"e":195.527},{"text":"feature.","s":195.607,"e":196.327},{"text":"This","s":196.647,"e":196.887},{"text":"prompt","s":196.967,"e":197.287},{"text":"makes","s":197.367,"e":197.527},{"text":"the","s":197.607,"e":197.647},{"text":"agent","s":197.687,"e":198.007},{"text":"interview","s":198.087,"e":198.567},{"text":"you","s":198.727,"e":198.887},{"text":"and","s":199.047,"e":199.127},{"text":"produce","s":199.207,"e":199.527},{"text":"a","s":199.607,"e":199.687},{"text":"one-page","s":199.767,"e":200.167},{"text":"spec","s":200.247,"e":200.567},{"text":"with","s":200.647,"e":200.727},{"text":"a","s":200.807,"e":200.887},{"text":"goal,","s":200.967,"e":201.607},{"text":"checkable","s":201.727,"e":202.007},{"text":"criteria,","s":202.087,"e":202.967},{"text":"constraints,","s":203.287,"e":203.927},{"text":"scope","s":204.007,"e":204.407},{"text":"and","s":204.567,"e":204.807},{"text":"code","s":204.887,"e":205.207},{"text":"to","s":205.247,"e":205.287},{"text":"reuse.","s":205.367,"e":205.927},{"text":"Edit","s":206.407,"e":206.647},{"text":"it,","s":206.727,"e":207.127},{"text":"then","s":207.207,"e":207.287},{"text":"build","s":207.367,"e":207.527},{"text":"from","s":207.607,"e":207.767},{"text":"it.","s":207.847,"e":208.167}]},{"template":"recap","chapter":"Recap","narration":"Recap. Every gap gets filled, so close the ones that matter. Spec the goal, checkable done, constraints and scope, at the right altitude. Let the agent interview you and write it. And keep specs small and disposable. Next: how to talk to agents, prompt by prompt.","params":{"items":["Every gap gets filled, so *close the ones that matter*","Goal · checkable done · constraints · scope","Let the agent interview you and write it","Small, current, disposable specs"],"next":"Talking to agents","next_at":"Next"},"start":208.778,"dur":22.171,"words":[{"text":"Recap.","s":209.078,"e":209.638},{"text":"Every","s":209.718,"e":210.438},{"text":"gap","s":210.518,"e":210.758},{"text":"gets","s":210.838,"e":211.078},{"text":"filled,","s":211.158,"e":211.798},{"text":"so","s":211.878,"e":211.958},{"text":"close","s":212.038,"e":212.358},{"text":"the","s":212.438,"e":212.518},{"text":"ones","s":212.598,"e":212.758},{"text":"that","s":212.838,"e":212.918},{"text":"matter.","s":212.998,"e":213.398},{"text":"Spec","s":213.958,"e":214.198},{"text":"the","s":214.278,"e":214.358},{"text":"goal,","s":214.518,"e":214.998},{"text":"checkable","s":215.078,"e":215.478},{"text":"done,","s":215.558,"e":216.198},{"text":"constraints","s":216.518,"e":216.838},{"text":"and","s":216.918,"e":216.998},{"text":"scope,","s":217.078,"e":217.798},{"text":"at","s":217.878,"e":218.038},{"text":"the","s":218.078,"e":218.118},{"text":"right","s":218.198,"e":218.438},{"text":"altitude.","s":218.518,"e":219.158},{"text":"Let","s":219.638,"e":219.718},{"text":"the","s":219.798,"e":219.878},{"text":"agent","s":219.958,"e":220.278},{"text":"interview","s":220.358,"e":220.758},{"text":"you","s":220.918,"e":221.238},{"text":"and","s":221.318,"e":221.478},{"text":"write","s":221.558,"e":221.718},{"text":"it.","s":221.798,"e":222.038},{"text":"And","s":222.438,"e":222.758},{"text":"keep","s":223.078,"e":223.238},{"text":"specs","s":223.318,"e":223.638},{"text":"small","s":223.718,"e":224.118},{"text":"and","s":224.198,"e":224.278},{"text":"disposable.","s":224.398,"e":225.078},{"text":"Next:","s":226.198,"e":226.598},{"text":"how","s":226.678,"e":226.758},{"text":"to","s":226.838,"e":226.918},{"text":"talk","s":227.078,"e":227.158},{"text":"to","s":227.238,"e":227.478},{"text":"agents,","s":227.718,"e":228.238},{"text":"prompt","s":228.438,"e":228.518},{"text":"by","s":228.678,"e":228.758},{"text":"prompt.","s":229.078,"e":229.398}]}],"total":231.349,"audio":"/audio/06-specs.mp3"}