AI 코딩 에이전트를 위한 스펙 문서, 어떻게 쓸 것인가?

우리는 뭘 만들어야 하는지, 어떻게 만들어야 하는지 잘 알고 있다고 착각합니다. 그래서 아무 설명도 적히지 않은 티켓을 만들고, 바로 코딩을 시작합니다. 구현을 시작하고 나서야 “이 경우엔 어떻게 하지?”라는 질문이 쏟아집니다. 한참을 만들고 나서 설계를 뜯어고치기 시작합니다. 빠르다고 생각했던 길이 멀리 돌아가는 길이 됩니다.

머릿속에 있는 것은 생각보다 모호합니다.

스펙 문서는 AI와 함께 작성합니다. 더 나은 프롬프트를 AI를 통해 만드는 것처럼, 스펙 문서도 AI와 함께 만듭니다. 무엇을 만들어야 하는지만 전달하지 않습니다. 왜 이 기능이 필요한지, 배경과 목적을 함께 전달합니다. 의도가 충분히 전달되면 AI가 더 나은 스펙을 써줍니다.

해피 패스부터 시작합니다. 사용자가 이 기능으로 뭘 할 수 있는지, 가장 기본적인 흐름이 어떻게 되는지. 해피 패스를 그리면 사용자 가치가 분명해집니다. 가치가 드러나지 않는 기능은 만들 이유가 없습니다.

해피 패스를 보면 자연스럽게 질문이 생깁니다. “입력값이 비어있으면?” “권한이 없으면?” “동시에 두 명이 요청하면?” 이 질문들이 엣지 케이스입니다. 의도가 잘 전달됐다면 AI가 기본적인 엣지 케이스를 찾아줬을 겁니다. 좀 더 예민한 부분을 검토하면서 채워나갑니다. 코드를 작성하기 전에 발견하는 것과 코드를 작성한 후에 발견하는 것은 비용이 다릅니다.

완료 기준도 정합니다. 이런 상황에서, 이렇게 하면, 이런 결과가 나와야 한다. “잘 동작해야 한다” 같은 모호한 기준이 아니라, 구체적인 예시로 성공을 정의합니다. 제약사항도 씁니다. 성능, 보안, 호환성, 기술적 한계. 미리 쓰면 설계 결정의 근거가 됩니다.

해피 패스부터 제약사항까지, 80%는 AI가 채워줍니다. 우리는 나머지 20%에 집중합니다.

우리가 할 일은 검토입니다. 해피 패스가 우리의 의도와 일치하는지, 엣지 케이스에 빠진 게 없는지 확인합니다. 디테일을 하나하나 잡는 것보다 AI가 의도를 잘못 파악한 부분을 찾아 올바른 이해로 교정하는 게 훨씬 효과적입니다.

개발을 진행하다 보면 우리가 오해하고 있던 것을 발견합니다. 이 오해를 AI와 함께 해소하고, 스펙을 고칩니다. 우리가 이해하고 있던 것과 실제 코드 사이의 차이가 기술 부채의 원인입니다. 이 차이를 초기에 발견하고 빠르게 대응하면 기술 부채가 쌓이기 전에 줄여나갈 수 있습니다.

스펙 문서는 최종 산출물이 아닙니다. 발견하고 갱신하는 문서입니다.

“스펙을 먼저 정한다고? 그거 워터폴 아닌가?”

아닙니다. 워터폴은 거대한 문서를 먼저 완성하고, 그대로 구현하고, 끝날 때까지 돌아보지 않는 방식입니다. 스펙 문서는 그 반대입니다. 빠르게 쓰고, 빠르게 구현하고, 빠르게 피드백하고, 빠르게 고칩니다. 이 사이클이 빠를수록 좋습니다.

스펙 문서를 쓰는 가장 큰 이유는 문서 그 자체가 아닙니다. 쓰는 과정에서 생각이 정리됩니다. 모호했던 것이 구체적이 되고, 빠져있던 것이 보이고, 합의가 필요한 부분이 드러납니다.

스펙 문서는 관료적 절차가 아닙니다. 생각을 명확하게 만드는 도구입니다.

더 읽을거리:

우리 팀에 맞는 AI 도입과 개발 전략이 필요하신가요?