Documentation Conventions¶

docs/ 안의 모든 문서가 공유하는 작성 규칙. 독자 친화성, 장기 유지보수성, 그리고 문서 자동화 (linting, 변경 감지) 를 위해 구조를 강제한다.

Why conventions matter¶

docs 는 코드만큼 팀 자산이다. 컨벤션이 없으면 다음이 발생한다:

비슷한 문서마다 구조가 달라 독자가 매번 재학습
링크가 깨졌는지 추적 불가
LLM 도구 (Claude Code 등) 가 문서 구조를 학습 못 함
문서 품질이 작성자별로 튐

Umbra 는 "팀 한 명이 쓰고 다른 한 명이 일주일 뒤에 읽어도 즉시 맥락을 회복" 하는 수준을 목표로 한다.

Document types¶

docs/.templates/ 에 각 타입별 템플릿 있음:

Type	Path	Template	Purpose
README	`docs/README.md`	`readme.template.md`	Navigation
Overview	`docs/overview/`	`overview.template.md`	Product identity
Architecture	`docs/architecture/`	`architecture.template.md`	System-wide view
ADR	`docs/adr/`	`adr.template.md`	Single decision record
Roadmap	`docs/roadmap/`	`roadmap.template.md`	Phase planning
Domain	`docs/domain/`	`domain.template.md`	Bounded context detail
Data schema	`docs/data/`	`data-schema.template.md`	DB schema
Flow	`docs/flows/`	`flow.template.md`	End-to-end scenario
Guide	`docs/guides/`	`guide.template.md`	How-to / convention

새 문서 작성 시 해당 템플릿을 복사해서 시작.

Front matter¶

모든 문서는 YAML front matter 필수.

---
title: "Document Title"
status: Draft | Review | Approved | Deprecated | Superseded
owner: github-username
audience: [engineer, developer, all]
last_updated: 2026-04-13
reviewers: []
tags: [domain, architecture, ...]
---

Fields¶

Field	Required	Notes
`title`	Yes	파일명과 일치하거나 확장 (Title Case)
`status`	Yes	Draft 로 시작, 리뷰 후 Approved
`owner`	Yes	문서의 장기 유지 책임자 (보통 PR 작성자)
`audience`	Yes	주 독자층 (engineer/developer/all)
`last_updated`	Yes	ISO date (YYYY-MM-DD)
`reviewers`	No	리뷰한 사람 username 목록
`tags`	Yes	검색 용 (kebab-case)

Status lifecycle¶

Draft — 작성 중, 리뷰 전. 내용 변경 자유
Review — PR 제출, 리뷰어 확인 중
Approved — 머지 완료. 공식 문서
Deprecated — 더 이상 유효하지 않음. 대체 문서 링크 필요
Superseded — 새 문서로 대체됨. 헤더에 "See [new doc]" 명시

Audience¶

engineer — 시스템/아키텍처 관점 (예: architecture/, adr/)
developer — 구현 관점 (예: guides/, data/)
all — 누구나 이해 (예: overview/)

문서 내용도 audience 에 맞춤:

engineer 문서 — 의도, 트레이드오프 중심
developer 문서 — 어떻게 쓰는가, 예시 중심

하나의 문서가 두 audience 다 있을 수 있음: audience: [engineer, developer].

Structure rules¶

H1 is title only¶

