| name | docs-writing |
| description | 문서 작성/현행화 스킬. 코드 변경 후 영향받는 문서를 식별하고 업데이트합니다. 트리거 키워드 - 문서, docs, 현행화, 다이어그램, 아키텍처 문서, 워크플로우 문서 |
문서 작성 스킬 (Documentation Writing Skill)
1. 문서 체계
1.1 폴더 구조
docs/
├── architecture/ # What — 시스템이 무엇인가
│ ├── SYSTEM.md # 전체 아키텍처, 서비스 상세, NATS 패턴
│ ├── DATABASE.md # ERD, Prisma 스키마, 서비스별 DB
│ └── INFRASTRUCTURE.md # GKE, Ingress, Secrets, CI/CD
│
├── workflow/ # How — 어떻게 동작하는가
│ ├── BOOKING.md # 예약 Saga, 분산 트랜잭션
│ ├── AGENT.md # AI 부킹 에이전트
│ ├── CHAT.md # 실시간 채팅
│ ├── NOTIFICATION.md # 알림 시스템
│ └── AUTH.md # 인증/인가, RBAC
│
├── policy/ # Why — 왜 이렇게 결정했는가
│ ├── ACCOUNT_DELETION.md
│ └── MEMBERSHIP_TIER.md
│
└── management/ # 프로젝트 관리
└── ROADMAP.md
1.2 분류 기준
| 분류 | 질문 | 내용 | 예시 |
|---|
| architecture/ | "시스템이 무엇인가?" | 구조, 관계, 배포 | 서비스 목록, DB 스키마, 인프라 |
| workflow/ | "어떻게 동작하는가?" | 흐름, 시퀀스, 상태 전이 | Saga, 채팅 이벤트, 인증 플로우 |
| policy/ | "왜 이렇게 결정했는가?" | 비즈니스 규칙, 정책 | 계정 삭제, 멤버십 등급 |
| management/ | "프로젝트 현황은?" | 로드맵, 진행률 | 마일스톤, 잔여 작업 |
2. 현행화 트리거 맵
코드 변경 시 어떤 문서를 업데이트해야 하는지 판단하는 기준:
| 코드 변경 유형 | 대상 문서 |
|---|
| 서비스 추가/삭제 | architecture/SYSTEM.md |
| NATS 패턴 추가/변경 | architecture/SYSTEM.md |
| NATS 클라이언트 의존성 변경 | architecture/SYSTEM.md (Service Dependencies) |
| Prisma 스키마 변경 | architecture/DATABASE.md |
| K8s/Ingress/Secret 변경 | architecture/INFRASTRUCTURE.md |
| CI/CD 워크플로우 변경 | architecture/INFRASTRUCTURE.md |
| 예약/결제 흐름 변경 | workflow/BOOKING.md |
| Agent 도구/핸들러 변경 | workflow/AGENT.md |
| Socket.IO 이벤트 변경 | workflow/CHAT.md |
| 알림 채널/트리거 변경 | workflow/NOTIFICATION.md |
| JWT/RBAC/권한 변경 | workflow/AUTH.md |
| 비즈니스 정책 변경 | policy/*.md |
| 마일스톤 완료 | management/ROADMAP.md |
현행화 절차
- 변경 파일 확인 —
git diff --name-only 또는 작업 내용으로 판단
- 트리거 맵 대조 — 위 테이블에서 영향받는 문서 식별
- 해당 문서 읽기 — 현재 내용 파악
- 변경사항만 반영 — 추가/수정/삭제된 부분만 정확히 업데이트
- 불필요한 내용 제거 — 코드에서 삭제된 기능은 문서에서도 삭제
3. 작성 규칙
3.1 핵심 원칙
| 규칙 | 설명 |
|---|
| 한 문서 = 한 관심사 | SYSTEM.md에 DB 스키마 넣지 않음 |
| 코드가 진실, 문서는 지도 | 구현 디테일보다 흐름과 관계에 집중 |
| 500줄 가이드라인 | 한 문서가 500줄 초과 시 분할 검토 |
| 변경 로그 없음 | git log가 이력, 문서에 changelog/version 섹션 넣지 않음 |
| NATS 패턴은 소스 기준 | 문서에 패턴 나열 시 실제 코드와 대조 |
3.2 언어 규칙
| 대상 | 규칙 | 예시 |
|---|
| 본문 | 한국어 | "예약 시스템은 Saga 패턴을 사용합니다" |
| 기술 용어 | 영문 원어 유지 | Saga, NATS, JWT, Socket.IO |
| 코드/패턴 | 영문 (코드 그대로) | booking.create, slot.reserve |
3.3 포맷 규칙
- 제목:
# 문서 제목 → ## 섹션 → ### 서브섹션 (3단계까지)
- 코드 블록: 언어 태그 필수 (
typescript, bash, yaml, swift, kotlin)
- 다이어그램: mermaid 기본 사용 (GitHub 렌더링), ERD만 d2 사용
- 테이블: 비교/목록 데이터에 적극 사용
- 문서 하단:
**Last Updated**: YYYY-MM-DD 한 줄만
3.4 금지사항
❌ 변경 이력 섹션 (## Recent Updates, ## Changelog)
❌ 버전 번호 (Document Version: X.Y.Z)
❌ 목차에 앵커 링크가 없는 경우
❌ Technology Stack 중복 나열 (CLAUDE.md에 이미 있음)
❌ 한 문서에서 여러 관심사 혼합
❌ 소스 코드 전체 복사 (핵심 로직만 발췌)
4. 다이어그램 가이드
4.1 도구 선택 기준
| 용도 | 도구 | 이유 |
|---|
| flowchart, sequence, state | mermaid | GitHub 기본 렌더링, 모바일 열람 가능 |
| ERD (DB 스키마) | d2 | sql_table shape으로 컬럼/제약조건 표현 우수 |
4.2 mermaid 다이어그램
다이어그램 타입
| 용도 | 타입 | 사용 위치 |
|---|
| 시스템 구조 | graph TB / graph LR | architecture/ |
| 요청/응답 흐름 | sequenceDiagram | workflow/ |
| 상태 전이 | stateDiagram-v2 | workflow/ |
| CI/CD 파이프라인 | graph LR | architecture/INFRASTRUCTURE.md |
컬러 팔레트 (프로젝트 표준)
Frontend: fill:#4fc3f7,stroke:#0288d1,color:#fff (하늘색)
BFF: fill:#ffb74d,stroke:#ef6c00,color:#fff (주황색)
Service: fill:#ba68c8,stroke:#7b1fa2,color:#fff (보라색)
AI/Ext: fill:#4db6ac,stroke:#00796b,color:#fff (청록색)
Data: fill:#81c784,stroke:#2e7d32,color:#fff (초록색)
Message: fill:#f06292,stroke:#c2185b,color:#fff (분홍색)
Ingress: fill:#42a5f5,stroke:#1565c0,color:#fff (파란색)
External: fill:#ffcc80,stroke:#e65100,color:#fff (연주황)
중요: 모든 노드에 color:#fff 필수 (다크모드 호환). Material 300 톤 fill 사용.
규칙
subgraph로 레이어/도메인 그룹화- 동기 통신: 실선 (
-->, ->>)
- 비동기 통신: 점선 (
-.->, -->>)
- 노드 레이블: 서비스명 + 기술 (
IAM["IAM Service<br/>NestJS"])
classDef로 레이어별 색상 통일
4.3 d2 ERD 다이어그램
ERD만 d2로 작성한다. sql_table shape으로 테이블 정의, 서비스(DB)별 하나의 다이어그램으로 통합.
ERD 클래스 정의
classes: {
db-title: {
style.font-size: 22
style.bold: true
style.stroke-width: 2
style.border-radius: 12
style.shadow: true
}
group: {
style.border-radius: 8
style.stroke-width: 1
style.shadow: true
style.font-size: 16
style.bold: true
}
}
ERD 컬러 팔레트
iam_db: fill "#FFF8E1" / stroke "#FFB300"
course_db: fill "#E8F5E9" / stroke "#4CAF50"
booking_db: fill "#E3F2FD" / stroke "#1E88E5"
saga_db: fill "#FCE4EC" / stroke "#EC407A"
payment_db: fill "#F3E5F5" / stroke "#AB47BC"
partner_db: fill "#E0F2F1" / stroke "#26A69A"
chat_db: fill "#FFF3E0" / stroke "#FB8C00"
notify_db: fill "#ECEFF1" / stroke "#78909C"
ERD 주의사항
- d2 예약어(
icon, label, direction, title)를 컬럼명으로 쓸 때 따옴표 이스케이프
- 세로 배치 필요 시 투명 연결선 사용 (
style.opacity: 0)
5. 문서 유형별 구조
5.1 Architecture 문서
# 제목
## 개요 (1-2문단)
## 다이어그램 (graph TB/LR)
## 서비스/모델 상세 (테이블 + 코드블록)
---
**Last Updated**: YYYY-MM-DD
5.2 Workflow 문서
# 제목
## 개요 (구성 요소 테이블)
## 상태 정의 (stateDiagram + 상태 테이블)
## 주요 흐름 (sequenceDiagram + 단계별 설명)
## 예외 처리 (실패 시나리오, 보상 트랜잭션)
---
**Last Updated**: YYYY-MM-DD
5.3 Policy 문서
# 제목
## 목적 (법적 근거 포함)
## 적용 범위
## 규칙 (테이블)
## 프로세스 (flowchart)
---
**Last Updated**: YYYY-MM-DD
6. 상호 참조
문서 간 링크
자세한 내용은 [예약 워크플로우](../workflow/BOOKING.md)를 참조하세요.
[Saga 패턴](../workflow/BOOKING.md#booking-saga-flow)을 참조하세요.
소스 코드 참조
**소스**: `services/booking-service/src/booking/service/booking.service.ts`
7. 품질 체크리스트
문서 작성/업데이트 완료 후 확인:
