Post

I don’t agree with you Sylvain and I think the article does not either. People that have written specs that need to be implemented by several other systems, that spend countless hours to refine it, know that uncertainty and unclarity creeps in at every opportunity.

Lean and you leave loads of undefined semantic. Detail to fix that and English (let alone French) will turn your text into a very long, verbose and hard to parse text. That’s because human language has lots of uncertainty built in and fighting it falls under its own weight.

So to describe the what something like code ends up being better. And between English code and Java code, I know what I prefer to read, understand and navigate. Java is less expressive and more deterministic and syntactically structured. These constraints make it a good descriptor of WHAT.

But there is something to the cascading for artéfacts. A WHY artefact not to lose the big picture (say a readme), the HOW (agents.md, architecture.md) as a constraining set of requests (I say requests because the coding agent can ignore them), the high level WHAT (spec.md) and the real WHAT (code).

What is fascinating is that coding agents can adjust one based on the other and iterate on them like a pyramid. And coding agents do “fill the blank”, the unknown, the unsaid.

It’s quite uncanny and what defines these tools vs the other technologies before it. It makes some (stochastic and algorithmic based) judgment calls.

So what you propose should not be called a spec. It’s closer to code. And I don’t see English as being a good basis for it.

Crap I failed to reference @swallez.com and his post bsky.app/profile/swal...

I think in some way we agree. I was baffled by Symphony's "spec" which is actually a detailed design document, not far from what we used to feed MDA tools with. LLMs can indeed fill in the blanks for the underspecified parts of the spec. Like "those details are left as an exercise to the reader".