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

251–260 of 316 posts

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

#251

Post by ebiester »

jacquesm wrote: post #218
ebiester wrote: post #216

Earlier quoted context omitted.

There is a lot of room to reevaluate the lessons of software development pre-web in the context of the current environment. Like, if waterfall of a project can be done in 2 weeks, is it agile now?

That doesn't do justice to either waterfall or agile.

Oh certainly - I'm conflating the adjective of agile with the manifesto of agile. I've been on projects with multi-hundred page design docs and multi-week UATs. And nobody wants to go back to prince2 for example.

The point I was trying to make is we should be diving back into the older methodologies and accumulated wisdom and re-evaluate some of the older dead ends with new context.

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

#252

Post by physicles »

brendanmc6 wrote: post #163
dotneter wrote: post #124

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.

Here is how I got from Markdown to YAML in a few easy steps: 1. Start with unmaintainable prompt. Add auth to the admin route. It must only be accessible to team members. It must not be accessible to team members with the `quarantine` role. Unauthorized users should be redirected to the /login page, with query param `?error=unauthorized`. Requires fresh session, no older than 10 minutes. 2. Put it in a structured .md…

As someone who’s an experienced coder but sorta new to LLMs, I’ve learned that my intuition about what is and isn’t machine-readable for an LLM isn’t well-tuned. Better to do the benchmarking so you can be sure you’re not fooling yourself about whether use of YAML is warranted.

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

#253

Post by ffsm8 »

brendanmc6 wrote: post #185
kibwen wrote: post #162

Earlier quoted context omitted.

> Does the business mandate we use a cache for this hot path? No, but the business set performance targets, and the cache was a sensible way to satisfy them. See the difference? This seems confused. Specs are free to include as much or as little detail as they deem necessary. If a spec only wants to suggest vague performance goals and handwave the details, that's permitted. But if specs want to specify the exact mean…

I think we are actually saying the same thing! We could think of situations where the cache would be verboten (sensitive info), or where it would be mandatory, like in your example, or optional like in my example. My aim was to voice disagreement with the "code is spec" crowd, whom I think are using a different (and in my opinion tautological / useless / counterproductive) definition of spec. Probably because they ar…

You're just conflating NFRs with spec.

Structuring your codebase like it's your spec doesn't mean you're omitting the NFRs - they need to become part of your codebase too where applicable.

eg with your first example of response times - in javaland you can use annotations on the REST resources and RPC endpoints

or your second example with specific data that may not be cached via a combination of AGENTS.md in the directory of the module providing access to it, potentially doctexts on the data constructs in question and QA agents which run pre review and raise (and resolve) the inevitable violations. Which I may add will _also happen, and so much more frequently_ when you're doing "spec driven development" via markdown files.

The difference is just down to code being testable, and markdown/yml being purely "trust me, it's like this fr fs man"

However you want to structure your spec, just structure your code like that - it works way better, because llms can handle source code so much better then markdown files.

It's not going to pass the "enterprise architect" review job application of the last decade, but your project will work, much much better and with less input required by the developer... And your development process is less let's roll the Dice and more this isn't the spec yet

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

#254

Post by joshribakoff »

energy123 wrote: post #242
chrisldgk wrote: post #187

At this point, why not just write the code yourself? Defining exactly what the product is supposed to do is the hard part, writing code is the easy part. Write your specs as code and you have your product - why let your LLM do the fun part?

I do this because I'm wagering that LLMs will keep getting better. I'm wagering that specs will maintain value while code will degrade in value (become commoditized). Code lacks the surrounding theory that situates the code in the world [1]. My specs contain the theory that the code lacks, which makes specs more valuable in the future. Specs are proprietary data. Data holds value in a post-AGI world, not code. I am d…

> I’m wagering

So isn’t that gambling, not engineering?

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

#255

Post by raincole »

raincole wrote: post #183
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…

Before AI era, specs meant documentations. The specs of jpeg, png, h.264, docx, usbc or whatever format you can think of, are not just a bunch of C++ source files. Compilable source files served as example implementations, complementary to the specs themselves. The idea that code is spec is just agile brainrot, like the idea that clean code means you never need to write documents or comments.

Edit: it's very interesting that all the other engineering principles know the difference between spec and implementation, except in software engineering the idea that all you need is code got reinvented every few years. Every generation thinks they're the special one, I guess.

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

#256

Post by Stehfyn »

joshribakoff wrote: post #254
energy123 wrote: post #242

Earlier quoted context omitted.

