{"slug": "return-of-the-spec-why-ai-agents-are-reviving-the-software-specification", "title": "Return of the Spec: Why AI agents are reviving the software specification", "summary": "AI agents are reviving the practice of writing detailed software specifications, according to a developer post on CodeClaude. The post argues that agents make specs cheaper to write, better informed by codebase analysis, and usable as detailed prompts to automate development, reducing low-value interruptions while keeping human judgment for critical decisions.", "body_md": "# Return of the Spec\n\nAgentic development is bringing a resurgence of \"the specification\". Maybe you've been writing detailed specs all along, but I've been mostly following [Working software over comprehensive documentation](https://agilemanifesto.org/). To some it'll sound like I'm some combination of crazy and lazy, but historically I have not found heavy specs to be worth the time or effort for a number of reasons I'll get into later. Agentic development is forcing me to take a second look though. Here's why:\n\n## Here's what changed\n\n### They're easier to write now\n\nLong, detailed specs are cheaper and easier to write now, changing the ROI calculation dramatically. You can have an agent write them for the most part and you can just check them for correctness. I'll talk about how [later in this post](#how-to-write-good-specs-easily).\n\n### They're better informed\n\nAgents are also capable of understanding complex codebases much faster than I ever could, so the specs can be written much more quickly and can take a lot of the complexity of the codebase into consideration in advance. When trying to add a complex feature to a complex codebase, I used to just start chipping away without much investigation (e.g., I'd start by just writing a failing test, even though I couldn't remember how the code was implemented at all), but now the agents can understand the codebase in a few moments and help you write a much more informed spec up front.\n\n### They take the human out of the loop for longer\n\nBut the most important advantage of a detailed spec now (and the actual reason for the resurgence) is that it can be used as a detailed *prompt*.\n\nWhen the spec is really nailed down, you can sometimes set a [ /goal](https://code.claude.com/docs/en/goal) to satisfy the spec, let an agent spin up whatever subagents it needs, and let it run until the work is done. This frees you up to do other things.\n\nWhile this is the most valuable part, I want to be clear about the rationale: The goal is not fewer human decisions; it’s fewer low-value interruptions. You still want human judgment where it's actually necessary.\n\n## Why it wasn't worth it before\n\n- Traditional specifications are not executable like code or tests, and humans forget to update them after changes, so they get out of sync with reality quickly.\n- The automated tests (and the application code itself, though often less clearly) described how the software should behave, and they were actually executable.\n- It took a ton of time that I could have been spending writing code. It's not enough for specs to just be useful; they have to be worth the effort.\n\n## Isn't this just waterfall again?\n\nThere are 3 aspects of the spec that have traditionally been pretty [waterfally](https://martinfowler.com/bliki/WaterfallProcess.html):\n\n### The spec will invariably be wrong\n\nThe spec will invariably be wrong (either incompatible with the existing product/codebase, or not actually the best solution for the user/business) in some ways that we can't foresee. Sometimes it will be disastrously wrong. You just can't know everything in advance. We need to be iterative.\n\nIn my experience, agents that have access to the codebase can find many problems/questions/concerns with a plan that I hadn't thought about in advance. This allows the agents to be a tool for writing specs that are \"less wrong\" than specs I would have written on my own before agents existed.\n\n### Spending a long time on a specification doc is spending a long time without delivering actual solutions to user problems.\n\nThis is still true, but I think we have the tooling now to write good comprehensive specs really quickly. I hope I can prove that [later](#how-to-write-good-specs-easily).\n\n### Larger specs create larger batches and will create more problems downstream for reviewing and merging.\n\nWhen you create a large spec, you *can* (and probably should) break it up into [thin vertical slices](https://caines.ca/posts/2022-05-9-breaking-it-down-part-3/) for delivery. You don't need to get out of the feedback loop of a large plan; you can stay in that loop and verify whatever you want. A large spec doesn't need to change how you deliver things. It could actually include your delivery and validation plan, e.g., the actual slices, validation points, and stop conditions.\n\nI always recommend delivering the most uncertain parts first when possible (even if just as a limited availability prototype), so if your plan turns out to be a bad one, you learn earlier rather than later.\n\nUnlike in waterfall, these specs can and should be revisited whenever. They're not contracts. They don't promise to guarantee business or user success just by correct implementation. They're still not as valuable as working code. We still want to learn (and iterate) while building.\n\n## I still just delete them after implementation\n\nIn general I don't care about keeping specs around as documentation; they're meant only to be used for prompting in a short-term way. The codebase isn't necessarily documentation-free; for example I like [ADRs](https://cognitect.com/blog/2011/11/15/documenting-architecture-decisions) to explain WHY I made certain decisions (\"Why?\" is a question that code rarely answers well).\n\nThere's still not really anything to force natural language specs to be in sync with the actual behavior of the codebase in a deterministic way that I would trust, so with few exceptions I just throw the specs away after. The spec is scaffolding: useful while building, but disposable once tests and code guarantee the behavior. I don't want to risk an agent later reading an incorrect spec when it can read the tests or code. (It's worth noting that there are tools like [speckit](https://github.github.com/spec-kit/index.html) that are trying to bridge that gap.)\n\nMaybe I'll change my mind on this later, but I haven't yet. Since generating specs from existing code is so easy, I just haven't seen a need and I want to keep things as simple as possible. For now, a spec in plain English is disposable as soon as its behavior exists in automated tests and code.\n\nI'm also not at all suggesting you make the specification a shared artifact in your organization. I'm using it to agree on the details between the agent and me. It's not something that anyone else will review or approve.\n\n## How to write good specs easily\n\nObviously we should use agents to help write the specs, and I wanted to figure out how to do that with the fewest human-entered keystrokes as possible. The best prior art for that that I've found is [Matt Pocock's grill-me-with-docs skill](https://www.aihero.dev/grill-with-docs). You give it some tiny, massively under-defined description of what you're trying to do, and it asks you questions relentlessly to get a clear picture of what you want (along with near-instant understanding of the existing code) that it can document into a clear plan. It's absolutely amazing for spec writing.\n\nI made a few tweaks though, so answering was also faster and easier. I wanted it to...\n\n-\n...suggest possible answers so that the questions would be multiple choice (including an \"Other\" escape hatch for a plain text answer of course).\n\n-\n...assign each possible answer a \"certainty percentage\" chance that it thought the answer was correct so it could mark the highest confidence one as \"Recommended\". That made it so I could easily scan for the recommended answer and select it without reading the others if I liked it.\n\n-\n...actually stop itself from asking questions when the recommended answer for each remaining question had a certainty percentage higher than 75%. Pocock's skill will just grill you until you give up.\n\nHere's how it looks in practice:\n\n```\n› $plan-questions add github authentication\n\n• I’ll use plan-questions for this. I’m going to inspect the existing auth/domain docs first so I only ask questions that\n  aren’t already answered by the codebase.\n\n• Current backend already has Better Auth social providers for Google and Apple, and the web login has a Google button. I’m\n  checking mobile auth and environment/schema details next, because “GitHub authentication” could mean web-only, all clients,\n  or just provider configuration.\n\n• The code points to a generic OAuth launch path on iOS/Android, which reduces the provider-specific work. I’m reading the UI\n  entry points so I can separate simple button/provider additions from deeper account policy questions.\n\n• I’ve got enough to start grilling. One notable code fact: Android’s callback spec explicitly calls the flow “Google sign-\n  in,” but the callback plumbing is generic OAuth; if we add another provider, some domain language should become “social\n  sign-in” or “OAuth sign-in” rather than Google-specific.\n\n• Question 1: Scope\n\n  When you say “add GitHub authentication,” should GitHub be a supported social sign-in provider everywhere Winternote already\n  exposes social auth, or only on web?\n\n  A. All clients: web, iOS, and Android. Add GitHub beside Google on web and native OAuth surfaces, keep callback/token\n  behavior shared. Recommended, 70% certainty because the repo treats auth as a cross-platform product surface and mobile\n  already has generic OAuth plumbing.\n\n  B. Web only for now. Add backend env/provider config and a web login button, leave mobile unchanged.\n\n  C. Backend only. Configure Better Auth for GitHub but don’t expose UI yet.\n\n  My recommendation is A, but I’m under the 75% threshold because GitHub sign-in may be less useful or awkward on mobile\n  compared with Google/Apple.\n  \n> [ ]\n```\n\nI've got [my iteration, /plan-questions here](https://github.com/cainus/skillz/blob/main/skills/plan-questions/SKILL.md). Credit is primarily due to\n\n[Matt Pocock](https://www.aihero.dev/)though for almost all the thinking here. I love how he's grounded it in\n\n[domain-driven design](https://martinfowler.com/bliki/DomainDrivenDesign.html)to help you settle on terms for describing the type of work that you're doing. It really helps make communication between you and the agent (and the codebase) all the more clear.\n\n## I don't write specs for everything\n\nI certainly don't use specs for everything. For defects, for example I use [my /undefect skill](https://github.com/cainus/skillz/blob/main/skills/undefect/SKILL.md). A specification is just a tool you can use whenever you think is right.\n\nFor work that involves UI changes I will often additionally want to iterate on some kind of mockup of the UI changes as well, so I don't get a terrible UI on top of my detailed spec. A spec in English prose will rarely get those details right.\n\nI do often call `/plan-questions`\n\nfor tiny things though. Sometimes it has no questions, or sometimes it has just one. It's a tiny payoff but it's also a tiny effort.\n\n[← Back home](/)", "url": "https://wpnews.pro/news/return-of-the-spec-why-ai-agents-are-reviving-the-software-specification", "canonical_source": "https://caines.ca/posts/2026-08-15-return-of-the-spec/", "published_at": "2026-08-18 17:49:23+00:00", "updated_at": "2026-08-18 18:11:30.080424+00:00", "lang": "en", "topics": ["ai-agents", "developer-tools", "artificial-intelligence"], "entities": ["CodeClaude"], "alternates": {"html": "https://wpnews.pro/news/return-of-the-spec-why-ai-agents-are-reviving-the-software-specification", "markdown": "https://wpnews.pro/news/return-of-the-spec-why-ai-agents-are-reviving-the-software-specification.md", "text": "https://wpnews.pro/news/return-of-the-spec-why-ai-agents-are-reviving-the-software-specification.txt", "jsonld": "https://wpnews.pro/news/return-of-the-spec-why-ai-agents-are-reviving-the-software-specification.jsonld"}}