{"slug": "write-code-not-specs", "title": "Write Code, Not Specs", "summary": "Software engineer Doug Turnbull argues that developers should prioritize writing code over specifications when working with AI coding agents, using tests as executable requirements to gradually expand the agent's trusted automation surface. He emphasizes maintaining human context and attention to quality, comparing the process to building a factory where hand-crafted prototypes inform higher-level automation.", "body_md": "In the before times, code was supposed to be self documenting. If it was good code, you could look at it and understand what it did.\n\nDoes that still matter? I think so.\n\nFor most of my projects I’ve maintained specs. Tried to get the agent to follow them. Carefully documented bits of English language functionality that described the system.\n\nBut that just means I have two systems. One imprecise. The other extremely precise. And now I have to maintain both.\n\nNow instead I write code. I establish the patterns. Within those areas, I have a high degree of trust in agent automation. Outside this carefully tilled garden, my trust diminishes. Trusting an agent here tends to be brittle. It requires high levels of detail and attention.\n\nAt that frontier, I’m moving more and more to a system where I just write some code. With the agent in tutor/reviewer mode, I establish a pattern of what I expect. I get more detail oriented. I think about the interfaces. Where I expect specific functionality to go. And write code until it works. The only way to develop this ‘taste’ is to do some of the work.\n\nWhat about the requirements? All the expected functionality?\n\nThat’s what tests do. (Remember this lesson from the before times?) I’d rather have executable language build the project than spec-based suggestions. At a certain level of maturity, the [tests become the code](https://softwaredoug.com/blog/2026/03/10/the-tests-are-the-code-now).\n\nWhen I trust a few tests actually test something, then I let an agent write more while I watch it like a hawk.\n\nThis gives me a gradually expanding surface of trust. Some areas I trust the agent to be extremely automated (and I’m protected against any stupid human changes). Other, newer areas, I want to be slower, careful, and gradual. I want to be thoughtful about the details.\n\nThen I push the frontier out gradually, maintaining a high level of precision and quality. Maintaining my own human context of the system along with the agent’s. Eventually the agent maintains 99% of the system - but I still have my long-running context of how it works.\n\nIn the end this may be as much about preference. My ability to pay attention is better served solving technical problems than writing specs, tabbing to social media, and coming back lost 15 minutes later. No matter how much better the agent gets at coding + debugging, I have the long term context. I’m responsible. My attention becomes the precious resource here.\n\nUsing coding agents isn’t a higher level of abstraction, it’s building a factory. You can’t build a factory without designing and hand-crafting prototype parts. Only then can you build up to higher levels of automation. You know how to establish quality assurance for each stage. You know what ‘good’ is from the completed car down to the drive train, transmission, gears, nuts, and bolts.\n\nA well running factory requires a mechanic’s skills. Not because even 0.001% of cars have some manual, human intervention. But because touching some cars improves the factory, develops tastes, and keeps the team obsessed with quality.\n\nFeel proud of touching code, it means you care how the factory works.\n\n### Enjoy softwaredoug in training course form!\n\n#### Starting May 18!\n\nSignup here -[http://maven.com/softwaredoug/cheat-at-search](http://maven.com/softwaredoug/cheat-at-search)\n\n[I hope you join me at](https://maven.com/softwaredoug/cheat-at-search)\n\n[Cheat at Search with Agents](https://maven.com/softwaredoug/cheat-at-search)to learn use agents in search. build better RAG and use LLMs in query understanding.", "url": "https://wpnews.pro/news/write-code-not-specs", "canonical_source": "https://softwaredoug.com/blog/2026/07/04/write-code-not-specs", "published_at": "2026-07-04 13:54:15+00:00", "updated_at": "2026-07-04 14:20:32.361652+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "ai-tools", "ai-research"], "entities": ["Doug Turnbull", "Maven"], "alternates": {"html": "https://wpnews.pro/news/write-code-not-specs", "markdown": "https://wpnews.pro/news/write-code-not-specs.md", "text": "https://wpnews.pro/news/write-code-not-specs.txt", "jsonld": "https://wpnews.pro/news/write-code-not-specs.jsonld"}}