AI에 휘둘리지 않으려면 스펙부터 써라 — 'Specsmaxxing'과 YAML 명세의 힘

도입

AI 코딩 도구를 본격적으로 쓰다 보면 한 번쯤 이런 경험이 있으실 거예요. 분명 좋은 결과가 나올 줄 알고 시켰는데, AI가 너무 자신만만하게 잘못된 코드를 뱉어내고, 그걸 따라가다가 한참을 헤매는 상황이요. acai.sh 블로그의 글쓴이는 이걸 "AI 사이코시스(AI psychosis)"라고 부르는데, 한국어로는 "AI에 홀린 상태" 정도로 옮길 수 있겠네요. AI의 자신감 있는 거짓말에 휘둘려서 판단력을 잃어버리는 거예요.

글쓴이는 이 문제를 극복하기 위한 자기만의 방법을 정리했고, 그 핵심에 "스펙(명세)을 YAML로 쓴다"는 원칙을 둡니다. 제목인 "Specsmaxxing"은 "Specs(스펙)"와 "maxxing(끝까지 밀어붙인다)"의 합성어로, 명세 작성을 가능한 한 진지하게 끝까지 해보자는 뜻이에요.

왜 스펙이 그렇게 중요한가

AI 에이전트한테 "사용자 인증 기능 만들어줘"라고 던지면, 그럴듯한 코드가 나오긴 하지만 우리가 정말 원하는 모양은 아닐 가능성이 높아요. 우리 머릿속에는 수많은 암묵적 전제가 깔려 있거든요. 이메일 인증인지, OAuth인지, 토큰은 어디에 저장하는지, 만료 시간은 얼마인지… AI는 이런 걸 다 추측해서 채웁니다. 그리고 추측이 어긋나는 만큼 우리가 원하는 결과와 멀어지죠.

스펙을 먼저 쓰면 이 추측을 사람이 직접 통제할 수 있어요. 더 중요한 건, 스펙을 쓰는 과정 자체가 우리 사고를 정리해준다는 점이에요. "이 기능이 정확히 뭘 해야 하지?"를 글로 풀어내다 보면, 빠뜨린 케이스나 모호한 부분이 보이기 시작하거든요. AI한테 시키기 전에 사람이 먼저 이해를 끝내자는 게 핵심 메시지예요.

왜 하필 YAML인가

저자는 마크다운이나 자유 형식 문장보다 YAML로 스펙을 쓰는 걸 선호한다고 해요. 이유가 몇 가지 있어요.

첫째, 구조가 강제됩니다. 자유 글로 쓰면 "이 내용은 어디에 적지?" 하는 고민이 매번 생기는데, YAML은 키-값 구조라 자리가 정해져 있어요. intent:, inputs:, outputs:, errors:, non_goals:, examples: 같은 키를 미리 정의해두면, 빈칸을 채우는 느낌으로 명세를 완성하게 돼요.

둘째, AI도 잘 읽습니다. YAML은 들여쓰기 기반이라 LLM이 구조를 파악하기 쉽고, 토큰도 JSON보다 적게 먹어요. 마크다운보다 마크업이 적어서 사람도 빠르게 훑을 수 있고, 모델도 명확한 구조 신호로 읽어줍니다.

셋째, diff가 깔끔합니다. 스펙은 한 번 쓰고 끝이 아니라 계속 수정되거든요. 그때 어디가 바뀌었는지 git diff로 명확하게 보이는 게 중요한데, 자유 텍스트는 한 줄을 고치면 줄바꿈이 들썩이는데 YAML은 한 키만 수정되면 그 줄만 바뀝니다. PR 리뷰가 훨씬 편해져요.

실제 워크플로우

글의 흐름은 대략 이래요. 새 기능을 만들 때 먼저 spec.yaml 같은 파일을 열고 의도, 입출력, 엣지 케이스, 받아들이지 않는 입력, 성공 기준 등을 키-값으로 적어 내려갑니다. 이 단계에서는 코드를 한 줄도 안 써요. 다 적은 다음에야 AI한테 "이 스펙대로 구현해줘"라고 시킵니다.

흥미로운 건, AI가 코드를 만들고 나서 다시 그 결과를 스펙과 대조시키는 단계도 둔다는 거예요. 즉 스펙이 "테스트 기준"으로도 쓰이는 셈이죠. 이러면 AI가 환각으로 엉뚱한 동작을 만들어도, 스펙이라는 닻이 있어서 금방 잡아낼 수 있어요. 스펙이 사양서이자 평가 기준이자 회귀 방지선 역할을 동시에 하는 거예요.

업계 맥락

이런 방향성은 사실 새로운 게 아니에요. Anthropic이 강조하는 "프롬프트 안에 명세를 충분히 넣어라", OpenAI의 "Structured Outputs", Cursor·Aider 같은 도구의 .cursorrules나 컨텍스트 파일도 결국 같은 이야기를 하고 있어요. 모델이 더 똑똑해질수록 오히려 사람의 의도를 또렷이 적어주는 게 더 중요해진다는 거죠. "Specsmaxxing"은 OpenAPI처럼 무거운 형식을 강요하는 대신, 한 함수·한 기능 단위에서 가볍게 적용한다는 점이 차별점이에요.

한국 개발자에게 주는 시사점

국내에서 Cursor, Windsurf, Claude Code 같은 AI 코딩 도구를 본격적으로 쓰는 분들이 많아졌는데요. "AI가 만들어준 코드가 자꾸 이상하다"는 호소를 자주 듣습니다. 이때 도구를 바꾸기 전에 자신의 입력을 한번 점검해보는 게 더 효과적일 때가 많아요. 당장 적용해볼 수 있는 건, 새 PR을 시작하기 전에 5~10분 정도 짧은 YAML 스펙을 먼저 쓰는 거예요. 그 시간이 한 시간짜리 헛소리 핑퐁을 막아주거든요.