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

Why is the vibecoding crowd still holding onto the idea that markdown (or here yml) is a better spec then code?

Seriously, it's just not

Write your code like it's your spec and your software will be more stable, maintainable clearer to read.

Code is not transient, it is your friggin spec itself

And if your code isn't structured like it's a spec, then your code is garbage from the perspective of LLM driven development

Author here, if you don't want to read all that, I'll post one excerpt that I think sums it up nicely:

> My point is, the spec must live somewhere, even if you don’t write it down. The spec is what you want the software to be. It often exists only in your head or in conversations. You and your team and your business will always care what the spec says, and that’s never going to change. So you’re better off writing it down now! And I think that a plain old list of acceptance criteria is a good place to start. (That’s really all that `feature.yaml` is.)

Wow - I love programming in YAML! You know what would make this really fun? Sprinkle in some Jinja. Then we'll be cooking with gas.

Love the writing style!

> Nothing beats an organic, pasture-raised, hand-written spec.

Hah, I strongly empathize with the wording. I’ve been starting my design docs for fellow humans with “100% hand-written, organic content”, I might steal a part of yours.

Overall, cool idea. I don’t see myself using your SaaS, but the approach of tagging the requirements and constraints to make them easier to find sounds good.

One project you didn’t mention which I think is also, I think, a cool perspective on this is codespeak.dev , but I haven’t given it a go yet.

All in all, I feel like maintaining specs, and having agents translate spec diffs into code diffs is a promising area for the future. Good thing I enjoy writing!

Where is the part where the author overcomes ai psychosis? Reads like digging in deeper and deeper.

So...is this just Cucumber cough cough behavior driven design again, but stored in YAML so that LLMs can read it easier by loading the AST instead of tokenizing the text?

Unfortunate name collision between your ACID concept and the database principles (atomicity, consistency, isolation, durability).

I use OpenSpec for my spec management, and I scrolled down to the comparison. The gripe seems to be with a semantic difference. Specs describing a current system is the basis for AS/IS Gap Analysis.

Also, I mainly pursue these tools so that I can have AI accelerate this process and broker an agreement after negotiating specs with the agent.

Old ist new I guess. This is independent of whether A"I" or a human executes, the point is that you need this if specifying and execution lie apart, be it in time or space. This is basically the whole point of the V-Model and processes (if used correctly as a tool and not preferred as goals) and was already researched an formalized in the 60s and 70s.

I didn’t quite understand why YAML is better than Markdown for such specifications.

If the specification is written in such a strict format as YAML, I would expect it to be executable, something like this https://blog.fooqux.com/blog/executable-specification/

But as far as I understood, for acai that is not the case.

And once you’ve written all these specs you realize it became so slow that it’s faster to do it yourself in editor

It’s like a yaml of an event model but less graphical. Right? I think I will prefer Event Modeling especially with Martin Dilger now building tooling very much with agents in mind. There is no one place to read about his most recent efforts except for his LinkedIn feed though I fear.l so won’t post any urls, but information is easy enough to find.

A full blown event model facilitates all communication, human (management, devs, ops) and agentic. But maybe I’m missing something, maybe the dashboard can have this function I didn’t dig into it too much.

I'm still confused as to why folks don't just write executable specs.

I just spent a week training up in spec driven development through bmad, which was awful, and speckit which was ok but not great. Both had what seemed like unnecessary ceremony around the specs, generating fields of spec documents which presumably fill up the context window quickly. I just kept thinking "this should be using something simpler, all this markdown is unnecessary"

This seems like the answer to that thought!

What is yours agentic development experience with elixir? I used to like elixir a lot during a pre agentic era, but with coding agents it feels like the language isn't the best choice - slow compile time, weak type system (at least it was a year ago, I know there is work on that front), small ecosystem...

Completely subjective take, but I feel like 95% of these "tools" that are prompt-engineering inventions created by the authors with their bias and to suit their needs don't have anything supporting them besides the authors' subjective experience.

I have seen the same idea with processes, pipelines, lists, bullet points, jsons, yamls, trees, prioritization queues all for LLM context and instruction alignment. It's like the authors take the structure they are familiar with, and go 100% in on it until it provides value for them and then they think it's the best thing since sliced bread.

I would like, for once, to see some kind of exploration/abalation against other methods. Or even better, a tool that uses your data to figure out your personal bias and structure preference for writing specs, so that you can have a way of providing yourself value.

Try openspec: https://github.com/Fission-AI/OpenSpec/blob/main/docs/gettin...

Yesterday I heard about lat.md [1] which seems to have similar ideas about annotating code with spec refs. I now need to try them both.

