Hacker News Board Hacker News, browsed like a classic message board
Live data from Hacker News

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

acai.sh

Post reply on HN
Print view View original

121–130 of 316 posts

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

#121

Post by try-working »

mike_hearn wrote: post #107
nalpha wrote: post #29

Earlier quoted context omitted.

What's the difference between this and Jira. Your specs already live somewhere, it's where you defined them. That's why it's nice to put the Jira ticket number in your code / commit, so you can refer back to the spec when something breaks

A specification isn't a series of change requests! Using Jira as your source of truth is no different to just recording all your prompts. There's nothing you can easily review to spot contradictions or how things interact with one another. I've been doing "specmaxxing" for a few months now. Unlike the author I don't use Yaml, I use a mix of Markdown and Gherkin. If you haven't encountered Gherkin before, it's not new…

I solved this five months ago with recursive-mode: recursive-mode.dev/introduction

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

#122

Post by colechristensen »

brendanmc6 wrote: post #2

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…

So what I'm building is a github clone with epics/issues/kanban + specs/requirements/standards + CI/testing/coverage with the idea that all of those things connect so issues+requirements+testing all interact via code+webUI+CLI the point being that we can specify how a product is to function and the steps to get there and it's less a matter of telling a person or an LLM to read and implement the spec and more software actually keeping track at all times.

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

#123

Post by try-working »

gnat wrote: post #24
gnat wrote: post #14

Earlier quoted context omitted.

Nice! Your spec-maxxing is very resonant. I've been doing working with explicit requirements: elicit them from conversation with me or introspecting another piece of software; one-shot from them; and keep them up-to-date as I do the "old man shouts at Claude" iterations after whatever one-shotting came up with. Unlike you, I wish for the LLM to do as much of the work as possible -- but "as possible" is doing a lot of…

Forgot to add: I get several benefits from doing this. 1. Specifications that live outside the code. We have a lot of code for which "what should this do?" is a subjective answer, because "what was this written to do?" is either oral legend or lost in time. As future Claude sessions add new features, this is how Claude can remember what was intentional in the existing code and what were accidents of implementation. A…

Specifications doesn't tell you what to do, they say what the end state should be. In between that you need a codebase analysis step and an implementation plan.

My recursive-mode workflow handles all of that and more and gives you full traceability: https://recursive-mode.dev/introduction

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

#124

Post by dotneter »

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.

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

#125

Post by cube2222 »

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!

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

#126

Post by didgeoridoo »

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.

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

#128

Post by [deleted] »

beshrkayali wrote: post #51
brendanmc6 wrote: post #2

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…

I wrote something similar recently about how agent-generated code lacks the institutional memory that human-written code has. There's nobody to ask why a decision was made (1). “Specsmaxxing” is basically the right response to this. When you can't rely on authorial memory, you have to put the intent somewhere durable. Specs become the source of truth by default if we continue down the road of AI generated code. 1: ht…

[deleted]

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

#129

Post by beshrkayali »

try-working wrote: post #117
beshrkayali wrote: post #51

Earlier quoted context omitted.

I wrote something similar recently about how agent-generated code lacks the institutional memory that human-written code has. There's nobody to ask why a decision was made (1). “Specsmaxxing” is basically the right response to this. When you can't rely on authorial memory, you have to put the intent somewhere durable. Specs become the source of truth by default if we continue down the road of AI generated code. 1: ht…

the recursive-mode workflow has full traceability, including why decisions were made, what the original requirement was, what the previous state was, etc. https://recursive-mode.dev/introduction

[dead]

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

#130

Post by Twey »

brendanmc6 wrote: post #2

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…

The traditional name for this spec is ‘source code’ — a canonical source of truth for the behaviour of a system that is as human-readable as we know how to make it, that will be processed by automated tools into a less-readable derived artefact for a computer to execute.

Checking the compiled artefact into the codebase without checking in its source code has always been a risky move!

Post reply on HN