지난 몇 년간 AI의 등장으로 개발 현장은 크게 변화했다. 바이브 코딩(Vibe Coding)을 비롯하여, 미경험자가 개발에 진입하는 장벽이 단번에 낮아졌고 진입자는 급증하고 있다. 이제는 프로덕트의 「인플레이션 상태」라고 해도 과언이 아닐지도 모른다.

하지만 프로덕트를 만들 수 있게 된 것 자체는 기쁜 일인 한편, 그 프로덕트가 오랫동안 살아남을 수 있을지는 전혀 별개의 문제로 남아 있다.

취미나 개인 개발이라면 그래도 문제없다. 하지만 AI는 이제 전 세계 개발 현장의 최전선에서 사용되고 있다. 그 자체는 매우 좋은 일이다.

한편, AI로 개발된 프로덕트의 상당수는 사양(Specification)을 정리한 문서가 남아 있지 않은 경우가 적지 않다. 이는 AI 이전 시대에도 있었던 이야기다. 하지만 지금 시대는 상황이 조금 다르다.

개발자 자신의 머릿속에도 사양이 남아 있지 않은 것이다.

즉, 진정한 의미에서 「존재하지 않는다」.

AI가 등장함으로써 개발 속도는 극적으로 향상되었음에도 불구하고, 프로덕트를 계속 운용해 나가는 난이도는 오히려 엄청나게 높아져 버리고 말았다.

그래서 나는, **AI 시대의 문서 주도 개발(Document-Driven Development)**을 제창하고 싶다.

문서를 기점으로 개발한다는 사고방식 자체는 결코 새로운 것이 아니다. 폭포수(Waterfall) 모델적인 사양서 주도 개발이나, DDD(Domain-Driven Design)에서의 「언어화」 중시 등 이전부터 이야기되어 온 것이다.

그렇다면 왜 지금 굳이 이것을 내세우는가.

이유는 단순하다. AI 이전에는 「번거롭기 때문에 생략되었던」 공정이, AI에 의해 생략하지 않아도 돌아가게 되었기 때문이다. 사양의 포맷화도, 설계서로의 반영도, 인력으로 하려고 하면 상당한 시간과 노력이 든다. 그렇기에 많은 현장에서 경시되어 왔다.

하지만 AI를 사용하면 대략적인 메모를 포맷이 갖춰진 사양서로 변환하는 작업도, 그 사양서로부터 설계서를 작성하는 작업도 대폭 효율화할 수 있다. 「사양을 쓸 여유가 없다」는 변명이 AI 시대에는 통하지 않게 된 것이다.

먼저 docs 디렉토리에 프로덕트 디자인을 대략적으로 적어 내려간다. 여기는 상당히 대충 해도 좋다.

• 무엇을 할 수 있는가
• 어떤 기능이 필요한가
• 어떤 언어/프레임워크/라이브러리로 구축할 것인가
• 어떤 기능이 핵심(Core)이 되는가
• 개발에서 무엇을 중시하고 싶은가

다음으로, 그 프로덕트 디자인을 AI를 사용하여 포맷화한다. 이 시점에서 인식의 차이나 추가·삭제하고 싶은 점이 있다면 편집한다. 그 후, 다시 AI에게 포맷화를 요청한다.

이를 반복하여 product.md를 완성시킨다. 이곳이 핵심이다.

다음으로, 그 product.md를 베이스로 FE/DB/UI/BE의 설계 문서를 docs 하위에 AI를 사용하여 기술하도록 한다.

그리고 인식에 차이가 없는지, 설계에 문제가 없는지 확인한다. 불명확한 점이나 불만족스러운 점이 있다면 질문·수정을 수행하고, 다시 LLM에 다시 쓰도록 한다. 이를 반복하여 각각의 설계서를 완성시킨다.

더 엄밀하게 설계하고 싶다면 디렉토리 구성이나 아키텍처(Architecture)에 관한 문서를 만들어도 좋다. 방법은 동일하다.

모든 것에 대해 어느 정도 납득할 만한 결과물이 만들어지면, 그것을 바탕으로 AI에게 코딩을 위탁하여 프로덕트를 만들어 나간다.