I do this because I'm wagering that LLMs will keep getting better. I'm wagering that specs will maintain value while code will degrade in value (become commoditized). Code lacks the surrounding theory that situates the code in the world [1]. My specs contain the theory that the code lacks, which makes specs more valuable in the future. Specs are proprietary data. Data holds value in a post-AGI world, not code. I am d…

> I’m wagering So isn’t that gambling, not engineering?

It's a reductive inverse corollary, but highly skilled Blackjack players are known to hesitate hitting on 18

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

#257

Post by alemanek »

hansmayer wrote: post #74
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…

> will always care what the spec says, and that’s never going to change Did I miss something or is everyone back in 1970s, working in waterfall processes now?

Specs weren’t the problem with waterfall. The difficulty in changing them to match reality was.

The waterfall process I experienced went like this:

- Product folks created requirements

- architects produced detailed specs

- project managers created tickets based on specs

- lengthy estimation ensued.

- Then finally developers proceeded with implementation.

- QA tested it.

Each step above involved lengthy review with like 5-10people. If the devs found an issue with the spec or god forbid the requirement it triggered a massive cascade of work for everyone above. Things needed to be reviewed again, customers may need to get contacted, …etc.

I think we can learn from that and optimize for change. Specs as living documents close to the code should be less cumbersome. But, just like anything else large corporations will probably fumble this like they did with “agile” (SAFe I am looking at you).

This is a long way to say specs aren’t bad. Specs that are difficult to change are though.

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

#258

Post by ebiester »

rzzzt wrote: post #250
mpyne wrote: post #234

Earlier quoted context omitted.

> Like, if waterfall of a project can be done in 2 weeks, is it agile now? Sure. The thing is, the waterfall guys would tell you it's impossible to do it in 2 weeks because you need to have written down everything first . "Thousands of pages" was the terms they used. Agile guys would point you to the Agile manifesto which would lead you to "working code over documentation" and "people over process". A 2 week period t…

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 this world for a long time.)

That said, we still do ad-hoc versions of many of these. For example, a system/segment specification today is an OpenAPI document between microservices. Most larger SaaS companies have the equivalent of a Software Configuration Management plan - Who can change terraform or a GHA, what are the standards that they conform to (linter, peer review standards).

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

#259

Post by maxnevermind »

enraged_camel wrote: post #245
chrisldgk wrote: post #187

At this point, why not just write the code yourself? Defining exactly what the product is supposed to do is the hard part, writing code is the easy part. Write your specs as code and you have your product - why let your LLM do the fun part?

>> Defining exactly what the product is supposed to do is the hard part, writing code is the easy part. There is a massive difference between a spec, which defines what the product should do, and code, which defines exactly how it should do it. Moving from the former to the latter is not "the easy part". Anyone who genuinely believes that either works on easy and straightforward problems, or is some sort of programmi…

> Defining exactly what the product is supposed to do is the hard part, writing code is the easy part.

> There is a massive difference between a spec, which defines what the product should do, and code, which defines exactly how it should do it.

He states: The difficult part is figuring out the details so LLM doesn't save much time. You state: If LLM is able to correctly assume the details that saves you a lot of time.

Case 1: Part of the spec describe some basic feature based on a popular framework and industry standards, everything is trivial. You are right, he is wrong.

Case 2: Part of the spec describe some niche feature and/or uses some not popular framework and/or require deviation from industry standards and/or cutting edge performance/latency requirements and/or uses a bunch of proprietary non-googlable data. You are wrong, he is right.

The more senior engineer are the less time they spend on case 1, those are easy, they don't spend much time on it, it is the 2nd which is much more time consuming.

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

#260

Post by alasano »

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…

Because I don't trust LLMs to fully implement what I want on the first try unless I babysit them. And it's the hand holding that burns people out.

I use detailed specs to implement but I don't maintain those specs as the source of truth afterwards, the code is indeed the source of truth.

I've built a library (and products on top) that takes in requirements (programmatic or various spec formats) and forces an externally orchestrated implement -> review -> fix loop that doesn't stop until all requirements are met.

So I'll write a detailed spec then I'll have GPT 5.5 implementing and a mix of opus 4.7 / GPT 5.5 / DeepSeek v4 pro reviewing at every phase until it produces the quality I want.

I can let it run overnight or just during the day while I'm doing stuff that doesn't burn me out and that I actually enjoy.

So tldr spec first for me but not as the source of truth afterwards.

I'll be open sourcing and launching soon https://engine.build

Post reply on HN