A sufficiently detailed spec is code • Hacker News Board

Re: A sufficiently detailed spec is code

#171

Post by yes_man » Thu, Mar 19, 2026, 8:19 AM UTC

jumploops wrote: post #160

In my experience with “agentic engineering” the spec docs are often longer than the code itself. Natural language is imperfect, code is exact. The goal of specs is largely to maintain desired functionality over many iterations, something that pure code handles poorly. I’ve tried inline comments, tests, etc. but what works best is waterfall-style design docs that act as a second source of truth to the running code. Us…

> In my experience with “agentic engineering” the spec docs should be longer than the code itself. Natural language is imperfect, code is exact.

The latter notion probably is true, but the prior isn’t necessarily true because you can map natural language to strict schemas. ”Implement an interface for TCP in ” is probably shorter than the actual implementation in code.

And I understand my example is pedantic, but it extends to any unambiguous definitions. Of course one can argue that TCP spec is not determimistic by nature because natural language isn’t. But that is not very practical. We have to agree to trust some axioms for compilers to work in the first place.

Re: A sufficiently detailed spec is code

#172

Post by Archer6621 » Thu, Mar 19, 2026, 8:20 AM UTC

debugnik wrote: post #152

Archer6621 wrote: post #141

Earlier quoted context omitted.

Actually, in the specific case of a 3D program it's the current generation of LLM's complete lack of ability in spatial reasoning that prevents them from "understanding" what you want when you ask it to e.g. "make a camera that flies in the direction you are looking at". It necessarily has to derive it from examples of cameras that fly forward that it knows about, without understanding the exact mathematical underpin…

> "make a camera that flies in the direction you are looking at" That's not the task of a renderer though, but its client, so you're talking past your parent comment. And given that I've seen peers one-shot tiny Unity prototypes with agents, I don't really believe they're that bad at taking an educated guess at such a simple prompt, as much as I wish it were true.

You're right. My point was more that LLMs are bad at (3D) math and spatial reasoning, which applies to renderers. Since Unity neatly abstracts the complexity away of this through an API that corresponds well to spoken language, and is quite popular, that same example and similar prototypes should have a higher success rate.

I guess the less detailed a spec has to be thanks to the tooling, the more likely it is that the LLM will come up with something usable. But it's unclear to me whether that is because of more examples existing due to higher user adoption, or because of fewer decisions/predictions having to be made by the LLM. Maybe it is a bit of both.

Re: A sufficiently detailed spec is code

#173

Post by lmm » Thu, Mar 19, 2026, 8:22 AM UTC

bad_username wrote: post #145

> There is no world where you input a document lacking clarity and detail and get a coding agent to reliably fill in that missing clarity and detail That is not true, and the proof is that LLMs _can_ reliably generate (relatively small amounts of) working code from relatively terse descriptions. Code is the detail being filled in. Furthermore, LLMs are the ultimate detail fillers, because they are language interpolat…

> LLMs _can_ reliably generate (relatively small amounts of) working code from relatively terse descriptions. Code is the detail being filled in.

They can generate boilerplate, sure. Or they can expand out a known/named algorithm implementation, like pulling in a library. But neither of those is generating detail that wasn't there in the original (at most it pulls in the detail from somewhere in the training set).

Re: A sufficiently detailed spec is code

#174

Post by ur-whale » Thu, Mar 19, 2026, 8:24 AM UTC

> A sufficiently detailed spec is code

Posting something like this in 2026: they must not have heard of LLMs.

And also: this is such a typical thing a functional programmer would say: for them code is indeed a specification, with strictly no clue (or a vague high level idea at most) as to how the all effing machine it runs on will actually conduct the work.

This is not what code is for real folks with real problems to solve outside of academic circles: code is explicit instructions on how to perform a task, not a bunch of constraints thrown together and damned be how the system will sort it out.

And to this day, they still wonder why functional programming almost never gets picked up in real world application.

