스펙맥싱: YAML 스펙과 ACAI로 AI 정신병과 싸우기

Acai.sh의 최신 블로그 게시물 "Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML"은 컨텍스트 창이 가득 차거나 세션이 종료될 때 AI 에이전트가 제대로 작동하지 않는 문제를 다룹니다. 저자는 마크다운만 사용하지 않고 YAML로 구조화된 명세를 작성하고, 에이전트가 코드에서 직접 참조할 수 있는 번호가 매겨진 요구사항(예: AUTH-1, AUTH-2)을 사용하는 실용적인 워크플로우를 공유합니다. 이 방법은 AI 수용 기준(ACAI)이라고 불리며, 하위 에이전트가 요구사항에 자동으로 번호를 매기고 구현에서 이를 참조하면서 추적 가능성이 향상되고 회귀가 줄어든 것에서 시작되었습니다.

게시물은 네 단계 프로세스를 설명합니다: 명세(YAML로 요구사항 작성), 출시(에이전트가 구현하도록 함), 검토(명세에 대해 코드 확인), 반복. 저자는 이전에 마크다운 명세(PRD, TRD, 아키텍처 문서)를 지나치게 많이 작성했고 "AI 정신병"을 겪었다고 인정합니다. 즉, 제품을 만드는 것보다 AI 하네스를 구축하는 데 더 많은 시간을 보냈습니다. YAML 기반 접근 방식은 더 가볍고 기계가 처리하기 쉽도록 설계되었습니다.

핵심 통찰: 일반 README.md와 AGENTS.md만으로도 에이전트의 출력이 크게 향상됩니다. 게시물은 "Peak Slop"은 지나갔고 구조화된 명세가 다음 진화 단계라고 주장합니다. 코드 스니펫은 패턴을 보여줍니다:

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

게시물은 또한 대안(GitHub SpecKit, OpenSpec, Kiro, Traycer.ai)을 검토하고 acai.sh가 마음에 들지 않을 이유(예: 오버헤드, 독선적인 형식)를 나열합니다. 이는 AI 에이전트가 지속적인 미세 조정 없이 안정적인 코드를 제공하길 원하는 개발자를 위한 실용적인 접근 방식입니다.

대상: 컨텍스트 제한에 부딪히고 에이전트를 올바른 방향으로 유지하기 위한 가벼운 명세 계층을 원하는 AI 코딩 에이전트(Claude, Copilot 등) 사용자.