Specsmaxxing: Fighting AI Psychosis with YAML Specs and ACAI

Acai.sh's latest blog post, "Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML," tackles the problem of AI agents going off the rails when context windows fill up or sessions die. The author shares a practical workflow: write structured specs in YAML instead of only markdown, and use numbered requirements (e.g., AUTH-1, AUTH-2) that agents can reference directly in code. This method, called Acceptance Criteria for AI (ACAI), emerged when a sub-agent auto-numbered requirements and referenced them in implementation, improving traceability and reducing regressions.

The post describes a four-step process: Specify (write requirements in YAML), Ship (let agents implement), Review (check code against specs), and Iterate. The author admits to previously overdoing markdown specs (PRDs, TRDs, architecture docs) and suffering "AI psychosis" — spending more time building AI harnesses than products. The YAML-based approach is meant to be lighter and more machine-actionable.

Key insight: plain README.md and AGENTS.md already improve agent output significantly. The post argues that "Peak Slop" has passed and structured specs are the next evolution. A code snippet shows the pattern:

# Requirements
AUTH-1: Accepts `Authorization: Bearer <token>` header
AUTH-2: Tokens are user-scoped, providing access to any of the user's resources
AUTH-3: Rejects with 401 Unauthorized

// AUTH-1
const authHeader = req.headers["authorization"];
// AUTH-2
const isAuthorized = verifyBearerToken(authHeader);
// AUTH-3
if (!isValid) return res.status(401).json({ error: "Unauthorized" });

The post also reviews alternatives: GitHub SpecKit, OpenSpec, Kiro, Traycer.ai — and lists reasons you might not like acai.sh (e.g., overhead, opinionated format). It's a pragmatic take for developers who want their AI agents to ship reliable code without constant nudge-and-fix loops.

Who it's for: Developers using AI coding agents (Claude, Copilot, etc.) who hit context limits and want a lightweight spec layer to keep agents on track.