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

Original Article ↗ Hacker News Discussion ↗

Role of Specs in AI-Assisted Development

  • Many see explicit specs as increasingly essential when AI generates code, because AI code has no “author memory.”
  • Specs outside the codebase help future work, onboarding, documentation, and post‑mortems, and give traceability from requirements to implementation.
  • Several people independently use numbered acceptance criteria, feature manuals, and architecture decision records to keep intent durable and searchable.

YAML and Other Spec Formats

  • The post’s YAML feature.yaml approach resonates with some, who like machine‑readable, cross‑referencable requirements and tighter control over what goes into the LLM context window.
  • Others strongly dislike YAML (indentation pain, brittle for LLMs) and prefer Markdown, Markdown+Gherkin, org‑mode, or diagram notations (UML, Mermaid, event modeling).
  • Some argue the same structure could be encoded in Markdown with conventions; YAML adds parsing ease but also cognitive and tooling overhead.

Specs vs Code and Tests

  • One camp claims “the real spec is the source code”; another counters that this collapses “what the system must do” into “how we happened to implement it,” which is backwards for business requirements.
  • Executable specs (Gherkin/Cucumber, BDD, test suites, literate programming, “code as spec”) are proposed as a middle ground: human‑readable but machine‑verifiable.
  • Concern: very detailed specs tend to converge on being code anyway; the benefit is “compression” (100 tokens of spec → 1000 tokens of code).

Process, Waterfall, and Change

  • Multiple commenters stress that written specs are not inherently “waterfall”; the problem is making them hard to change.
  • Real projects iterate: specs evolve with implementation and testing, often revealing missed cases and contradictions.
  • Some describe a V‑model / requirements‑engineering mindset as still valuable, especially for large, multi‑company systems.

AI Workflows, Tools, and Verification

  • Commenters describe elaborate agentic workflows: recursive decomposition, spec → intermediate spec → code, spec-driven TDD loops, or tools that cross‑check all specs for contradictions.
  • Others link or mention alternatives (OpenSpec, recursive‑mode, agents.md, lat.md, “special”) and systems tying spec IDs directly into code and tests.
  • A recurring theme: AI can generate lots of code, but robust verification (tests, linters, formal acceptance criteria) is the real bottleneck and opportunity.

Skepticism, Costs, and Culture

  • Some see “specmaxxing” and prompt frameworks as vibes‑driven, over‑engineered content marketing without comparative evidence.
  • Concerns include token cost, maintenance overhead of ever‑growing spec corpora, and the risk that teams stop truly reviewing AI‑generated code.
  • The “maxxing” terminology and misuse of “AI psychosis” draw criticism; several express fatigue with tool‑obsession and AI hype, while others say they genuinely enjoy this experimentation and see large productivity gains.