문서 체계 가이드

컨벤션(링크·파일명·frontmatter)은 CONVENTIONS.md 참고. 도구 설치는 setup 참고.

이 저장소의 모든 문서는 repo 안에 마크다운으로 관리한다(docs-as-code). 문서 변경은 코드와 같은 PR 리뷰를 거친다.

문서 유형과 위치

유형	질문	위치	템플릿
기획 (PRD)	왜 만드는가	`docs/product/`	`templates/prd.md`
설계 (Design Doc)	어떻게 만드는가	`docs/design/`	`templates/design-doc.md`
결정 (ADR)	왜 그렇게 정했는가	`docs/adr/`	`adr/0000-template.md`
운영 (Runbook)	장애 시 무엇을 하는가	`docs/runbook/`	`templates/runbook.md`
회고 (Postmortem)	무엇을 배웠는가	`docs/postmortem/`	`templates/postmortem.md`

문서 작성 원칙 (Diátaxis 기준)

한 문서에는 한 가지 목적만 담는다. 정보가 많아지는 이유는 대부분 아래 4가지가 한 문서에 섞이기 때문이다.

Tutorial (학습): 처음 온 사람이 따라 하는 단계별 안내 → 온보딩 문서
How-to (작업): 특정 작업의 절차 → Runbook, 배포 가이드
Reference (조회): 정확한 사실의 나열 → API 스펙(OpenAPI 자동 생성), 설정값 목록
Explanation (이해): 배경과 이유 → ADR, Design Doc의 배경 섹션

라이프사이클 규칙

ADR은 append-only. 수정하지 않는다. 결정이 바뀌면 새 ADR을 쓰고 이전 ADR에 Superseded by NNNN을 표시한다.
Design Doc은 구현 완료 시 상태를 Implemented로 바꾸고 보존한다. 이후의 변경은 새 문서로.
PRD는 살아있는 문서. 범위가 바뀌면 변경 이력 섹션에 기록하며 수정한다.
Runbook은 장애 대응 후 반드시 갱신한다. 실제로 안 맞았던 절차를 그대로 두지 않는다.
모든 문서 상단에 상태(Draft / In Review / Approved / Implemented / Deprecated)와 담당자를 명시한다.

AI 친화 규칙

코드 변경 PR에 관련 문서 변경을 포함한다 (리뷰 체크리스트 항목).
문서는 짧게, 상세는 링크로. AI 컨텍스트는 유한하다.
결정의 “왜”는 반드시 ADR에 남긴다. AI가 기존 결정을 뒤집는 제안을 하는 것을 막는 가장 효과적인 수단이다.