내가 AI에게 쓰는 '설명서'가 결국 코드와 똑같아진다는 경고
AI에게 상세한 설명서를 쓰면 코드 없이 개발할 수 있다는 믿음이 깨지고 있습니다. 해커뉴스 151표를 받은 개발자의 분석 — 설명서가 정확할수록 코드와 같아지며, OpenAI Symphony 실험에서도 스펙 기반 코드 생성은 실패했습니다.
'AI에게 원하는 걸 상세하게 설명하면 코드 없이도 프로그램을 만들 수 있다' — 바이브코딩 시대에 많은 사람이 이렇게 믿고 있습니다. 하지만 한 개발자가 해커뉴스에서 151표와 57개의 댓글을 받으며 이 믿음에 정면으로 반박했습니다. 핵심 주장은 간결합니다. "충분히 상세한 설명서는 곧 코드다."
▲ CommitStrip 만화: "프로그램을 자동 생성할 만큼 정확한 설명서가 있다면, 업계에서 그걸 뭐라고 부르는지 아세요? 코드요."
왜 '설명서만 쓰면 된다'는 말이 틀렸는지
이 글을 쓴 가브리엘라 곤잘레스(Gabriella Gonzalez)는 프로그래밍 언어 Haskell 전문 개발자입니다. 그는 AI 코딩 지지자들이 가진 두 가지 착각을 지적합니다.
착각 1: "설명서(스펙)는 코드보다 간단하다"
→ 현실: AI가 제대로 이해할 만큼 설명서를 정확하게 쓰려면, 결국 코드 수준의 상세함이 필요합니다.
착각 2: "설명서를 쓰는 건 코드를 짜는 것보다 깊은 사고가 필요하다"
→ 현실: 빠르게 쓴 설명서는 대부분 두서없는 '지시 나열'에 불과합니다. AI는 읽는 사람의 마음을 읽지 못합니다.
아르헨티나 작가 보르헤스의 유명한 우화를 인용합니다. 지도 제작자들이 제국 영토를 완벽하게 담은 지도를 만들었는데, 그 지도의 크기가 제국 자체와 같아져 버렸다는 이야기입니다. 설명서도 마찬가지입니다 — 완벽하게 만들수록 코드와 크기가 같아집니다.
OpenAI Symphony로 직접 실험한 결과
가브리엘라는 말로만 주장하지 않았습니다. OpenAI가 만든 Symphony(AI가 프로젝트 관리 도구의 작업 목록을 보고 자동으로 코드를 짜주는 시스템, 깃허브 스타 1만 3,400개)의 설계 문서를 직접 테스트했습니다.
▲ OpenAI Symphony 데모 화면. 작업 관리 도구(Linear)에서 할 일을 만들면 AI가 자동으로 코드를 짜는 구조입니다.
실험 내용: Symphony의 공식 설계 문서(SPEC.md)를 Anthropic의 Claude Code에게 주고, Haskell 언어로 구현하라고 시켰습니다.
결과는 실망스러웠습니다.
발견 1: Symphony의 '설계 문서'라는 것이 사실상 마크다운으로 위장한 코드였습니다. 데이터베이스 구조, 알고리즘, 코드 조각이 곳곳에 박혀 있었습니다.
발견 2: 설계 문서 크기가 실제 코드의 6분의 1이었습니다. 간결해 보이지만, 그마저도 "모델이 코드를 잘 생성하도록 돌봐주는" 중복 섹션을 포함하고 있었습니다.
발견 3: Claude Code는 이 문서로 작동하는 코드를 만들지 못했습니다. 버그를 반복적으로 수정해야 했고, 수정 후에도 AI 에이전트가 아무 진행 없이 멈춰버렸습니다.
YAML의 교훈 — 완벽한 설명서도 소용없다
가브리엘라는 더 강력한 사례를 제시합니다. YAML(설정 파일에 널리 쓰이는 데이터 형식)은 수십 년간 다듬어진 극도로 상세한 공식 규격과 적합성 테스트 세트를 갖추고 있습니다. 그런데도 대다수의 YAML 구현체가 규격을 완벽하게 따르지 못합니다.
인간 개발자도 완벽한 설명서를 보고 정확하게 구현하지 못하는데, AI가 그걸 해낼 수 있다고 기대하는 것은 비현실적이라는 주장입니다.
해커뉴스 57명의 논쟁 — 합의는 없다
이 글은 해커뉴스에서 격렬한 논쟁을 불러일으켰습니다.
동의하는 쪽: "브룩스의 '은탄환은 없다'가 30년 전에 이미 말한 내용이다. 코딩의 본질적 복잡성은 도구가 바뀌어도 사라지지 않는다."
반박하는 쪽: "AI가 빈칸을 채울 수 있다. 모든 걸 명시하지 않아도 문맥에서 추론할 수 있으니, 몇 년 안에 이 논쟁은 사라질 것이다."
흥미로운 것은 양쪽 모두 일정 부분 맞다는 점입니다. 간단한 작업에서 AI는 대략적인 지시만으로도 잘 작동합니다. 하지만 복잡한 시스템일수록 설명서의 빈틈이 버그가 되고, 결국 코드 수준의 정확성이 필요해집니다.
바이브코딩을 하는 사람들이 알아야 할 것
이 논쟁이 '나한테 무슨 의미인가'를 정리하면 이렇습니다.
간단한 도구를 만들 때: AI에게 대략 설명하는 것만으로 충분합니다. 웹사이트 랜딩페이지, 간단한 자동화 스크립트 등은 바이브코딩이 잘 작동합니다.
복잡한 시스템을 만들 때: "AI에게 맡기면 된다"는 생각은 위험합니다. 설명서를 쓰는 데 드는 노력이 직접 코드를 짜는 것과 비슷해지며, AI가 생성한 코드의 품질도 보장되지 않습니다.
핵심 교훈: AI 코딩 도구는 "코딩이 필요 없는 세상"을 만든 게 아니라, "코딩의 형태가 바뀐 세상"을 만들었습니다. 프로그래밍 지식 없이 복잡한 소프트웨어를 만드는 것은 여전히 쉽지 않습니다.
가브리엘라의 말을 빌리면: "AI 코딩 에이전트는 독심술사가 아닙니다. 당신의 생각 자체가 정리되지 않았다면, 아무리 좋은 AI도 대신 정리해줄 수 없습니다."
AI 코딩에 대한 기대가 높아질수록, 이런 냉정한 현실 점검이 더 필요해 보입니다.
관련 콘텐츠 — Easy클코로 AI 시작하기 | 무료 학습 가이드 | AI 뉴스 더보기
출처