1. 들어가며
저희 팀은 원래 Google Drive와 Google Docs로 기획 문서를 관리했어요.
그런데 AI를 기획서 작성과 수정에 활용하면서, 기존 템플릿의 구조가 조금씩 달라지는 문제가 반복됐어요 .
이를 피하려고 Markdown으로 결과를 받은 뒤 다시 Google Docs로 옮겼지만, 이번에는 변환 작업이 새로 생겼어요.
그래서 아예 Markdown을 원본으로 관리하기 위해 기획 문서를 Mintlify로 옮기기 시작했어요.
2. AI는 내용을 잘 써도 문서 양식을 잘 지키지 못했어요
저희 기획서에는 문서마다 정해진 구조가 있었어요.
예를 들어 시스템 기획서라면 개요, 목표, 핵심 규칙, 세부 동작, 예외 처리처럼 일정한 순서와 형식을 유지해야 했어요.
사람에게 “기존 양식을 유지해서 작성해 주세요”라고 하면 어렵지 않은 일이지만, AI와 작업할 때는 결과가 조금씩 달라졌어요.
기존 섹션을 빼먹거나, 비슷한 의미의 다른 제목으로 바꾸거나, 표 구조가 달라지거나, 새로운 목차를 임의로 추가하는 일이 생겼어요. 내용은 사용할 수 있어도 기존 문서에 그대로 반영하기는 어려웠어요.
결국 AI가 만든 결과를 사람이 다시 기존 템플릿에 맞게 손봐야 했어요.
3. 그래서 Markdown을 중간 포맷으로 사용했어요
이 문제를 줄이기 위해 AI에게 결과를 Markdown으로 작성하게 했어요.
Markdown은 문서 구조가 텍스트에 그대로 드러나기 때문에, 저희가 사용한 AI 작업 흐름에서는 “이 구조를 유지해”, “이 섹션만 수정해” 같은 지시를 전달하기 쉬웠어요.
# 개요## 목표## 핵심 규칙## 세부 동작## 예외 처리
실제로 템플릿을 유지하는 문제는 이전보다 나아졌어요.
하지만 새로운 수작업이 생겼어요.
AI → Markdown → 검토 → Google Docs로 복사 → 제목·표 형식 정리 → 기존 문서에 병합
AI로 기획 작업 시간을 줄이려고 했는데, AI가 만든 문서를 다시 Google Docs 형식으로 만드는 작업이 추가된 셈이에요.
그러다 한 가지 생각이 들었어요.
어차피 AI와 작업할 때 Markdown이 더 편하다면, 왜 다시 Google Docs로 바꿔야 할까?
4. Markdown을 중간 포맷이 아니라 원본으로
그래서 Markdown을 임시 결과물이 아니라 기획 문서의 원본으로 사용하기로 했어요.
필요했던 건 두 가지였어요.
첫째, AI와 개발 도구가 Markdown 원문을 그대로 사용할 수 있어야 했어요.
둘째, 그렇다고 기획자에게 개발 문서를 편집하는 것 같은 UX를 강요하고 싶지는 않았어요.
기획자에게 중요한 건 .md 확장자가 아니라 문서를 열고, 읽고, 수정하고, 관련 문서로 이동하는 경험이니까요.
이 두 조건을 함께 만족시키기 위해 Mintlify로 기획 문서를 옮기기 시작했어요.
내부에서는 Markdown으로 관리하면서, 기획자는 Mintlify의 웹 에디터에서 일반적인 문서 도구와 비슷하게 내용을 읽고 수정할 수 있었어요.
그림 1. Google Docs 중심 작업에서 Markdown 원본 기반 작업으로의 변화
5. 옮기려고 보니 문서 체계부터 다시 정리해야 했어요
처음에는 Google Docs의 문서를 그대로 옮기면 끝날 줄 알았어요.
그런데 이전 과정에서 기존 문서 체계의 문제가 눈에 더 잘 보이기 시작했어요.
같은 시스템의 내용이 PRD와 GDD, 시스템 기획서에 중복되어 있거나 서로 조금씩 다른 경우가 있었어요.
사람은 문맥을 보고 “이쪽이 최신이겠지”라고 판단할 수 있어요.
하지만 AI가 문서를 읽고 수정하게 하려면 어느 문서가 기준인지 더 명확해야 했어요.
그래서 문서를 옮기는 김에 역할부터 다시 정의했어요.
- PRD(Product Requirements Document) — 무엇을 왜 만드는가
- GDD(Game Design Document) — 게임 전체가 어떤 구조로 동작하는가
- 시스템 기획서 — 개별 시스템이 어떤 규칙으로 동작하는가
- 콘텐츠 기획서 — 플레이어가 실제로 경험하는 콘텐츠는 무엇인가
- 기능 정의서 — 기능이 구체적으로 어떻게 동작하는가
- WBS(Work Breakdown Structure) — 무엇을 언제 누가 만드는가
가장 중요하게 잡은 원칙은 같은 기획을 여러 문서가 동시에 소유하지 않게 하는 것이었어요.
예를 들어 시스템의 세부 규칙은 시스템 기획서 한 곳을 기준으로 두고, PRD나 GDD에서는 필요한 경우 그 문서를 참조하도록 했어요.
문서 종류별 기본 목차와 각 목차에 무엇을 적는지도 정했어요.
새 기획서를 만들 때 예전 문서를 찾아 비슷하게 따라 쓰는 대신, 정해진 뼈대에서 시작할 수 있도록 바꿨어요.
그림 2. PRD·GDD·시스템 기획서 등 문서별 책임 분리
6. Front Matter로 문서의 상태도 명확하게 했어요
Markdown으로 관리하면서 Front Matter도 함께 사용하기 시작했어요.
---title: 원소 시스템type: systemstatus: active---
본문이 사람이 읽는 기획 내용이라면, Front Matter는 문서 자체에 대한 정보를 담아요.
여기에 저희가 정한 type과 status 같은 메타데이터를 넣어, 사람과 AI가 본문을 읽기 전에 이 문서의 역할과 현재 상태를 먼저 확인할 수 있도록 했어요.
기획이 변경됐을 때 이전 내용을 무조건 지우지 않는 규칙도 만들었어요.
더 이상 사용하지 않는 중요한 기획은 deprecated 상태로 남겨서, 과거의 결정은 추적할 수 있으면서 AI가 예전 기획을 현재 기준으로 오해하지 않도록 했어요.
6.1 제목에 [WIP]를 붙이던 상태 관리도 바꿨어요
그림 3. [WIP] 제목 기반 상태 관리에서 Front Matter와 브랜치 관리로의 변화
기존에는 아직 작업 중인 문서라면 제목 앞에 [WIP]를 붙이는 식으로 상태를 표시했어요.
사람이 목록을 볼 때는 편했지만, 상태 정보가 제목 문자열에 섞여 있어 AI나 자동화 도구가 일관되게 처리하기는 어려웠어요.
Mintlify로 이전하면서 이 정보도 Front Matter로 분리했어요.
저희 팀에서는 Front Matter에 status 필드를 별도 규칙으로 정의해 draft·active·deprecated 상태를 관리하기로 했어요.
큰 변경 작업은 브랜치를 나눠 진행해요.
작업 중인 문서와 현재 기준 문서를 제목만으로 구분하지 않아도 되고, 변경 사항을 검토한 뒤 반영하는 흐름도 훨씬 명확해졌어요.
브랜치와 변경 이력을 함께 활용할 수 있다는 점도 좋았어요.
이전에는 문서가 수정되면 현재 내용은 쉽게 확인할 수 있어도 “어떤 변경이 언제 들어왔는지”, “실험 중인 기획과 확정된 기획이 어떻게 다른지”를 추적하려면 별도의 기록이 필요했어요.
지금은 작업 브랜치와 문서 상태를 나눠 관리하면서 기획 변경을 버전 단위로 추적하기 쉬워졌어요.
AI에게도 현재 기준 문서와 아직 검토 중인 변경사항을 구분해서 전달하기 좋아졌고요.
결과적으로 [WIP] 같은 제목 규칙은 사람이 보기 위한 표시에서 끝났지만, Front Matter와 브랜치를 사용하니 문서 상태가 사람·개발 도구·AI 모두가 읽을 수 있는 정보가 됐어요.
7. 하나의 기획서를 기획자·개발자·AI가 함께 사용해요
그림 4. 하나의 기획서를 기획자·개발자·AI가 활용하는 방식
이번 이전은 처음에는 기획자가 AI를 더 편하게 사용하기 위한 작업이었어요.
그런데 문서가 Markdown과 Front Matter 기반으로 바뀌면서 개발자에게도 장점이 생겼어요.
요즘은 개발에서도 AI 코딩 도구를 자연스럽게 사용해요. 기능을 구현할 때 관련 기획을 AI에게 전달해야 하는 경우도 많아요.
Google Docs가 원본일 때는 필요한 내용을 복사하거나 다른 형식으로 전달하는 과정이 필요했어요.
하지만 이제는 개발자가 Markdown 기획서를 그대로 컨텍스트로 사용할 수 있고, Front Matter를 통해 문서 종류와 상태 같은 정보도 함께 전달할 수 있어요.
결국 같은 기획 문서를 세 주체가 서로 다른 방식으로 사용할 수 있게 됐어요.
- 기획자 — 웹 에디터에서 문서를 읽고 수정하기
- 개발자 — Git에 있는 Markdown 문서를 개발 컨텍스트로 바로 활용하기
- AI — 구조와 상태가 명시된 문서를 검색하고 작업 컨텍스트로 활용하기
기획자의 UX를 크게 바꾸지 않으면서 개발과 AI 쪽에서는 더 구조화된 정보를 사용할 수 있게 된 점이 이번 이전에서 가장 마음에 드는 부분이에요.
8. MCP를 연결하니 문서를 전달하는 방식도 바뀌었어요
Markdown 원문을 AI에게 전달하기 쉬워졌다고 해도 사람이 매번 필요한 문서를 찾아 첨부해야 한다면 여전히 번거로워요.
MCP(Model Context Protocol)는 AI가 외부 도구나 데이터에 연결해 필요한 정보를 사용할 수 있게 해주는 방식이에요.
Mintlify에서 MCP를 사용할 수 있다는 점도 이 구조와 잘 맞았어요.
AI가 필요한 기획 문서를 검색하고 내용을 읽은 뒤, 그 정보를 기획·개발 작업의 컨텍스트로 활용할 수 있으니 매번 사람이 “이 문서를 참고해”라고 복사해서 전달하는 과정도 줄일 수 있었어요.
예전에는 사람이 기획서를 찾아서 AI에게 전달했다면, 앞으로는 AI가 매번 사람이 붙여준 문서만 읽는 대신, 문서 체계 안에서 필요한 정보를 검색하고 참고할 수 있는 방향으로 바뀐 거예요.
9. 아직 좋은 선택이라고 결론 내리기는 일러요
이전한 지 얼마 되지 않았기 때문에 아직 검증해야 할 부분도 있어요.
가장 먼저 걱정되는 건 작업자들의 적응이에요.
Google Drive와 Google Docs는 모두가 익숙한 환경이었어요. 이번에는 도구뿐 아니라 문서 종류별 역할, 템플릿, Front Matter, 문서 상태와 Agent 규칙까지 한꺼번에 바뀌었어요.
장기적으로는 문서를 찾고 관리하는 비용이 줄어들기를 기대하고 있지만, 처음 몇 번은 오히려 이전보다 느릴 수도 있어요.
그래서 실제로 몇 주간 사용하면서 원하는 문서를 더 쉽게 찾는지, 새 문서를 만드는 시간이 줄어드는지, 규칙이 작업을 방해하는 부분은 없는지 확인해볼 생각이에요.
또 하나는 인원이 늘어났을 때의 문제예요.
현재 Mintlify Starter 플랜은 에디터 5명까지 지원하기 때문에, 기획 인원이 늘어나면 편집 권한과 플랜을 다시 검토해야 해요.
지금 규모에서는 문제가 없지만, 앞으로 기획 인원이 늘어나면 고민이 필요해요.
상위 플랜으로 이동할지, 편집 권한을 일부 인원에게만 둘지 등은 팀 규모가 커졌을 때 다시 판단해야 할 부분이에요.
지금 팀에서 잘 동작한다고 해서 팀이 커졌을 때도 같은 방식이 그대로 유지된다는 보장은 없어요.
10. 마치며
처음에는 AI가 Google Docs의 기획서 양식을 잘 지키지 못하는 문제를 해결하려고 시작했어요.
하지만 Markdown을 원본으로 옮기는 과정에서 문서의 역할과 상태, 변경 이력, AI가 따라야 할 규칙까지 함께 정리하게 됐습니다.
아직 작업자 적응과 인원 증가에 따른 비용은 더 검증해야 해요.
그래도 이번 이전을 통해 한 가지는 분명해졌습니다.
AI를 잘 사용하는 것만큼, AI가 정확하게 읽을 수 있도록 프로젝트의 지식을 관리하는 구조도 중요했어요.
'Project > 마법 공방의 대장장이' 카테고리의 다른 글
| [마법 공방의 대장장이 #01] AI 기반 핵심 기능을 만들 수 있을까? — VLM과 OpenCV를 비교한 PoC 의사결정 회고 (0) | 2026.06.04 |
|---|
