다크 모드
문서 운영 가이드
이 위키의 문서는 AI 에이전트가 주로 작성·업데이트하며, 팀원이 리뷰합니다.
아래 규칙은 AI 에이전트와 사람 모두에게 적용됩니다.
문서 추가 체크리스트
새 문서를 추가할 때 아래 항목을 빠짐없이 확인하세요.
- [ ] 파일 생성: 적절한 디렉토리에
.md파일 생성 - [ ] frontmatter 작성:
description필드 필수 (GitBook에서 페이지 설명으로 표시) - [ ] SUMMARY.md 등록: 올바른 위치에 네비게이션 항목 추가
- [ ] 크로스 레퍼런스: 관련 문서에서 새 문서로의 링크 추가
- [ ] 용어 확인:
common/glossary.md에 정의된 용어 사용. 새 용어 도입 시 glossary 먼저 업데이트
기능 스펙 추가 시 추가 체크리스트
- [ ] 표준 템플릿 적용:
common/features/README.md의 템플릿 구조를 따를 것 - [ ] 도메인 디렉토리 README 업데이트: 해당 도메인 영역의 README 테이블에 새 기능 추가
- [ ] 관련 문서 섹션: 관련 tech/ 문서, ADR, 공통 규칙 문서 링크 포함
- [ ] 변경 이력: 최초 작성 이력 기록
문서 수정 규칙
- 변경 범위 최소화: 수정이 필요한 부분만 정확히 변경. 관련 없는 섹션을 건드리지 않음
- common/ ↔ tech/ 정합성: common/ 기능 스펙을 수정했으면 관련 tech/ 문서도 확인하고 필요 시 업데이트
- 변경 이력 기록: 기능 스펙의 동작 규칙이 바뀌면 변경 이력 테이블에 기록
용어 사전 업데이트 프로세스
- 새 용어 등장 시:
common/glossary.md의 적절한 테이블에 추가 - 기존 용어 변경 시: 기존 용어를 "Deprecated 용어" 섹션으로 이동하고, 새 용어를 등록
- 코드명 불일치 시: "코드명 매핑" 테이블에 기록
주의
용어 사전에 없는 도메인 용어를 문서에서 사용하지 마세요.
새 용어가 필요하면 반드시 glossary.md에 먼저 등록한 뒤 사용하세요.
의사결정 기록(ADR) 작성 시점
다음 상황에서 ADR을 작성합니다:
- 기술 스택 변경 (라이브러리/프레임워크 도입 또는 교체)
- 아키텍처 결정 (시스템 구조, 통신 방식 변경)
- 비즈니스 규칙 변경 (도메인 로직, 상태 전이 변경)
- 트레이드오프가 있는 선택 (명확한 정답이 없어 논의 후 결정한 사항)
파일 위치: common/decisions/{연도}/{번호}-{kebab-case-제목}.md
AI 에이전트 전용 지침
정보
이 섹션은 위키 문서를 작성하는 AI 에이전트를 위한 지침입니다.
- 추측 금지: 코드나 기존 문서에서 확인되지 않은 내용을 작성하지 말 것
- GitBook 문법:
.claude/skills/gitbook-editing/SKILL.md레퍼런스를 반드시 참조 - 커밋 메시지:
docs: {변경 내용 요약}형식 사용 - 한 번에 하나의 논리적 변경: 여러 기능의 스펙을 한 커밋에 섞지 말 것
- 링크 검증: 추가하는 모든 내부 링크가 실제 파일을 가리키는지 확인
자동 동기화 시스템
이 위키는 멀티 에이전트 팀이 소스 코드 변경을 감지하여 자동으로 문서를 업데이트합니다.
팀 구조
lead (Orchestrator)
├── pr-analyst PR/커밋 메타데이터에서 변경 의도 분석
├── analyst-backend 백엔드 소스 코드 변경 분석
├── analyst-client 클라이언트/인프라 소스 코드 변경 분석
├── synthesizer 분석 리포트 통합 → 위키 파일별 수정 지침 생성
├── writer-feature common/ 레이어 작성 (PM 관점)
├── writer-tech tech/ 레이어 작성 (Engineer 관점)
└── reviewer 정확성 + 스타일 이중 검토파이프라인
Phase 0: 변경 감지
10개 소스 코드 레포를 순회하며 마지막 동기화 이후 변경이 있는지 확인합니다.
변경이 없으면 여기서 종료됩니다.
Phase 1: 분석 (병렬)
PR Analyst가 PR/커밋 메타데이터에서 "왜" 바뀌었는지 분석하고, Source Analyst들이 소스 코드에서 "어떻게" 바뀌었는지 분석합니다.
Phase 2: 합성
Synthesizer가 "왜 + 무엇 + 어떻게"를 통합하여 위키 파일별 수정 지침(Change Brief)을 생성합니다.
Phase 3: 작성 (병렬)
Feature Writer가 common/ 문서를, Tech Writer가 tech/ 문서를 각각 수정합니다.
Phase 4: 검토 + 수정 루프
Reviewer가 정확성(소스 코드 일치)과 스타일(레이어별 작성 규칙)을 이중 검토합니다.
BLOCKING 이슈 발견 시 Writer에게 피드백 → 수정 → 재검토 (최대 2라운드).
Phase 5: 커밋
모든 검토를 통과하면 자동으로 커밋하고 push합니다.
레이어별 작성 규칙 차이
| 항목 | common/ (Feature Writer) | tech/ (Tech Writer) |
|---|---|---|
| 대상 독자 | PM, 디자이너, QA, 경영진 | 개발자 |
| 톤 | 제품 관점 ("사용자가 X를 하면...") | Staff Engineer 관점 |
| 코드 스니펫 | 금지 | 권장 |
| API 엔드포인트 | 금지 | 권장 |
| DB 스키마 | 금지 | 권장 |
| Mermaid 다이어그램 | 선택 (흐름도 수준) | 권장 |
| 환경변수 | 금지 | 권장 |
주의
common/ 문서에 코드, API 경로, HTTP 상태 코드, DB 테이블명 등이 포함되면 Reviewer가 BLOCKING 이슈로 판정합니다.
리뷰 기준
BLOCKING (반드시 수정):
- 위키 텍스트가 소스 코드와 불일치
- Change Brief의 변경이 누락됨
- 추측이나 근거 없는 주장 포함
- 내부 링크가 존재하지 않는 파일을 가리킴
- 새 용어가 glossary.md에 미등록
- common/ ↔ tech/ 간 내용 불일치
- common/에 기술 상세 포함
- frontmatter description 필드 누락
- GitBook 블록 문법 오류
NON-BLOCKING (권장 개선):
- 표준 템플릿 구조 미준수
- 변경 이력 테이블 미업데이트
- 코드 블록에 파일 경로 미표시
- Mermaid 다이어그램 참여자 이름 미표시