추천하는 방식은 모노레포(Monorepo) 구성이다. 설계가 흔들리기 어렵고, CLAUDE.md 등에 기록할 때나 버전 관리가 편하기 때문이다.

AI 시대의 문서 주도 개발에는 다음과 같은 장점이 있다.

사양의 버전 변경을 Git으로 관리할 수 있다

product.md나 설계 문서를 코드와 동일한 리포지토리(Repository)에서 관리함으로써, 사양이 언제·어떻게 변했는지를 이력으로 추적할 수 있다.

신규 개발자나 인수인계에 강하다

사양과 설계가 언어화되어 있기 때문에, 구두 설명이나 기억에 의존하지 않고 온보딩(Onboarding)을 할 수 있다.

AI와의 인식 차이를 사전에 방지할 수 있다

코딩을 위탁하기 전에 설계 단계에서 조율함으로써, AI가 잘못된 전제로 코드를 작성해 버릴 리스크를 줄일 수 있다.

제대로 설계된 상태에서 프로덕트 개발을 할 수 있다

기세만으로 구현에 들어가지 않고, 설계를 굳힌 뒤 착수할 수 있기 때문에 재작업(Backtrack)이 적다.

유지보수성을 어느 정도 담보할 수 있다

사양과 구현의 대응 관계가 남기 때문에, 나중에 기능 추가나 개수를 진행할 때도 영향 범위를 파악하기 쉽다.

한편, 이 방식이 항상 최적인 것은 아니다.

문서와 코드 사이의 왕복 비용이 발생한다

사양 책정(Specification) → 포맷화 → 설계 → 리뷰라는 공정을 거치는 만큼, 아이디어가 떠오른 당일에 바로 코드를 작성하기 시작하는 속도감은 떨어진다. 검증 단계의 MVP나 몇 시간 만에 완성하고 싶은 작은 도구에는 과도할 수 있다. -
문서와 구현이 괴리될 리스크

설계 후에 AI에게 구현을 전적으로 맡겨버리면, 구현이 진행되는 동안 사양서 쪽이 업데이트되지 않아, 어느샌가 "또 사양이 실제와 맞지 않게 되는" 상태로 되돌아갈 위험이 있다. 문서는 작성하고 끝내는 것이 아니라, 변경될 때마다 업데이트하는 운영 규칙과 세트로 기능해야 한다. -
탐색 단계의 프로덕트에는 부적합할 수 있음

"무엇을 만들어야 하는가" 자체가 아직 정해지지 않은, 가설 검증(Hypothesis Verification) 단계의 프로덕트에서는, 먼저 설계를 확정 짓는 것이 오히려 발목을 잡는 경우가 있다. 이 수법은 만드는 대상의 방향성이 어느 정도 보인 시점부터 효과를 발휘한다.

이러한 한계가 있음을 고려했을 때, 그럼에도 "나중에 후회하는" 것보다는 "미리 약간의 수고를 들이는" 편이, 장기적으로 운영하는 프로덕트에는 더 적합하다고 나는 생각한다.

AI에 의해 누구나 "동작하는 것"을 만들 수 있는 시대가 되었다. 이는 분명히 환영해야 할 변화다. 하지만 "동작하는 것"과 "지속될 수 있는 것" 사이에는 여전히 큰 간극이 존재한다.

그 간극을 메우는 것은 AI의 성능도, 코딩 속도도 아니다. 바로 언어화된 사양이다.

코드는 다시 쓸 수 있다. 하지만 개발자의 머릿속에만 있는 의도나 판단의 이유는, 상실되는 순간 정말로 되찾을 수 없게 된다. AI 이전의 시대였다면 본인에게 물어보면 그만이었다. 지금의 시대는 본인의 머릿속에조차 남아 있지 않을지도 모른다. 그렇기에 문서라는 형태로 외부화해 둘 필요가 있다.

프로덕트의 인플레이션 상태는 앞으로도 가속화될 것이다. 그 속에서 살아남는 것은 가장 빠르게 만들어진 프로덕트가 아니라, 가장 올바르게 계승할 수 있는 프로덕트라고 나는 생각한다.

AI에게 쓰게 하고 끝내는 것이 아니라, AI와 함께 "남길 것"을 만든다. 그것이 바로 AI 시대의 문서 주도 개발(Document-Driven Development)이다.