Comment by a1o

Hey just because you mentioned specs, we went back from the huge amount of md files to no md files at all and having the code being self documented for our AI based workflow (we have projects using AI and others with human workflow).

If necessary there is tooling to generate docs from the code itself. There is also tooling for code quality and other things. You can also use AI to help build deterministic tools for specific code quality verification you may want - all major languages have established ways to parse the code and generate easy to inspect AST and code metrics that can be used for arbitrary quality measurements.

The entire “API” (all the code objects and functions interfaces) were carefully architected so their “contracts” are well determined, with very explicitly defined types. The machine written code now can evolve it directly and it has much less impact on context, which allows using very cheap and fast models and reduce a lot of expense while producing quality and predictable code output. Just a heads up if you are still using many md files and relying too much on the big frontier models.