핸드오프: 팀 문서 시스템 구축 — 고민, 결정, 트레이드오프
이 문서는 팀 문서 시스템을 설계하는 과정에서 어떤 문제를 고민했고, 어떤 대안을 검토했고, 무엇을 얻기 위해 무엇을 포기했는지를 기록한다. 이 시스템을 이어받는 사람(또는 6개월 뒤의 나)이 “왜 이렇게 돼 있지?”라고 물을 때 읽는 문서다. 최종 결정의 공식 기록은 ADR-0001에 있고, 이 문서는 거기까지 도달한 여정을 담는다.
출발점: 세 가지 문제
처음의 고민은 하나의 문장이었다 — “실무 정보가 너무 많고, AI를 위한 문서 관리까지 하고 싶다.” 이걸 풀어보니 실제로는 세 개의 문제였다.
첫째, 문서 유형이 뒤섞여 있었다. 기획 문서, 개발 문서, 아키텍처 결정이 구분 없이 쌓이면서 정보량 자체보다 분류의 부재가 과부하의 원인이었다. 둘째, 표준 템플릿이 없었다. 매번 문서 형식을 새로 고민하고 있었다. 셋째, AI 에이전트(Claude Code 등)를 개발 워크플로우에 넣으려는데, AI가 읽을 수 있는 단일하고 신뢰할 수 있는 문서 소스가 없었다.
결정 1: 문서를 4유형으로 분류하고 표준 템플릿을 채택한다
문서를 기획(PRD — 왜 만드는가), 설계(Design Doc — 어떻게 만드는가), 결정(ADR — 왜 그렇게 정했는가), 운영(Runbook — 장애 시 무엇을 하는가)의 네 유형으로 나눴다. 여기에 회고(Postmortem)를 더했다. 각 유형은 업계 표준 템플릿을 따른다: ADR은 옵션 비교표가 있는 MADR 계열, 설계는 구글식 Design Doc, 분류 철학은 Diátaxis 프레임워크(Tutorial/How-to/Reference/Explanation)를 차용했다.
“정보가 너무 많다”는 문제의 진단이 여기서 나왔다: 정보가 많은 게 아니라, 서로 다른 목적의 정보가 한 문서에 섞여 있던 것이다. 한 문서에 한 목적만 담는다는 원칙이 이 시스템 전체의 뼈대다.
결정 2: 소스 오브 트루스는 노션도 옵시디언도 아닌 Git repo다
가장 오래 고민한 지점이다. 검토 순서대로 적는다.
노션은 협업성이 최고였지만 치명적 결함이 있었다. 문서가 코드와 다른 세계에 살기 때문에 “PR에 문서 변경 포함” 규칙이 성립하지 않고, 문서 부패(코드는 바뀌었는데 문서는 그대로)가 구조적으로 발생한다. AI 접근도 MCP를 거쳐야 해서 repo 마크다운을 직접 읽는 것보다 불안정하다. AI 문서 관리라는 출발점 요구사항과 정면충돌했다.
옵시디언은 마크다운 로컬 파일이라 AI 친화적이지만 본질이 개인 도구다. 팀 공유를 하려면 결국 Git이 필요한데, 그렇다면 처음부터 repo가 원본인 게 맞다.
GitBook은 WYSIWYG 편집과 Git 양방향 동기화로 두 세계를 잇는 가장 깔끔한 단일 솔루션이었지만, 유료이고 도구 종속이 생긴다는 이유로 기각했다. 예산이 생기면 재검토할 가치는 있다.
결론: Git repo의 마크다운이 유일한 원본이고, 나머지 도구는 전부 이 원본을 편집하거나 읽는 창구다.
결정 3: “다같이 문서화”와 “같은 도구 사용”을 분리한다
비개발 직군이 있는 팀에서 “다같이 해야 의미가 있다”는 요구가 나왔고, 여기서 중요한 재정의가 있었다. 다같이 문서화한다는 것과 다같이 같은 도구를 쓴다는 것은 다른 문제다. 이 둘을 동일시하면 가장 쉬운 도구(노션)로 수렴하게 되고, 그 순간 AI 요구사항을 포기하게 된다.
대신 필요한 것은 하나로 연결된 시스템이다: 원본은 하나(repo), 편집 창구는 역할별로 다르게(개발자는 Git, 비개발자는 Relay 실시간 편집), 읽기는 모두가 같은 곳에서(Quartz 웹사이트). 문서화 문화가 무너지는 원인은 도구가 여러 개라서가 아니라 같은 내용이 두 곳에 있는데 서로 다를 때라는 것이 이 결정의 근거다.
결정 4: 그래프 구조는 도구가 아니라 링크가 만든다
repo의 폴더 구조가 수직적이라는 우려, 문서들이 노드로 연결되면 좋겠다는 요구가 있었다. 검토 결과의 핵심 통찰: 그래프는 저장 구조가 아니라 문서 안의 링크가 만든다. 옵시디언의 그래프 뷰조차 폴더가 아닌 링크의 시각화다.
따라서 Roam이나 Tana 같은 그래프-네이티브 도구로 옮기는 대신(이들은 데이터가 독점 포맷에 갇혀 docs-as-code와 충돌한다), repo 위에 그래프 레이어를 얹기로 했다: 편집 시에는 Foam/옵시디언의 백링크, 읽기에는 Quartz의 인터랙티브 그래프 뷰. 링크가 마크다운 텍스트로 존재하므로 그래프가 특정 도구에 종속되지 않고, AI에게도 그대로 보인다. 실무 가치의 대부분은 그래프 그림이 아니라 백링크(“이 ADR을 참조하는 문서가 뭐지?“)에서 나온다는 점도 확인했다.
결정 5: 최종 스택과 검증된 도구 우선 원칙
최종 구성은 이렇다. 편집 계층은 개발자가 Obsidian(+Git 플러그인) 또는 VS Code(+Foam), 비개발자가 Obsidian(+Relay 실시간 협업, 단 product/와 meetings/ 폴더만 공유). 저장 계층은 Git repo의 docs/. 소비 계층은 GitHub PR 리뷰와 CI(markdownlint, lychee 링크 검사), Quartz 웹사이트(그래프 뷰 포함), AI 에이전트(CLAUDE.md 진입점). 보조 플러그인으로 Templater(템플릿 삽입·날짜 자동화), Dataview(frontmatter 기반 인덱스 자동 생성), Linter, Excalidraw를 채택했다.
도구 선택에서 한 가지 원칙을 세웠다: 기능이 더 매력적이어도 검증이 부족한 도구에 소스 오브 트루스를 걸지 않는다. EVC Team Relay는 MCP 내장 등 기능상 이상적이었지만 출시 초기라 제외하고, 검증된 System 3 Relay를 택했다. 모든 구성요소가 표준 마크다운 위에서 동작하므로, EVC가 성숙하면 갈아타는 비용이 거의 없다 — 이 낮은 전환 비용 자체가 스택 전체의 설계 목표였다.
트레이드오프 총정리
| 결정 | 얻은 것 | 포기/감수한 것 |
|---|---|---|
| repo를 소스 오브 트루스로 | AI 직접 접근, PR 리뷰, 버전 이력, 도구 비종속 | 노션 수준의 실시간 협업 경험, 비개발자 온보딩 비용 |
| 노션 대신 하이브리드 | 문서-코드 동기화 가능성 | 논의(노션류)와 확정본(repo)의 이원 관리 부담 |
| Relay는 폴더 부분 공유만 | 비개발자의 Git 없는 참여, ADR·설계는 PR 리뷰 유지 | Relay→repo 수동 동기화(문서 지기 로테이션 필요) |
| 표준 마크다운 링크 강제 | GitHub·Quartz·AI 전 도구 호환 | 옵시디언 위키링크의 편의성 |
| System 3 Relay (EVC 대신) | 안정성, 커뮤니티 검증 | MCP 내장 등 최신 기능 (재검토 조건 명시) |
| Quartz 별도 repo 빌드 | 문서 repo의 가벼움 | 배포 파이프라인이 한 단계 복잡해짐 |
| GitBook 기각 | 무료, 종속 없음 | 가장 매끄러운 단일 도구 경험 |
미해결 과제
Relay 공유 폴더에서 repo로의 동기화가 수동이다(주 1회, 문서 지기 담당). 부담이 주 30분을 넘으면 자동화한다. Quartz 사이트의 접근 제어(사내 한정 공개)가 미정이다 — Cloudflare Access 또는 내부망 서빙 중 선택 필요. 그리고 이 수동 동기화 지점의 자동화 스크립트는, 검토 과정에서 나온 사업 아이디어(“사람과 AI가 같은 문서 시스템을 쓰는 컨텍스트 레이어”)의 첫 프로토타입이기도 하다. 유사 솔루션(EVC Team Relay, GitBook 등)이 이미 존재하므로 범용 통합 도구가 아니라 좁은 마찰 지점 하나를 자동화하는 것부터 검증하기로 했다.
산출물
team-docs-starter repo: 온보딩 README, CLAUDE.md, 문서 체계 가이드, 컨벤션 문서, 5종 템플릿(frontmatter + Templater 구문 포함), ADR-0001(이 결정 자체의 기록), 도구별 설치 가이드 3종(Obsidian/Relay/Quartz), 문서 CI 워크플로우, PR 템플릿.