Funny, I've spoken about something like this to a colleague couple weeks ago. This could be a future of software development we're headed towards, if the DX is done right.

There are definitely cases where the spec is much easier to understand than the code that implements it.

Think systems with complex lifecycles or lots of required boilerplate.

Have you thought of embedding the specs into existing code?

E.g.

  # @spec: if any method takes longer than 1s to execute, a warning must be logged

  class X: ...