Try openspec: https://github.com/Fission-AI/OpenSpec/blob/main/docs/gettin...
That was my initial thought when reading the headline but the author states they didn't know it existed before doing this project and critiques it.
Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
21–30 of 316 posts
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#22Yesterday 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/
Agents.md actually scales and outperforms alternatives so I would be skeptical about overcomplicating the proces https://vercel.com/blog/agents-md-outperforms-skills-in-our-...
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#23Author 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 actually read it all since it did not contain any hints of being AI generated (although I wouldn't be surprised to learn you did use AI to write it), so thank you for that. It's kind of crazy how I now have the default expectation that posts posted here are AI slop with little thought or care put in.
I am also stealing the idea of talking to LLMs as if it's an email. So funny, we need to be joymaxxing a bit more I think :)
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#24Author 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…
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. And they're useful for documenters, support, etc.
2. Specifications that stay up to date as code is written. No spec survives first contact with the enemy (implementation in the real world). "Huh, there are TWO statuses for Missing orders, but we wrote this assuming just one. How do we display them? Which are we setting or is it configurable?" etc. Implementer finds things the specifier got wrong about reality, things the specifier missed that need to be specified/decided, and testing finds what they both missed.
I have a colleague working on saving architecture decisions, and his description of it feels like a higher-abstraction version of my saving and maintaining requirements.
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#25the 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.
I think uml exists to help humans understand and communicate specifications, not because language alone is insufficient.
I mean, if you can't agree on what UML is, then what hope do you have to agree on what the spec says?
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#26And once you’ve written all these specs you realize it became so slow that it’s faster to do it yourself in editor
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#27I'm still confused as to why folks don't just write executable specs.
If you're confused, and have tried Opus for coding, I'm keen to hear what problems or workflows it's not good at. If you're genuinely confused, and haven't tried Opus for coding, then it's not surprising you're confused! It is also okay for you to just not like the idea of LLMs for coding (but say that!).
That's what the article is about - overcoming problems with AI cooding tools using specs in Yaml. If we've got that far, it might be better to write specs in a proper programming language instead and skip the AI layer altogether
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#28the 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.
Natural language is a fully general system and can define and describe everything. You could deterministically process any UML diagram into a prose equivalent. And in fact you couldn't do the other way around (any prose -> UML) because UML is less powerful than natural language and actually can't express everything that natural language can.
There are also diagram notation languages and LLMs are happy to both consume and produce e.g. Mermaid.
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#29Author 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…
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
Re: Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
#30Earlier 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…
I do (1) the same but (2) differently. In my workflow, (2) are AI generated specs using human written (1) as the input. It's an intermediate stage between (1) and the codebase, allowing for a gradual token expansion from 30k to 250k to the final code which is 2-3M. The benefit I've found with this approach is it gives the AI a way to iterate on the details of whole system in one context window, whereas fitting the whole codebase into one prompt is impossible. The code is then nothing more than a style transfer from (2).