0001. 팀 문서를 docs-as-code + Obsidian/Relay 하이브리드로 관리한다
- 상태: Accepted
- 결정일: 2026-07-24
- 결정자: (팀원 이름 기입)
맥락 (Context)
기획·설계·결정·운영 문서가 흩어져 있고, AI 에이전트(Claude Code 등)를 개발 워크플로우에 도입하면서 AI가 읽을 수 있는 단일 문서 소스가 필요해졌다. 팀에는 비개발 직군이 있어 Git 기반 워크플로우만으로는 전원이 참여할 수 없다.
고려한 옵션 (Considered Options)
- Notion 단일화 — 협업성 최고, 그러나 문서가 코드와 분리되어 AI 접근이 불안정하고 문서-코드 불일치(문서 부패)가 구조적으로 발생
- Git repo 단일화 — AI·버전관리 최적, 그러나 비개발 직군의 참여 장벽이 높음
- GitBook — WYSIWYG + Git 동기화로 양쪽을 잇지만 유료이며 도구 종속 발생
- repo 소스 + Obsidian 편집 + Relay 실시간 협업 + Quartz 웹 배포 — 도구는 나뉘지만 원본은 하나
옵션별 비교
| 기준 | Notion | Git 단일 | GitBook | 하이브리드(4) |
|---|---|---|---|---|
| AI 접근성 | 낮음 | 최고 | 중간 | 최고 |
| 비개발자 참여 | 최고 | 낮음 | 높음 | 높음 |
| 비용 | 유료 | 무료 | 유료 | 거의 무료 |
| 도구 종속 | 높음 | 없음 | 중간 | 없음 |
결정 (Decision)
옵션 4를 선택한다. Git repo의 마크다운을 유일한 원본으로 삼고, 편집은 각자 편한 도구(Obsidian/VS Code/Relay)로, 읽기는 Quartz 웹사이트로 한다. 모든 구성요소가 표준 마크다운 위에서 동작하므로 어떤 도구를 나중에 교체해도 문서 자산이 남는다는 점을 가장 높게 평가했다.
결과 (Consequences)
- 좋아지는 것: AI가 문서를 코드와 함께 읽음, 문서 변경이 PR로 리뷰됨, 도구 종속 없음
- 감수하는 것: Relay 공유 폴더 → repo 동기화가 수동(문서 지기 로테이션 필요), 실시간 협업 경험은 Notion 대비 열세
- 후속 작업: Relay→repo 동기화 자동화 스크립트, Quartz 배포 파이프라인 구축
재검토 조건
- 문서 지기의 수동 동기화 부담이 주 30분을 넘으면 자동화 우선순위를 올린다
- EVC Team Relay 등 통합 솔루션이 성숙하면(1년 이상 운영 실적) 재평가한다