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

Who Should Read

A full-stack developer who reviews huge agent-generated PRs file by file and worries about missed requirements

Core Mechanics

• Numbered requirements become traceable
  • A sub-agent numbered the requirements and referenced those numbers in code comments.
  • The author calls these tags ACIDs (Acceptance Criteria IDs) and uses them to find where a requirement is implemented and tested.
• Specs are numbered lists in feature.yaml
  • Each feature gets one spec with concrete, testable requirements as a numbered list.
  • Every requirement has a unique, stable ID such as my-feature.ENG.2.
• He scrapped the markdown and started over
  • He built specs, templates and role agents, and had an agent run unsupervised for 1.5 hours.
  • The output wasn't slop but still sloppy, so he threw out the branch and all markdown.
• Acai.sh is an open-source toolkit
  • It has a feature.yaml template, a CLI for CI and agents, and a dashboard web app with a JSON REST API.
  • The app is built with Elixir, Phoenix and Postgres and published on GitHub under Apache 2.0.
• Review by requirement, not by file
  • acai push uploads specs and code references to the dashboard.
  • Requirements can be marked Completed, Accepted or Rejected, with comments.
• Rules for what goes in a spec
  • Specs hold functional behavior and critical constraints, not UI polish or design.
  • When a spec changes, the code must be re-aligned so the numbering stays valid.
• When code outpaces reading, tests become the bottleneck
  • He argues that once code is generated faster than you can read it, QA and test automation pay off hugely.
  • The end goal is LLMs reacting on their own to red tests or alerts.

Community Reactions

• Objection: just write the spec as code
  • One commenter argued code is the spec, so structure your code well instead.
  • Another said defining the product is the hard part and writing code is easy, so why hand it to an LLM.
• Opinion: specs are compression
  • One commenter said 100 tokens of spec can become 1000 tokens of code, so specs are denser and easier to read than code.
  • They added that non-dev partners can share and edit them more easily.
• Nothing new, some said
  • One comment called it Cucumber-style BDD again.
  • Another noted that requirements engineering like the V-model was formalized in the 1960s and 70s.
• Experience with other spec tools
  • One commenter spent a week on bmad and speckit, found too much ceremony and markdown filling the context, and saw this as the answer.
  • An OpenSpec user said specs describing the current system underpin AS-IS gap analysis, so the author's critique is a semantic difference.
• Skepticism about YAML and evidence
  • Commenters said there's no evidence YAML beats markdown and no ablation against other formats.
  • One said that after writing all these specs, doing it yourself in the editor is faster.

How to Apply

• Add requirement numbering to your prompt today
  • List the requirements of a feature in progress as AUTH-1, AUTH-2 and so on.
  • Tell the agent to tag implementation and test code comments with those IDs.
  • In the PR, check each ID for an implementation and a test.
• Write one feature as feature.yaml
• Keep only behavior and constraints in specs
• Add acai push to CI and review per requirement

Try It

# Paste into Claude Code (simplified version of the article's method: numbering only, no Acai CLI)

Each requirement below has a unique ID like AUTH-1.
In the implementation and test code, add the ID as a comment like `// AUTH-1` at the relevant place.
After the work, summarize in a table each ID's implementation location, test location, and whether it is missing.

# Requirements
{{AUTH-1: requirement}}
{{AUTH-2: requirement}}
{{AUTH-3: requirement}}

Terminology

Related Papers

• GPT-5.6 Sol can beat Factorio on peaceful mode

  GPT-5.6 Sol in Codex at low thinking finished a peaceful Factorio run with a rocket launch

• AI isn't replacing SREs, it's deskilling them

  Letting AI handle 95% of incidents may dull the skills SREs need for the critical 5%.

• Backdoor in Claude Code for VS Code extension on the Cursor Marketplace

  A tampered Claude Code extension on Cursor Marketplace planted an SSH backdoor

• Building an AI-native engineering org

  Automating each shipping step raised merges per engineer about 5x with reverts under 0.5%

• We ran AI agent swarms in Minecraft and Mindustry

  We put 50 agents in Minecraft and they invented ration ledgers and bureaucracy.

• The Agent SDK

  Cursor released Agent SDK, letting you define agents in code and deploy them with one command.

• Here be monsters: What do you still need to know when agents do the work?

  Owning agent-written code depends on fundamentals, breadth, and diving deep just in time.

• AI promised less work. I've never worked more

  Running agents in parallel brought my GitHub activity back to full-time engineer levels, and I'm exhausted.

Related Resources

• https://acai.sh/blog/specsmaxxing
• https://github.com/acai-sh/cli
• https://app.acai.sh
• https://github.com/Fission-AI/OpenSpec
• https://en.wikipedia.org/wiki/V-model
• https://www.lat.md/
• https://blog.fooqux.com/blog/executable-specification/