[1] https://www.lat.md/

I’m building something similar with https://github.com/LabLeaks/special (apologies for the desultory slop-laden README, need to give that a lot more human attention) but I’ve gone in a slightly different direction: a “spec” is a product contract claim supported by attached tests that verify it. It’s a little Cucumber-y, if anyone remembers that, but a lot more flexible — you just write stuff like

  @spec LINT_COMMAND.ORPHAN_VERIFIES

  linter reports blocks that do not attach to a supported owned item.

Then

  #[test]
  // @verifies SPECIAL.LINT_COMMAND.ORPHAN_VERIFIES

  fn rejects_orphan_verifies_blocks() {
    let block = block_with_path("src/example.rs", &["@verifies EXPORT.ORPHAN"]);

    let parsed = parse_current(&block);

    assert!(parsed.verifies.is_empty());
    assert_eq!(parsed.diagnostics.len(), 1);
    assert!(
        parsed.diagnostics[0]
            .message
            .contains("@verifies must attach to the next supported item")
    );

}

And then the CLI command “special specs” pulls your specs and all attached verification + test code so you (or your LLM) to analyze whether the (hopefully passing!) test actually supports the product claim.

There’s also a bunch of other code quality commands and source annotations in there for architectural design & analysis, fuzzy-checking for DRY opportunities, and general codebase health. But on the overall principle, this article is dead-on: when developing with LLMs, your source of truth should be in your code, or at least co-located with it.

Small advice - make one repo “main” and link to it from the website instead of an organisation.

I wanted to star the project to track the progress but it feels a bit weird.. Which repo shall I track? Server? Cli? Sounds like a misc repos.

There are also Architectural Decision Records (ADRs), which might be something similar. https://adr.github.io/

Stopped at "Specsmaxxing".

> We are entering the post-slop era. My software is more robust, better tested, better integrated, and more observable than ever before. And my velocity keeps increasing!

Don't we just love the hard fact conclusions based on sample size N=1 and hand-waving arguments?

I'm tired, boss.

This industry has become a parody of itself, and people are celebrating.

I also have started numbering my Acceptance criteria and pushing that across the team(s). It’s going pretty well. Some note however are

1. Don’t write in yaml. It’s really hard for humans. Write in markdown and use a standard means to convert to lists / yaml.

2. Think beyond you writing your own specs - how does this expand into teams of tens or more. The ticketing system you have (jira? Bugzilla) is not designed for discussion of the acceptance criteria. I think we are heading into a world of waterfall again where we have discussions around the acceptance criteria. This is not a bad thing - is used to be called product management and they would write an upfront spec.

If this new world of a tech and a business user lead the writing of a new spec (like a PEP) and then then AI implements it and it’s put into a UAT harness for larger review and a daily cycle begins, we might have something.

Good luck

YAML is one of the worst technologies ever invented, it has more warts than features. One of the benefits of LLMs is that they can write YAML for me, wherever I am forced to use it.

Otherwise, I like the idea of machine-readable specs.

    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.

the token usage isn’t sustainable. formal english is a barrier but requirement for specification. brevity is the language of money and that’s the premise of management using ai.

fyi language alone can’t define/describe requirements which is why UML existed.

ugh with the "maxxing" everything

Could it be that slop PRs are less frequently rejected/commented due to (unfortunate) increased acceptance of it? As it turns out when maxxing AI on leaf parts of a program, the quality of the code doesn't matter that much anymore when compared to building the fundament.

Anything [prefix]maxxing just sounds so bad. It just feels so Andrew Tate...

More nonsense buzzword soup de jour. Can I play along at home? How about Vibewatermaxxing? Surely in the new age it should catch on.

This industry is just getting more and more bonkers.

What is it with people and procrastinating with the most useless shit you can imagine?

First it was choice of editor: people were micro optimizing every aspect of their typing experience, editor wars where people would literally slaughter over suggesting another camp.

Editor wars v2: IDEs arrived and second editor war began.

Revenge of the note taking apps: Obsidian/Roam/Joplin/Apple Notes/Logseq. Just one plugin, just one more knowledge graph, bro, and I’ll have peak productivity. 10x is almost here.

AI: you’re witnessing it now.

Do people NOT have anything else in life? How are y’all finding time to do all of this shit? Are you doing it on company time? Do you have hobbies, do you learn foreign languages, travel, have kids or spouses, drive a car, other thousand “normie” things outside of staring at the freaking monitor or thinking about this shit 24/7? Did I miss the invention of a Time Machine?

Grindmaxxing, a long form blog post that is actually just an advertisement for his website.

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.

[flagged]

[dead]

[dead]