AI에게 코드를 작성하게 하면서, 이런 경험을 해본 적 없으신가요?

• 생성된 코드가 기존 아키텍처 (Architecture)와 전혀 맞지 않는다
• PR (Pull Request)이 너무 거대해져서 리뷰가 불가능해진다
• "왜 이렇게 구현했는지"를 알 수 없어 수정에 불필요한 시간이 걸린다
• 몇 번을 말해도 비슷한 실수를 반복한다

이런 일을 겪으면 "역시 AI는 신뢰할 수 없어"라는 결론에 빠지기 쉽습니다.

하지만, 수차례 AI에게 개발을 맡기며 깨달은 것은 진정한 문제는 AI의 능력이 아니었다는 점입니다. 문제는 AI에게 전달하는 "입력"――즉 스코프 (Scope)의 모호함에 있습니다.

그래서 누구나 "그럼 사양 (Specification)을 제대로 문서로 전달하자"라고 생각하게 되지만, 여기서 두 번째 늪에 빠집니다.

개발 문서는 결국 몇 개나 필요할까?

이 기사는 그 질문에 대해 실제로 "12문서", "3문서", "7문서"를 시도해보고 각각의 문제점을 겪은 끝에 얻은 고찰입니다. 결론부터 말씀드리면 최종적으로 7문서에 안착했습니다만, 흥미로운 점은 숫자보다 그곳에 도달하기까지의 과정이라고 생각하기에, 그 압축해 나가는 흐름을 공유하고자 합니다.

기존의 소프트웨어 개발에서는 문서 템플릿이 60종류 이상 있는 것도 드문 일이 아닙니다. "설마 그렇게 많겠어?"라고 생각하실지도 모르니, 대표적인 것들을 개발 단계 순으로 전부 나열해 보겠습니다.

대략 훑어봐도 66종류입니다. 세는 방식에 따라 증감이 있겠지만, 제대로 갖추려고 하면 가볍게 60개를 넘기는 것이 현실입니다.

사람도 전부 읽지는 않습니다. 그렇다면 이걸 전부 AI에게 전달하면 최강의 사양이 될까요?

정답은 No입니다. 이유는 두 가지가 있습니다.

• 컨텍스트 윈도우 (Context Window)의 제한: 60개의 파일을 매번 읽게 하는 것은 현실적이지 않으며, 전달한다 해도 중요한 정보가 희석된다.
• 더 근본적인 문제: 정보가 산재하면 문서 간에 모순이 발생한다.

특히 두 번째가 치명적입니다. "사용자 등록 사양"이 요구사항 정의서에도, 기능 사양서에도, API 사양서에도 적혀 있는데, 심지어 각각 미묘하게 다르다면―― AI는 무엇을 믿어야 할지 알 수 없게 됩니다.

여기서부터가 본론입니다. "적절한 문서의 수"를 실제로 양 끝단에서부터 탐색해 나갔습니다.

먼저, 제대로 정리한 12문서 구성을 시도했습니다.

요구사항 정의 / 기능 사양 / 비기능 요구사항 / API 사양 / DB 설계 / 컴포넌트 설계 / 테스트 계획 / 테스트 사양 / 배포 절차 / 모니터링 설계 / 장애 대응 / 용어집

그 결과, 두 가지 문제가 발생했습니다.

• 문서 간의 중복과 모순: 동일한 사양이 여러 파일에 조금씩 다른 기술로 흩어져 있음
• AI에 대한 지시의 복잡화: "구현해줘"라고 말할 때마다 "요구사항 정의서의 이 부분과 기능 사양서의 이 부분, API 사양서의 이 부분을 참조해"라고 매번 지정해야 함

정리하려고 했던 것이 오히려 AI를 혼란스럽게 만들고 있었습니다.

반대로 "최소한으로만 해보자"라며 3문서 (README / ARCHITECTURE / PATTERNS)만으로 시작한 프로젝트도 있었습니다.

이번에는 다른 문제입니다.

• 비즈니스 규칙 (Business Rule)을 둘 곳이 없음: "이 할인 규칙은 어디에 적지?", "이 상태 전이는 어디서 관리하지?"라는 질문이 빈번해지고, 갈 곳을 잃은 정보가 전부 README로 흘러 들어와 비대해짐

너무 적으면 이번에는 정보가 행방불명되었습니다.

12개는 너무 많아서 모순을 낳고, 3개는 너무 적어서 정보가 미아가 됩니다. 이 양 끝단을 오간 결과, 도달한 곳이 바로 7문서였습니다.

60개 이상의 개발 문서
│ 너무 많음: 컨텍스트 초과 + 정보가 산재하여 모순 발생
▼
...

