Specsmaxxing – AI 사이코시스 극복기, 그리고 내가 YAML로 스펙을 쓰는 이유

TL;DR Highlight

AI 코딩 에이전트와 일할 때 컨텍스트가 날아가거나 요구사항이 흐려지는 문제를 해결하기 위해, 인수 조건(Acceptance Criteria)을 YAML로 구조화해서 스펙을 관리하는 방법론과 오픈소스 툴킷(acai.sh)을 소개하는 글이다.

Who Should Read

AI 코딩 에이전트(Cursor, Claude 등)를 써서 실제 프로덕트를 개발 중인데, 세션이 바뀌거나 컨텍스트 윈도우가 꽉 차면 에이전트가 요구사항을 잊어버리거나 엉뚱한 구현을 해서 골치인 개발자. 스펙 관리와 AI 코드 품질 사이의 간극을 줄이고 싶은 솔로 개발자나 소규모 팀에 특히 유용하다.

Core Mechanics

AI 에이전트와 작업하다 보면 컨텍스트 윈도우 한계, 세션 종료, 머신 전환 등의 이유로 요구사항이 소실되고 에이전트가 '탈선'하는 현상이 반복된다. 저자는 이걸 'AI 사이코시스'라고 부른다.
README.md, AGENTS.md, architecture.md 같은 마크다운 문서를 쌓는 것도 좋지만, 저자는 여기서 한 단계 더 나아가 YAML로 구조화된 인수 조건(Acceptance Criteria)을 관리하는 방식을 실험했다.
핵심 인사이트는 '스펙은 어딘가에 반드시 존재한다'는 것이다. 문서화하지 않으면 개발자 머릿속이나 대화 속에 흩어져 있을 뿐이고, 어차피 팀과 비즈니스는 그 스펙을 기준으로 판단한다. 그러니 지금 당장 써두는 게 낫다는 논리다.
실험 중에 서브 에이전트가 자발적으로 요구사항 번호(AUTH-1, AUTH-2, AUTH-3 등)를 코드 주석에 달기 시작하는 걸 발견했다. 이 동작에서 힌트를 얻어 YAML 기반 스펙과 코드를 연결하는 방식을 체계화했다.
acai.sh라는 오픈소스 툴킷을 만들었으며, 워크플로우는 'Specify → Ship → Review → Iterate' 4단계로 구성된다. feature.yaml 파일에 인수 조건 목록을 작성하고, 에이전트가 이를 참조해 코드를 생성한다.
저자 스스로 'AI 사이코시스' 증상 중 하나로 꼽은 것이 '제품을 만들 AI 하네스를 만드는 데 AI를 쓰는 것'이다. 이 함정을 인식하고 복잡한 에이전트 군단 구조를 버리고 단순한 feature.yaml 중심 접근으로 돌아왔다.
비교 대상으로 GitHub Spec, Kit, OpenSpec, Kiro, Traycer.ai를 언급했고, 각각과의 차이를 정리했다. acai.sh의 차별점은 구조화된 인수 조건 ID 기반 추적과 코드 주석 연결 방식이다.
미래 비전으로 'Specsmaxxing → Testmaxxing → 반응형 소프트웨어 팩토리' 로드맵을 제시했다. 스펙 diff가 자동으로 코드 diff로 변환되는 방향을 목표로 한다.

Evidence

저자 본인이 댓글에서 핵심을 직접 요약했다: '스펙은 어딘가에 반드시 살아있다. 머릿속이나 대화 속에 있을 뿐이고, 팀과 비즈니스는 항상 스펙을 기준으로 판단한다. 그러니 지금 써두는 게 낫다. feature.yaml은 결국 인수 조건 목록일 뿐이다.'
'스펙을 다 쓰고 나면 직접 코딩하는 게 더 빠르다'는 반론이 있었다. 정확히 무엇을 만들지 정의하는 게 어려운 부분인데, 그걸 다 해놓으면 에이전트한테 코딩을 맡길 이유가 없다는 지적이다.
'이거 결국 Cucumber(BDD, Behavior-Driven Development) 아니냐'는 댓글이 있었다. YAML로 AST를 파싱해서 LLM에 먹이는 방식이 텍스트 토크나이징보다 낫긴 하지만 개념 자체는 수십 년 된 거라는 시각이다. 이에 V-모델, 요구사항 공학이 1960~70년대에 이미 정립됐고 애자일과 대립하는 게 아니라는 보충 설명도 달렸다.
'LLM의 확률적 특성을 극복하려고 샤먼처럼 온갖 의식을 치르는 게 피곤하지 않냐'는 공감 댓글이 있었다. 스펙을 아무리 잘 써도 LLM이 가장 창의적인 방식으로 코드를 망칠 수 있다는 현실적인 불만이다.
'왜 실행 가능한 스펙(코드 그 자체)을 쓰지 않느냐'는 의견도 있었다. 코드가 곧 스펙이어야 하며, YAML/마크다운은 오히려 역류라는 주장이다. 반면 'LLM을 쓰는 요점이 특정 언어로 스펙을 쓰지 않아도 된다는 것인데, YAML로 강제하면 흐름을 거스른다'는 비슷한 맥락의 댓글도 있었다.

