The Spec Is the New Source Code | Yushi's BlogThe Spec Is the New Source Code<br>28 May, 2026

The shift I didn&rsquo;t expect<br>The more I use coding agents, the less source code feels like the thing I personally write.<br>I know. Strange sentence from someone with a computer science background.<br>At university, the model was clean: humans write source code, the compiler turns it into machine code, and the final product runs from there. Source code was the serious artifact. You shaped it, reviewed it, argued over it, maintained it.<br>That model is still true. It just feels incomplete now.<br>In my day-to-day work with agents, the thing I keep touching is the spec. The PRD. The design note. The acceptance criteria. The markdown file where I try to explain, in plain human language, what this thing should do.<br>That file is starting to feel like the real source code.<br>How I got here<br>My path through AI coding tools has been gradual enough that I didn&rsquo;t notice the shift at first.<br>First it was autocomplete. Copilot suggested the next line, maybe the next small block. I was still writing the code. It just felt like typing with a very fast assistant beside me.<br>Then I moved to chat. Ask a question, copy the answer, paste a chunk of code, fix it, run it, repeat. Useful, but still manual. The model gave me pieces. I stitched them together.<br>Then the workflow changed again. I stopped asking for snippets and started giving tasks.<br>Investigate this bug. Add this feature. Update the tests. Refactor this flow.<br>The agent could read files, edit code, run commands, and loop on the result. Once that became normal, the hard part moved. It was no longer &ldquo;can I type the code fast enough?&rdquo; It was &ldquo;can I explain the work clearly enough that the agent builds the right thing?&rdquo;<br>So I started caring more about prompts. Then specs. Then keeping those specs clean and up to date. Not because I suddenly became a documentation person. Because the agent was only as good as the document I gave it.<br>From code-driven to spec-driven<br>When I write code by hand, I spend a lot of attention on how the thing works.<br>Which function calls which function. Where the state lives. What the data shape should be. How the edge case should be handled. That is the normal programmer brain, and I still need it.<br>But with a coding agent, I don&rsquo;t always start there anymore.<br>I start with questions like:<br>What should this feature do?<br>What should the user see?<br>What should happen in the weird case?<br>What is out of scope?<br>How will we know it is done?<br>Less &ldquo;how do I implement this line by line?&rdquo; More &ldquo;what are we actually building?&rdquo;<br>That pulls me upward. I find myself thinking more like a product person. The feature shape matters. The user flow matters. The tiny product decision that used to sit in my head now has to be written down, because otherwise the agent will invent an answer for me.<br>Sometimes the invented answer is fine. Sometimes it is quietly wrong. That is the scary version.<br>A new compiler in the middle<br>The old model in my head looked like this:<br>1human-written source code -> compiler -> machine code -> product

The new one looks closer to this:<br>1spec document -> coding agent -> source code -> compiler/runtime -> product

If I compress it, maybe it becomes:<br>1spec document -> agent-assisted compile process -> product

That middle part includes the coding agent, the generated source code, the tests, the build system, and the normal compiler or runtime. None of the old layers disappeared. The machine code is still there. The source code is still there.<br>But there is another translation step before the source code now.<br>This is the bit that keeps bothering me, in a good way. When the model is strong enough and the feedback loop is good enough, I spend less time inspecting every generated line. I still review. I still test. I still have to catch bad decisions. But I don&rsquo;t read the code in the same way I read code I wrote from scratch.<br>I read it against the spec.<br>Did the product behavior match what we said we wanted? Did the agent make an assumption that should have been written down? Did the generated code satisfy the tests for the real requirement, or just the easiest interpretation of the words?<br>That is a different kind of work.<br>The document becomes the source of truth<br>A vague spec is dangerous because a coding agent will not stop and feel awkward. It will make a reasonable guess and keep going.<br>That is useful when you are moving fast. It is also how you get a product that is almost right in five different places.<br>So the document needs to be treated more seriously. Not as a throwaway plan. Not as a meeting note that dies after implementation starts. The spec has to be maintained like code.<br>Version it. Review it. Keep it honest. Remove stale decisions. Add the weird cases after you discover them. Write down what is out of scope before the agent helpfully builds it anyway.<br>This is the part I did not expect to care about so much....