H1 (#) 은 front matter 의 title 과 동일하게 문서 첫 줄. 이후 모든 헤더는 H2 이하.

Start with blockquote summary¶

H1 아래 첫 블록은 1-2 문장 blockquote 로 문서의 핵심 요약.

# Document Title

> 이 문서가 무엇을 다루는지 한두 문장. 독자가 3초 안에 "이 문서가 내가 찾던 것인가" 판단 가능.

"Why this exists" 섹션¶

본문 시작은 왜 이 문서 / 이 결정 / 이 flow 가 존재하는가. 맥락 설명 우선, 구체적 내용은 뒤.

## Why this [domain/flow/decision] exists

{문제 인식 + 고민}

Why-first 원칙 (luxtra-agent 컨벤션). 독자는 "이게 왜 필요한지" 를 알아야 나머지를 이해 가능.

5-minute read¶

대부분 문서 목표 길이는 2000~2500 단어 (약 5분 읽기). 예외:

긴 ADR — 대안 검토가 많으면 3000 단어까지 허용
Complex domain/flow — 최대 5000 단어 (더 길면 sub-document 로 분리)

길이 초과 시 sub-document 로 쪼갠다. 예: domain/recovery/ 가 overview + 4 sub.

Section order per type¶

각 템플릿이 권장 순서 제공. 임의로 섹션 순서 바꾸지 말 것. 독자는 같은 위치에서 같은 정보를 기대한다.

ADR 필수 섹션: Status → Context → Decision → Consequences → Alternatives considered → Compliance → Revisit triggers → References → Related ADRs.

Domain 필수 섹션: Bounded context → Why this domain exists → Domain model → Invariants → State machine → Domain events → Ports → Adapters → Permission model → Failure modes → See also.

Flow 필수 섹션: Scenario → Actors → Preconditions → Postconditions → Sequence → Step-by-step → Failure cases → Edge cases → Involved domains → See also.

Guide 필수 섹션: Why this guide exists → [내용] → See also.

Writing style¶

Language¶

파일명, 헤더, Mermaid diagram — English
본문 — Korean (존댓말, 기술적이고 직접적)
코드 주석 — English (backend-conventions 참조)
Commit, PR, Issue — English (AI 기여 언급 금지)

Tone¶

직접적, 간결
불필요한 반복 설명 금지
과도한 겸손 표현 ("부족하지만...") 금지
Why 설명에는 구체적 사례 포함

Format¶

Bold — 강조 또는 key term 정의 시
inline code — identifier, 파일명, command
Code block — 예시 코드 (언어 명시: ```go, ```sql, ```sh 등)
Table — 비교, 카탈로그 정리
Mermaid — flow, sequence, state, ER, gantt

Lists¶

Bullet list — 병렬 항목
Numbered list — 순서가 의미 있는 단계
Definition-style: - **Term** — definition

Mermaid diagrams¶

When to use¶

Sequence — flow/ 의 시나리오 흐름
State — domain/ 의 상태 머신
ER — data/ 의 테이블 관계
Flowchart — 조건부 decision tree (드물게)
Gantt — roadmap/ 타임라인

Common gotcha¶

Mermaid 블록 안에 {...} placeholder 금지. 파서가 깨진다.

❌ Bad:
state X { {content} }

✓ Good:
state X "real example" {
    sub1
    sub2
}

템플릿에 placeholder 쓸 때는 실제 예시 값 + 아래 설명.

Styling¶

노드명 영문 소문자 + underscore
긴 레이블은 <br/> 로 줄바꿈
중요 경로는 --> (굵은 화살표), 덜 중요는 -..->

Cross-references¶

Internal links¶

같은 docs/ 내 문서 참조 시 상대 경로:
```
[`domain/billing.md`](../domain/billing.md)
```

같은 카테고리 내부:

[`flows/payment-failure.md`](./payment-failure.md)

ADR 참조 시 번호 포함:

[`adr/0013-payment-toss-billing.md`](../adr/0013-payment-toss-billing.md)

External links¶

공식 문서만 (Stripe, Toss, Discord API, RFC)
블로그 포스트는 ADR 에 근거로 인용하는 경우만
짧은 링크로 이름 + 괄호 URL

"See also" section¶

모든 문서 마지막. 관련 문서 나열:

## See also

- `related-file-1.md`
- `../other-category/file-2.md`
- `../adr/0013-...md`

Markdown 링크 대신 파일 경로 만 표기하는 컨벤션. 짧고 명확.

Templates¶

When to update templates¶

새 섹션이 여러 문서에 공통으로 필요해지면 템플릿에 추가
섹션 이름 변경은 기존 문서 모두 업데이트 PR 동반

Template variables¶

{placeholder} 로 가이드 텍스트 포함. 새 문서 작성 시 전부 교체:

## Why this domain exists

{이 도메인이 왜 독립 경계인지 — 문제 인식과 해결 관점}

템플릿 자체에 {...} 를 Mermaid 블록 안에 넣지 않는다 (파서 충돌).

Review checklist¶

PR 로 새 문서 또는 수정을 제출 시 리뷰어 체크:

Lint automation (future)¶

Phase 2 에서 도입 검토:

markdownlint — 스타일 규칙
remark-lint — 링크 유효성
Custom checker — front matter required fields, template adherence
CI gate — 위 모두 PR 에서 검증

현재는 수동 리뷰.

Don't¶

❌ 한 문서에 여러 도메인 섞기 (한 파일 = 한 주제)
❌ 템플릿 무시하고 자유 구조
❌ AI 기여 언급 ("Claude 가 생성함" 등)
❌ 맥락 없이 선언만 ("X 는 Y 이다" — 왜 그런지 빠짐)
❌ 외부 블로그/Medium 을 근거 링크로 사용
❌ TODO 를 문서 본문에 남김 (issue 로 전환)

Do¶

✅ Why 먼저, What 나중
✅ 구체적 예시 포함
✅ Trade-off 명시 (장점만 나열 금지)
✅ 관련 문서 "See also" 에 링크
✅ 짧게 쓰고 필요 시 sub-document 분리
✅ 주기적으로 last_updated 갱신