7이라는 숫자에 특별한 의미가 있다기보다, "정보의 중복을 피하면서도 필요한 정보가 누락되지 않는" 균형을 찾다 보니 우연히 7이 된 순서입니다.

최종적으로 남은 것이 이 7가지입니다. 각각에 명확한 역할이 하나씩 할당되어 있어, "이 정보는 어디에 적어야 할까" 고민하지 않게 되는 구성입니다.

이 7가지는 "있으면 편리한 문서"를 모은 것이 아니라, 누락되었을 때 AI가 구체적으로 무엇 때문에 헤맬지를 역산하여 설계되었습니다.

예를 들어 DOMAIN.md가 없는 상태에서 EC 사이트의 "상품 구매 기능을 구현해줘"라는 요청을 받으면, "1회 구매는 상품 10개까지", "5,000엔 이상 구매 시 무료 배송"과 같이 팀 내에서는 당연하지만 어디에도 적혀 있지 않은 규칙을 AI는 알 방법이 없어 일반적인 구현으로 채워버립니다. 이는 "AI가 잘못된 것"이 아니라, 규칙의 위치(=DOMAIN.md)를 마련해두지 않은 쪽의 문제입니다.

7개 문서까지 압축해도, 운영하다 보면 "이 정보는 어느 문서에 적어야 하더라?"라고 고민하는 순간이 옵니다. 그때 효과적인 것이 이 대응 관계입니다.

Why (왜 필요한가) → PROJECT.md -
What (무엇을 실현하는가) → DOMAIN.md -
How (어떻게 실현하는가) → ARCHITECTURE.md -
How to write (어떻게 작성하는가) → PATTERNS.md

문서를 처음부터 7개 완벽하게 갖출 필요는 없습니다. 우선 MASTER.md / ARCHITECTURE.md / PATTERNS.md 이 3개부터 시작하여, 리뷰에서 지적된 내용을 해당 문서에 추가하며 키워나가가는 것이 현실적입니다.

"아까 3개 문서는 실패한 것 아닌가?"라고 생각할지도 모릅니다. 실패한 것은 3개에서 멈춘 케이스입니다. 여기서의 3개는 비즈니스 규칙이 등장하면 DOMAIN.md를 추가하는 식으로, 7개까지 키워나가는 것을 전제로 한 출발점입니다. 색인 또한 비대해지기 쉬운 README가 아니라 전용 MASTER.md로 분리했습니다.

이 7문서 구성과 이슈(Issue) 주도 개발 플로우를 정비한 상태에서, RAG 챗봇 기능 구현을 AI에게 맡겼을 때의 측정 결과입니다.

※ 아울러 행(line) 수 기준 생산성은 업계 평균의 100배 이상을 기록했으나, 이는 "구현 단계에 한정된 행 수 비교"이며 요건 정의 등 상류 공정은 포함하지 않습니다. 조건부 수치로 이해해 주시기 바랍니다.

포인트는 **"AI가 빠른 것"이 아니라 "사양이 정비되어 있다면, AI는 빠르고 정확하게 움직일 수 있다"**는 점입니다. 98%가 그대로 머지되고 있다는 사실이 품질을 떨어뜨리지 않고 이를 실현할 수 있었음을 보여줍니다. 반대로 말하면, 사양이 모호한 상태에서는 이 생산성을 재현할 수 없습니다.

• 개발 문서는 많으면 좋은 것이 아니다. 너무 많으면 모순이 생겨 AI가 헤맨다.
• 그렇다고 너무 적으면 비즈니스 규칙이 행방불명되어 README가 비대해진다.
• 12개 문서와 3개 문서 양극단을 시도한 결과, "중복되지 않고/누락되지 않는" 균형점이 코어 7문서였다.
• 7개 문서는 "있으면 편리한 것"이 아니라 "누락되면 AI가 무엇 때문에 헤맬지"를 역산하여 설계되었다.

"문서를 몇 개 만들 것인가"로 소모하던 것이 "이 정보는 어느 문서에 적을 것인가"만 생각하면 되게 되었다――이 전환이 AI에게 안심하고 개발을 맡길 수 있는지 여부의 분기점이었습니다.

이 기사는 서적 『

AI仕様駆動開発 (AI Specification-Driven Development) ―― AI 에이전트 개발의 새로운 상식』의 핵심 내용을 발췌 및 재구성한 것입니다. 각 문서에 구체적으로 무엇을 적을지, 템플릿, 이슈 (Issue) 주도 실천 플로우, 조직 도입 방법은 서적에서 자세히 설명하고 있습니다.

📘 서적은 이쪽으로

• Kindle (전자책): amzn.asia/d/09XOussK
• 페이퍼백 (종이책): amzn.asia/d/02BXIxN3