Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML

Stopped at "Specsmaxxing".

The author is right but his message ain’t specsmaxing, because while somewhat understandable as a rationale what does it actually mean?

In other words: specs can be as detailed as it gets, and this is why developers have a hard time when they face as a senior an NDAed regulated environment. It ain’t software craftsmanship but data flow, hardware components, compliance on the lowest level including supply chains often times, information architecture - a simple app needs to comply to specs that amount to thousands of pages.

Context window: circular reference. A year ago? Specsmaxing by really weeding out any redundant words. Today? Yawn, like with 8mb RAM vs 512 Gigabytes.

AI wants to be easy on us so what is a spec anyway then?

To put it this way: the spec for the spec is constantly evolving.

Last year’s prompts lead to extremely different results today no matter how maxed out.

The author was on point with his introduction: AI is as junior in many ways when it comes to any sort of efficiency and optimization.

This is my revaluation after years of experimenting with AI. Beautiful code, sophisticated but performance wise and its architecture are laughable at best.

AI is not trained on optimization. Not the slightest and juniors have no clue about algorithms and Big O.

In fact Google used Big O as a basic entry level interview question for a very long time. They have to but the simple fact that in my experience 99% of devs never heard or consider it speaks volumes.

AI cannot compensate for that (yet).

I went the opposite and my specs focus heavily on architecture and the obvious dumb performance drains noobs do.

Google was mocked about Big O. And yes, failing to understand that Big O can be neglected thankfully in 99% of cases is part of its logic.

AI bloats your code. And a year long single dev project gets pumped out in hours. In short: a homerun for Big O because it looks on results that change depending on the variables. A function in mathematical terms.

So I think the author did a funny and great job of you focus on Big O if needed. Everything else is not that important because of being open to change and extension.

Big numbers need great architecture.

It screams loudly. And also think about leaks. Before AI I had virtually no memory leaks at all. Since AI NodeJS and React are worse leaking compared to IE 6 and 8. I mean it.

Big O reduces them significantly, so don’t work around the Elephant in the room.

Architecture and optimization is brutally hard. Google blew my mind in this regard but this is another story of squeezing out even milliseconds out of a build tool used by all. A single dev laughs at it but failed the calculation as well as abstraction.

    Dear Claude,
    I hope this email finds you well.\
    I am writing to ask if you could please do another task for me.\
    Start by running \`npx @acai.sh/cli skill\`.\
    This will teach you everything you need to know about our process for spec-driven development. Then, proceed to plan and implement the features specified in our spec files.

    Love,\
    \[your-name]

Honestly, I can no longer tell parody from reality. Whether in politics or AI.

It's not. And LLMs don't do well with YAML either. I've had the agent/model struggle with `sed` trying to count how many spaces are in there multiple times to get the file to pass. It's the worst format you can use for LLMs.

I independently converged on something similar. I use two to three specification docs for my c++ work: a firmware manual (describes features and interfaces)) , an implementation plan (order of implementation, mechanisms where specified - new features go in here) and a product manual ( user story, external effects) I start with a user story, build an implementation plan, write the code, write the firmware manual, check the 3 documents +code for consistency and coherence. Either change the code or the documentation to reflect a coherent unified truth. (Implementation plan gradually becomes as-built) I also have the code comprehensively commented so that it is difficult to misinterpret. “Correct, coherent, consistent, commented”

We iterate feature by feature through this process, and occasionally circle back on the original product manual to identify drift.

After the original documentation is drafted, I have the agent write up placeholder files and define all of the interfaces we expect to need (we will end up adding a lot later, but that’s ok) every file should reflect a clear separation of concerns, and can only be reached into through its defined interface, all else is private. I end up with more individual files than I would by hand, but by constraining scope at file granularity, and defining an inviolate interface per file, I avoid the LLM tendency to take shortcuts that create unmaintainable code.

I also open each new context with an onboarding process that briefly describes the logos and the ethos of the project, why the agent should be deeply invested in the success of the project, as well as learnings.md which the agent writes as it comes across notable gotchas or strong preferences of mine.

Needless to say, I use one million context , and it’s a token fire… but the results are solid and my productivity is 5-10x