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

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

> 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!

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.

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.

This seems like the answer to that thought!

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.

also, i wonder if people who did MDD (model driven development) have embedded AI in their methodology

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.

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

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

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.

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

  @spec LINT_COMMAND.ORPHAN_VERIFIES

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

  #[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.

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

    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]

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

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

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?

This industry is just getting more and more bonkers.

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.