공통 문서 템플릿¶

위키의 모든 문서는 자기 type에 맞는 형식을 따른다. 그래야 같은 종류의 문서가 어디서나 같은 골격으로 읽힌다. 실제 틀은 4-reference/templates/<type>.md에 한 벌씩 있고, 새 문서는 그걸 복사해 시작한 뒤 같은 폴더의 최근 문서를 형식 참고로 채운다. 이 페이지는 "어떤 type에 어떤 틀이 있고 무슨 섹션으로 구성되나"를 한눈에 보여주는 인덱스다. 틀 파일 자체는 오너 검토 없이 고치지 않는다.

시작 절차¶

쓰려는 문서의 type을 아래 매핑 표에서 고른다.
4-reference/templates/<파일>.md를 복사해 들어갈 위치에 붙인다.
머리말(아래 표준)을 채우고 섹션 골격에 실제 내용을 담는다.
같은 폴더의 같은 type 최근 문서를 형식 참고로 본다.

머리말 (모든 위키 페이지 필수)¶

---
title: <한글 제목>          # nav 표시
type: <아래 매핑 표의 type>
owner: "@담당자"
policy: protected|living|append-only|derived
updated: YYYY-MM-DD
source: []        # raw/notion/... 또는 Issue URL — 출처(provenance). 없으면 []
links: []         # 관련 위키 페이지만 [[basename]]
scenarios: []     # 정당화 시나리오 ID
tags: []          # 선택 — 의미 있을 때만
visibility: private   # 랜딩/리크루팅만 public
---

source(raw 출처)와 links(관련 위키 페이지)는 분리한다. raw 경로를 links에 섞지 않는다.

type → 템플릿 파일 매핑¶

4-reference/templates/ 에 18개 골격 파일이 있다. type별 대응:

type	템플릿 파일	섹션 골격	주 위치
overview	`overview.md`	무엇·왜 → 여기 있는 것 → 여기서 시작하라 → 오너·갱신 → 관련	모든 카테고리 `index.md`
glossary	`glossary.md`	용어 → 정의 → 맥락·예 → 관련 용어·문서	glossary
reference	`reference.md`	요지(한 줄 정의) → 본문(표/불릿 중심 사실) → 관련	레퍼런스 사실·자료 (external-resources·faq·books)
method	`method.md`	요지 → 언제 쓰나/안 쓰나 → 단계 → 체크리스트 → 흔한 함정 → 예시·폼 → 관련	methodology-literacy
principle	`principle.md`	요지 → 핵심 원칙 → 판단 기준·룰 → 하지 말 것 → 예시 → 관련	hub 사고방식·철학
persona	`persona.md`	요지 → 맥락·목표 → 좌절점 → 우리 해결 → 금지 메시징 → 관련	2-product/insight/personas
prd	`prd.md`	요지 → 목표·성공기준 → 페르소나 → 범위 → 요구사항 → 근거 → 오픈이슈	기능 컨테이너 (기획)
design	`design.md`	요지 → 상위 PRD → 플로우 → 화면·컴포넌트 → 인터랙션 → 접근성 → 핸드오프	기능 컨테이너 (디자인)
frd	`frd.md`	요지 → 상위 PRD → 기술 접근 → API·데이터 → 의존성 → 테스트 → 작업분해	기능 컨테이너 (개발)
feature	`feature.md`	요지 → 해결 문제 → 핵심 동작 → 관련(PRD·디자인·FRD·상태)	기능 컨테이너 index
playbook	`playbook.md`	요지 → 담당 → 단계 체크리스트 → 사용 도구 → 주의·예외	3-operations/playbooks
runbook	`runbook.md`	요지 → 트리거 → 대응 절차 → 확인 → 에스컬레이션 → 관련 인시던트	hub-eng 런북
decision (ADR)	`decision.md`	배경·문제 → 검토 대안 → 결정·근거 → 영향 범위 → 후속 액션	3-operations/decisions (append)
log	`meeting.md`·`incident.md`·`sprint.md`·`research.md`·`campaign.md`	시간순 항목, 위가 아닌 아래에 추가 (append-only)	회의·인시던트·스프린트·리서치·캠페인 로그

log은 단일 파일이 아니라 용도별 5종 골격으로 갈린다(회의록·인시던트·스프린트·리서치·캠페인). 모두 policy: append-only. 자세한 5종 골격은 각 파일 참조.

type → 본문 골격 빠른 참고 (복붙용)¶

PRD

## 요지 (왜·무엇을)
## 목표 & 성공 기준 (지표 — [[methodology-literacy]])
## 대상 페르소나 (링크)
## 범위 (포함/제외)
## 요구사항 (유저 스토리·기능)
## 근거 (피드백·아이디어·리서치 source)
## 오픈 이슈

FRD

## 요지
## 상위 PRD (링크 · 변경 시 알림)
## 기술 접근 · 아키텍처
## API · 데이터 모델 (SpringDoc — 아래 컨벤션)
## 의존성 · 영향 범위
## 테스트 계획 (→[[qa-playbook]])
## 작업 분해 (이슈 링크)

Playbook

## 요지 (목적·적용 상황)
## 담당
## 단계 체크리스트 ([ ] 항목)
## 사용 도구
## 주의 · 예외

FRD — API 명세 컨벤션¶

API를 담는 frd 문서는 백엔드 SpringDoc 규약을 따른다. 출처는 frontmatter source 참조.

기본 자동 문서화 — @RestController/@RequestMapping을 SpringDoc이 스캔해 명세 자동 생성. 코드만 써도 문서화된다.
설명 보강 — @Operation(메서드), @Parameter(파라미터), @Schema(DTO 필드)로 구체화. 비공개 API는 @Hidden.
에러 명세 — common/swagger/의 메타 어노테이션(@ErrorResponseAnnotation) 기반. 도메인별 Api{Domain}ErrorResponses 어노테이션을 컨트롤러 메서드에 붙이면 ErrorCode가 HTTP 상태별로 그룹화돼 Swagger ApiResponse·Example이 자동 생성된다. 새 도메인은 어노테이션 파일을 추가하고 컨트롤러에서 사용.

6-part 기능 컨테이너(index·prd·design·frd·status·release-notes 공존)는 wiki-spec §2 참조. 없는 파일만 생성, 기존 덮어쓰기 금지.