How to Apply

AI 에이전트 세션이 끊기거나 컨텍스트가 리셋될 때마다 요구사항이 날아가는 문제를 겪고 있다면, 기능별로 feature.yaml 파일을 만들어 AUTH-1, AUTH-2 식으로 번호를 붙인 인수 조건 목록을 유지하면 에이전트가 세션 간에 일관된 요구사항을 참조할 수 있다.
에이전트가 생성한 코드에 어떤 요구사항을 구현했는지 추적하고 싶다면, 코드 주석에 AUTH-1 같은 요구사항 ID를 달도록 에이전트 프롬프트에 명시적으로 지시하면 코드와 스펙 간 연결고리를 유지할 수 있다. 글에서 소개된 서브 에이전트처럼 자동으로 하기도 한다.
복잡한 멀티 에이전트 파이프라인을 구축하려는 충동이 생길 때, 저자의 교훈처럼 'AI 하네스를 만드는 데 AI를 쓰고 있지 않은지' 먼저 자문하고, feature.yaml 같은 단순한 구조화 파일 하나로 먼저 시도해보는 게 낫다.
팀 내 AI 코드 리뷰나 핸드오프가 필요한 상황이라면 acai.sh의 오픈소스 툴킷(https://acai.sh)을 직접 설치해 Specify → Ship → Review → Iterate 워크플로우를 팀 프로세스에 붙여볼 수 있다.

Code Example

snippet

# feature.yaml 예시 (인수 조건 목록)
feature: authentication
requirements:
  - id: AUTH-1
    description: Accepts `Authorization: Bearer <token>` header
  - id: AUTH-2
    description: Tokens are user-scoped, providing access to any of the user's resources
  - id: AUTH-3
    description: Rejects with 401 Unauthorized
    depends_on: AUTH-1

# 에이전트가 생성한 코드에 요구사항 ID가 주석으로 연결된 예시
const authHeader = req.headers["authorization"]; // AUTH-1
const isAuthorized = verifyBearerToken(authHeader); // AUTH-2
if (!isValid) return res.status(401).json({ error: "Unauthorized" }); // AUTH-3

Terminology

Acceptance Criteria소프트웨어 기능이 '완료됐다'고 판단하는 기준 조건 목록. '로그인 버튼을 누르면 토큰이 발급된다'처럼 테스트 가능한 형태로 쓴다.

Context WindowLLM이 한 번에 기억하고 처리할 수 있는 텍스트의 최대 분량. 이걸 넘으면 앞부분 내용을 잊어버린다.

Vibe Coding명확한 스펙 없이 AI와 대화하면서 즉흥적으로 코드를 만들어가는 방식. 빠르지만 일관성이 깨지기 쉽다.

BDD (Behavior-Driven Development)사람이 읽을 수 있는 자연어로 소프트웨어 동작을 기술하고, 그걸 자동화 테스트와 연결하는 개발 방법론. Cucumber 같은 도구가 대표적이다.

V-model요구사항 정의부터 테스트까지 각 개발 단계를 대칭 구조로 연결하는 소프트웨어 개발 프로세스. 각 구현 단계마다 대응하는 검증 단계가 있다.

AST (Abstract Syntax Tree)코드나 마크업을 컴퓨터가 처리하기 쉬운 트리 구조로 파싱한 것. YAML을 AST로 파싱하면 LLM이 텍스트로 읽는 것보다 구조를 더 정확히 이해할 수 있다는 논리다.