Re: A sufficiently detailed spec is code

#175

Post by lmm » Thu, Mar 19, 2026, 8:25 AM UTC

prohobo wrote: post #139

Why is everyone still talking about markdown files as the only form of spec? The argument is true for text-based specs, but that's not the only option. Stop being so text-file-brained? This article is really attacking vague prose that pushes ambiguity onto the agent - okay, fair enough. But that's a tooling problem. What if you could express structure and relationships at a higher level than text, or map domain conce…

> - 1970s: abstracted away the algorithm -> OOP, standard libraries, UML

Which was mostly a failure, to the point that there is a major movement towards languages that "abstract away" (in this sense) less, e.g. Rust.

Certainly if the creators of UML are saying that AI is great, that gives me more confidence than ever that it's bunk.

Re: A sufficiently detailed spec is code

#176

Post by d--b » Thu, Mar 19, 2026, 8:32 AM UTC

> Misconception 1: specification documents are simpler than the corresponding code

That is simply not true. There is a ton of litterature around inherent vs accidental complexity, which in an ideal world should map directly to spec vs code. There are a lot of technicalities in writing code that a spec writer shouldn't know about.

Code has to deal with the fact that data is laid out a certain way in ram and on disk, and accessing it efficiently requires careful implementation.

Code has to deal with exceptions that arise when the messiness of the real world collides with the ideality of code.

It half surprises me that this article comes from a haskell developer. Haskell developers (and more generally people coming from maths) have this ideal view of code that you just need to describe relationships properly, and things will flow from there.

This works fine up to a certain scale, where efficiency becomes a problem.

And yes, it's highly probable that AI is going to be able to deal with all the accidental complexity. That's how I use it anyways.

Re: A sufficiently detailed spec is code

#177

Post by stanac » Thu, Mar 19, 2026, 8:34 AM UTC

jumploops wrote: post #160

In my experience with “agentic engineering” the spec docs are often longer than the code itself. Natural language is imperfect, code is exact. The goal of specs is largely to maintain desired functionality over many iterations, something that pure code handles poorly. I’ve tried inline comments, tests, etc. but what works best is waterfall-style design docs that act as a second source of truth to the running code. Us…

> The goal of specs is largely to maintain desired functionality over many iterations, something that pure code handles poorly.

IMHO this could be achieved with large set of tests, but the problem is if you prompt an agent to fix tests, you can't be sure it won't "fix the test". Or implement something just to make the test pass without looking at a larger picture.

Re: A sufficiently detailed spec is code

#178

Post by smartmic » Thu, Mar 19, 2026, 8:35 AM UTC

hintymad wrote: post #28

> A sufficiently detailed spec is code This is exactly the argument in Brooks' No Silver Bullet. I still believe that it holds. However, my observation is that many people don't really need that level of details. When one prompts an AI to "write me a to-do list app", what they really mean is that "write me a to-do list app that is better that I have imagined so far", which does not really require detailed spec.

I wouldn‘t say this is the core argument of No Silver Bullet. I wrote a short review of Brooks paper with respect to todays AI promises, to whoever is interested in more details:

https://smartmic.bearblog.dev/no-ai-silver-bullet/

Re: A sufficiently detailed spec is code

#179

Post by tomhow » Thu, Mar 19, 2026, 8:39 AM UTC

sjeiuhvdiidi wrote: post #47

Absolute nonsense. A sufficiently detailed "spec" is the code. What is wrong with you people ? Pure nonsense, all they have to offer.

Please don't fulminate on HN. The guidelines make it clear we're trying for something better here. https://news.ycombinator.com/newsguidelines.html

Re: A sufficiently detailed spec is code

#180

Post by jibal » Thu, Mar 19, 2026, 8:42 AM UTC

A piece of code is only one of many different implementations of a spec. And a good spec is careful to state what sort of variation is allowed and when rigid adherence is required.