다크 모드
001. 위키 Knowledge Base 체계 개선
| 항목 | 내용 |
|---|---|
| 날짜 | 2026-03-09 |
| 상태 | 승인됨 |
| 결정 사항 | 위키 메타 구조를 AI 에이전트 중심 운영에 최적화하고, 용어 사전·기능 스펙 템플릿·문서 운영 가이드를 체계화한다. |
맥락
truloop 위키는 두 가지 목적을 가진다:
- 팀원 간 유비쿼터스 언어를 정립하고 기능 스펙을 동기화하여 합의를 이끌어냄
- AI 에이전트가 개발·기획 전 프로세스에서 제품 맥락을 정확히 파악하는 컨텍스트 소스
2025-2026년 업계에서는 "Context Engineering"이라는 새로운 분야가 부상했다. AI 에이전트에게 정확한 컨텍스트를 제공하는 것이 코드 품질에 직결된다는 인식이 확산되었고, AGENTS.md, Spec-Driven Development 같은 패턴이 등장했다.
기존 위키는 문서 구조(common/tech 2레이어)와 용어 사전이 잘 갖춰져 있었으나, 다음 부분에서 개선이 필요했다:
- CLAUDE.md에 제품 도메인 맥락 부재 → AI가 기본적인 제품 이해 없이 시작
- 용어 사전에 엔티티 간 관계와 코드명 매핑 부재
- 문서 운영 가이드 부재 → 일관성 없는 문서 품질
- 기능 스펙 템플릿에 크로스 레퍼런스 누락 → common/과 tech/ 간 연결 끊김
- ADR 섹션이 비어 있음 → 의사결정 기록 문화 미정착
고려한 대안
대안 1: 현행 유지 + 개별 문서만 보강
- 장점: 변경 범위 최소
- 단점: 메타 구조 문제(템플릿, 가이드, AI 컨텍스트)가 해결되지 않음
대안 2: 위키 플랫폼 교체 (GitBook → Mintlify/Docusaurus)
- 장점: 더 나은 검색, API 문서 자동 생성
- 단점: 마이그레이션 비용이 크고, 기존 GitBook 커스텀 블록 재작업 필요. 현재 GitBook + GitHub 동기화가 잘 작동 중
대안 3: 메타 구조만 개선 (채택)
- 장점: 기존 101개 문서 콘텐츠 유지, 프레임워크 강화로 향후 문서 품질 향상
- 단점: 기존 문서가 즉시 개선되지는 않음 (점진적 업데이트 필요)
선택 이유
대안 3을 채택했다. 핵심 판단 기준:
- 투입 대비 효과: 메타 문서(CLAUDE.md, 템플릿, 가이드) 5-6개만 수정하면 향후 작성되는 모든 문서의 품질이 향상
- AI 에이전트 효율: CLAUDE.md에 제품 컨텍스트를 포함하면 에이전트가 매번 여러 파일을 탐색하지 않아도 기본 맥락 파악 가능
- 점진적 개선: 기존 문서는 수정이 필요할 때 새 템플릿에 맞춰 자연스럽게 업데이트
결과
CLAUDE.md: 제품 개요, 핵심 도메인 모델 요약, 서비스 맵, 문서 탐색 가이드, AI 에이전트 작성 지침 추가common/glossary.md: 엔티티 관계 다이어그램, 코드명 매핑 테이블, Deprecated 용어 섹션 추가common/contributing.md: 문서 운영 가이드 신규 작성 (AI 에이전트 중심)common/features/README.md: 기능 스펙 템플릿에 "관련 문서" 섹션 추가- 이 ADR 자체가 첫 번째 의사결정 기록의 실제 사례