May 3, 2026
Spec and the City
Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
Developer’s AI spec obsession sparks a comment war over docs, costs, and common sense
TLDR: A developer says AI coding works better when you write very clear instructions first, and he’s now open-sourcing a YAML-based way to do it. The comments split fast: some called it smart discipline, others said it’s costly, overly formal, and just reinventing old paperwork with AI lipstick.
A developer wrote a dramatic confession about going full “spec maxi”—basically, becoming obsessed with writing ever more detailed instructions so AI coding tools stop forgetting important details. The big twist? After trying mountains of markdown files and what he jokingly calls “AI psychosis,” he landed on a system using structured YAML specs and little requirement tags he nicknamed ACIDs to keep code, tests, and goals lined up. It’s nerdy, yes, but the comments turned it into a full-on crowd brawl over how much writing is too much writing.
The author jumped in to calm the chaos, insisting the real point is simple: the plan for your software always exists somewhere, whether it’s written down or rattling around in someone’s brain. But the replies were not exactly holding hands and singing. One camp basically yelled, “This is too expensive and too wordy!” with one commenter warning that all this polished English burns too many AI credits and that brevity is the language of money. Another side rolled in with classic engineer smugness: why not just write “executable specs,” meaning instructions that are so precise they double as working tests? Meanwhile, tool fans arrived like sports supporters plugging OpenSpec and arguing this is less a revolution and more a naming fight.
The funniest part is the vibe: half the thread treats the post like a breakthrough, the other half like a very elegant spiral. The meme of the day is clear—AI was supposed to remove paperwork, and somehow everyone ended up inventing even more paperwork, but prettier.
Key Points
- •The article says AI coding tools can increase development speed and improve robustness, testing, automation, and observability, but still lose requirements because of context-window limits.
- •The author argues that writing requirements into documents is more reliable than relying on prompts alone, and lists markdown-based docs as practical starting points.
- •The article describes an experiment with extensive specification-driven AI workflows, including detailed PRDs, TRDs, templates, roles, and long-running AI agents.
- •The author says the AI-generated output was functional but still felt sloppy, leading them to restart and simplify the workflow.
- •A sub-agent’s automatic numbering of requirements led the author to adopt acceptance-criteria identifiers to connect specs with implementation, tests, and progress tracking.