Specsmaxxing: Combatendo a Psicose de IA com Especificações YAML e ACAI

O post mais recente do blog da Acai.sh, "Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML," aborda o problema de agentes de IA saindo dos trilhos quando as janelas de contexto ficam cheias ou as sessões morrem. O autor compartilha um fluxo de trabalho prático: escrever especificações estruturadas em YAML em vez de apenas markdown, e usar requisitos numerados (ex.: AUTH-1, AUTH-2) que os agentes podem referenciar diretamente no código. Este método, chamado Critérios de Aceitação para IA (ACAI), surgiu quando um subagente numerou automaticamente os requisitos e os referenciou na implementação, melhorando a rastreabilidade e reduzindo regressões.

O post descreve um processo de quatro etapas: Especificar (escrever requisitos em YAML), Entregar (deixar os agentes implementarem), Revisar (verificar o código em relação às especificações) e Iterar. O autor admite que antes exagerava nas especificações em markdown (PRDs, TRDs, documentos de arquitetura) e sofria de "psicose de IA" — gastando mais tempo construindo arneses de IA do que produtos. A abordagem baseada em YAML é mais leve e mais acionável por máquinas.

Insight chave: um simples README.md e AGENTS.md já melhoram significativamente a saída dos agentes. O post argumenta que o "Peak Slop" passou e que especificações estruturadas são a próxima evolução. Um trecho de código mostra o padrão:

# 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" });

O post também revisa alternativas: GitHub SpecKit, OpenSpec, Kiro, Traycer.ai — e lista razões pelas quais você pode não gostar do acai.sh (ex.: sobrecarga, formato opinativo). É uma visão pragmática para desenvolvedores que querem que seus agentes de IA entreguem código confiável sem loops constantes de ajuste e correção.

Para quem é: Desenvolvedores que usam agentes de codificação de IA (Claude, Copilot, etc.) que encontram limites de contexto e querem uma camada de especificação leve para manter os agentes no caminho certo.