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).

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

Whether it’s code or your advanced spec Sylvain (of which I have doubts about), humains won’t read it much in the future. Like I don’t read much assembly code today.

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.