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

271–280 of 316 posts

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

#271

Post by lelanthran »

surgical_fire wrote: post #262
lelanthran wrote: post #243

Earlier quoted context omitted.

I've never seen a spec survive first contact with implementation. The spec is refined while writing the code. Hell, you probably couldn't even build a simple bike shed from plans without having to revise them while building, so I am skeptical that without writing you are going to pinpoint the problems in the spec. Reading only gets you a short way towards learning.

> I've never seen a spec survive first contact with implementation. The spec is refined while writing the code. Neither have I. This does not make the spec useless. I don't spec hoping that it will be the source of truth, I spec because planning more often than not allows me to spot inconsistencies and ambiguity ahead of time, not halfway through implementation. > Hell, you probably couldn't even build a simple bike…

> It's not supposed to be a bible that implementation can't deviate from. It's a plan, not law. It's okay for the plan to be adjusted in contact with reality.

My point is that without writing, you can't surface the type of problems you usually surface. The AI isn't going to surface those problems for you.

It's rare when reviewing that you think "Oh shit, this approach is totally wrong, we need to throw it away", while it's common when writing code to have that reaction.

If you aren't writing, you aren't having that reaction, and you aren't going to get it from reviewing code that has thousands of green "passed" lines in the testsuite.

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

#272

Post by Ancapistani »

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 think my use case is a little different than yours - I’m wanting to use it as a framework for me and an agent to manage specs, then split implementation into a separate agent fleet and use the spec as the interface layer - but the tool itself looks great and should work well!

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

#273

Post by hintymad »

Maybe it's just me, but isn't it exhausting that we have to do all kinds of work like a Shaman to combat the probabilistic nature of LLM, while knowing from the bottom of our heart that LLM can still screw up the code in the most creative way?

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

#274

Post by chickensong »

bizzletk wrote: post #120
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…

I've been attaching to my commit messages a Git Trailer [1] of the Session UUID from the Claude Code conversation that created that commit. It allows Claude to look back into the session where a change was made and see the decisions made, tradeoffs discussed and other history not captured by code, tests. [1] https://git-scm.com/docs/git-interpret-trailers

A few questions:

- Does Claude leverage the trailers automatically, or is usage initiated by you?

- How often are you using the trailer lookups?

- Any idea how this relates to token usage? If you're frequently busting cache on old sessions, it might be cheaper to read a local doc.

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

#275

Post by akomtu »

hintymad wrote: post #273

Maybe it's just me, but isn't it exhausting that we have to do all kinds of work like a Shaman to combat the probabilistic nature of LLM, while knowing from the bottom of our heart that LLM can still screw up the code in the most creative way?

AI makes us believe that instead of working towards a goal, one can "win" that goal with a lucky prompt. AI replaces thinking with gambling, in other words, and it's very tempting to many.

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

#276

Post by mpyne »

ebiester wrote: post #258
rzzzt wrote: post #250

Earlier quoted context omitted.

The DoD's 2167 standard from the late '80s mentions the following documentation that should be produced as part of the development process (section 6.2 and Appendix D): - System/Segment Specification - Software Development Plan - Software Configuration Management Plan - Software Quality Evaluation Plan - Software Requirements Specification - Interface Requirements Specification - Software Standards and Procedures Man…

This is a particular artifact of the government system process. These are contracted pieces of work that Company A would deliver, Company B would administer, and Company C would be contracted out for additional work. Further, all specifications were created ahead of time because changes would cost extra. (Anyone who has done government contracting can talk to the shenanigans involved with it - I have not lived in thi…

> This is a particular artifact of the government system process.

Yes, a government process meant to implement the waterfall approach.

If you look at Dr. Royce's paper which originated the concept, he was very explicit that it required upwards of thousands of pages of documentation to be written up front, if you were doing it "right".

By the time the required documentation had all been written, there should be essentially nothing left to do but to actually type out the punch cards as specified and turn then into a system of compiled programs.

Now, this appealed to government because it put documentation in place that was felt to be more viable for contracting processes, but ever since Dr. Brooks chaired a 1987 Defense Science Board study on the issues already facing the DoD trying to implement waterfall methods, they've been trying to restructure their software acquisition methods to pursue better outcomes rather than more concretely defined outputs.

Of course it's still a tremendous challenge for them even now, and it remains common to see defense acquisition projects that will say "Agile" to the right people even as they prescribe a full waterfall-style 'system engineering V' approach behind the scenes.

The ad-hoc responses that the commercial space often involves is usually more appropriate, believe it or not. They get process added when process is helpful, but not before it is helpful.

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

#278

Post by ffsm8 »

smokel wrote: post #169
ffsm8 wrote: post #134

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 developmen…

No, code is not the same as a specification. There are a lot of accidental implementation details that the customer may not require. By making the code the specification, you end up with those details becoming requirements, and you can then no longer change that implementation. Having functional behavior and implementation details separate can be really useful, even though it is typically a pain to keep them in sync.

Your comment reads like you haven't understood my point.

I'm not saying that you can just take any code out there and call it your spec.

I even pointed out in my last paragraph that code not written as a spec is garbage for LLM driven development - precisely because you end up with unintended implementation details becoming your spec.

There are a lot of ways to address this, but ultimately it is down to how you structure your code, where you place your comments, and what you write into your agents.md in the modules and what kind of QA agents you configure to go through your code before reviewing the code changes/spec adjustments yourself

A more heavy handed approach could also be domain driven design, where your domain/core package becomes the spec, and the unspecified parts get extracted to less specified modules with less explicit structuring.

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

#279

Post by tommica »

One thing that popped to my mind from this article is code comments; crazy idea, what if any piece of code had to justify its existence - comment explaining why it is there and in support of what feature.

I want to try this features.yaml approach - there is something solid there, and the acai.sh tooling looks nifty.

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

#280

Post by arikrahman »

cassianoleal wrote: post #104
arikrahman wrote: post #19

Earlier quoted context omitted.

Literate programming would provide specs and code instead of working backwards from hard coded functions to figure out specs.

> working backwards from hard coded functions to figure out specs. People do that? Actual professionals?

Yes all the time actually, especially when making system migrations. Uncle Bob writes about this in Clean Code. It is actually extremely common since it's the most apparent course of action to look at hard-coded values in maintenance and backport it as specs to new system.
Post reply on HN