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

Original Article ↗ Hacker News Discussion ↗

As large language models generate more of the code in modern projects, many engineers are experimenting with “spec-driven development”: writing detailed, machine-readable requirements (often in YAML or Gherkin) and treating them as the primary source of truth. Proponents argue that external specs preserve intent, improve traceability, and make it easier for AI agents to evolve a codebase safely, while critics counter that this adds ceremony, risks duplicating what well-structured code and tests already express, and can devolve into over-optimized “prompt engineering.” Underneath the tooling debate is a broader question of process: whether AI accelerates a return to more formal requirements engineering and waterfall-like planning, or simply changes how agile teams capture and maintain evolving system behavior.

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.