Specsmaxxing – AI 정신병을 넘어서, 스펙을 YAML로 쓰는 이유
Specsmaxxing – On overcoming AI psychosis, and why I write specs in YAML
TL;DR Highlight
요구사항에 ID를 붙여 코드와 연결했더니 AI 코드 리뷰를 요구사항 단위로 하게 됐다
Who Should Read
Claude Code 같은 에이전트가 만든 큰 PR을 파일 단위로 리뷰하다 요구사항 누락이 걱정되는 풀스택 개발자
Core Mechanics
- 요구사항에 번호를 붙이면 추적된다
- 서브 에이전트가 요구사항에 번호를 매기고 코드 주석에서 그 번호를 참조했다.
- 저자는 이 태그를 ACID(Acceptance Criteria ID)라고 부르고, 요구사항이 어디서 구현·테스트되는지 찾는 데 쓴다.
- 스펙은 feature.yaml에 번호 목록으로 쓴다
- 기능 하나당 스펙 하나를 두고, 요구사항을 구체적이고 테스트 가능하게 번호 목록으로 쓴다.
- 각 요구사항은 my-feature.ENG.2처럼 고유하고 안정적인 ID로 참조된다.
- 마크다운을 버리고 처음부터 다시 했다
- 저자는 스펙·템플릿·역할 에이전트를 잔뜩 만들어 에이전트가 1.5시간 무감독으로 돌게 했다.
- 결과물은 슬롭은 아니었지만 여전히 조금 어설퍼서 브랜치와 마크다운을 모두 버렸다.
- Acai.sh는 오픈소스 도구 모음이다
- feature.yaml 템플릿, CI와 에이전트용 CLI, 대시보드와 JSON REST API 웹앱으로 구성된다.
- 웹앱은 Elixir, Phoenix, Postgres로 만들었고 Apache 2.0 라이선스로 GitHub에 공개돼 있다.
- 리뷰는 파일이 아니라 요구사항 단위로 한다
- acai push로 스펙과 코드 참조를 대시보드에 올린다.
- 요구사항 상태를 Completed, Accepted, Rejected로 표시하고 댓글을 남길 수 있다.
- 스펙에 넣을 것과 뺄 것을 정해 두었다
- 스펙에는 기능 동작과 핵심 제약만 쓰고, 세세한 UI나 디자인은 넣지 않는다.
- 스펙을 바꾸면 번호가 어긋나지 않게 코드도 다시 맞춰야 한다.
- 코드가 빨리 나오면 병목은 테스트로 옮겨간다
- 저자는 코드 생성이 읽는 속도를 앞지르면 QA와 테스트 자동화 투자가 큰 효과를 낸다고 본다.
- 최종 목표는 빨간 테스트나 알림에 LLM이 스스로 반응하는 구조다.
Community Reactions
- 스펙을 코드로 쓰면 되지 않느냐는 반론
- 댓글에서 코드가 곧 스펙이니 코드를 구조화해 쓰면 된다는 의견이 있었다.
- 다른 댓글은 요구사항을 정하는 게 어렵고 코드 작성은 쉬운 일인데 왜 LLM에 맡기느냐고 물었다.
- 스펙은 압축이라 코드보다 낫다는 의견
- 댓글에서 100토큰 스펙이 1000토큰 코드가 되듯 스펙이 코드보다 촘촘하고 읽기 쉽다는 의견이 나왔다.
- 이 댓글은 비개발자와 공유하기도 쉽다고 했다.
- 새로울 것 없다는 지적
- 댓글에서 Cucumber 같은 BDD의 반복이라는 의견이 있었다.
- 다른 댓글은 V-모델 같은 요구공학이 1960~70년대에 이미 정립됐다고 지적했다.
- 기존 스펙 도구 경험담
- 한 댓글은 bmad와 speckit을 일주일 써 봤더니 의식과 마크다운이 과해 컨텍스트를 빨리 채웠고, 이 글의 접근이 그 대안 같다고 했다.
- OpenSpec 사용자는 현재 시스템을 설명하는 스펙이 AS-IS 갭 분석의 기초라서 저자의 비판은 의미 차이라고 했다.
- YAML과 근거에 대한 회의
- 댓글에서 YAML이 마크다운보다 낫다는 근거가 없고 다른 방식과의 비교 실험이 없다는 의견이 있었다.
- 스펙을 다 쓰고 나면 직접 코딩하는 게 더 빠르다는 경험담도 있었다.
How to Apply
- 요구사항 번호 규칙을 지금 프롬프트에 넣기
- 진행 중인 기능의 요구사항을 AUTH-1, AUTH-2처럼 번호 목록으로 적어라.
- 에이전트에게 구현·테스트 코드 주석에 해당 번호를 달게 하라.
- PR에서 번호별로 구현과 테스트 유무를 확인하라.
- 기능 하나를 feature.yaml로 써 보기
- 스펙은 동작과 제약만 남기기
- CI에 acai push 붙여 요구사항 단위로 리뷰하기
Try It
# Claude Code에 붙여넣기 (원문 방법의 간이 버전: Acai CLI 없이 번호 규칙만 적용)
아래 요구사항에 AUTH-1처럼 고유 ID가 있다.
구현 코드와 테스트 코드의 해당 위치에 `// AUTH-1` 형태로 ID를 주석으로 달아라.
작업 후 각 ID별로 구현 위치, 테스트 위치, 누락 여부를 표로 정리해라.
# Requirements
{{AUTH-1: 요구사항}}
{{AUTH-2: 요구사항}}
{{AUTH-3: 요구사항}}Terminology
관련 논문
GPT-5.6 Sol, 평화 모드 Factorio를 13.5시간에 클리어
GPT-5.6 Sol이 Codex 낮은 사고 수준으로 평화 모드 Factorio 로켓 발사까지 갔다
AI가 SRE를 대체하는 게 아니라 실력을 깎아먹는다
인시던트 95%를 AI에 맡기자 나머지 5%를 다룰 SRE의 실력이 녹슬 수 있다
Cursor Marketplace의 Claude Code 확장에 심어진 SSH 백도어
Cursor Marketplace의 변조된 Claude Code 확장이 SSH 백도어를 심었다
AI-native 엔지니어링 조직 만들기: FurtherAI 9개월 회고
배포 전 과정을 단계별로 자동화하자 엔지니어 1인당 일일 머지가 약 5배 늘었다
Minecraft·Mindustry에서 AI 에이전트 군집 50마리를 돌려 봤다
에이전트 50개를 Minecraft에 풀었더니 배급 장부와 관료제가 생겼다
Cursor Agent SDK 출시: 에이전트를 코드로 정의하고 한 줄로 배포
Cursor가 에이전트를 코드로 정의·배포하는 Agent SDK를 정식 공개했다
에이전트가 코드를 짜는 시대, 엔지니어가 여전히 알아야 할 것: 기초·폭넓은 지식·필요할 때 깊이 파기
에이전트가 짠 코드의 오너십은 기초, 폭넓은 지식, 즉시 깊이 파는 능력에 달렸다
AI가 일을 줄여준다더니, 이렇게 많이 일한 적이 없다
에이전트를 병렬로 돌렸더니 GitHub 활동이 엔지니어 시절 수준으로 돌아왔다