# 문서 구조 표준

## 목적

문서를 처음 보는 사람이 전체 구조를 빠르게 이해하고, 필요한 순간에만 적용 방법이나 장애 해결 세부사항으로 내려갈 수 있게 한다.

## 기본 문서 지도

```text
README.md              무엇을, 왜 하는가 / 현재 상태 / 큰그림
├── architecture.md    어떻게 구성되며 누가 무엇을 신뢰하는가
├── cookbook.md        어떻게 적용·검증·되돌리는가
└── troubleshooting.md 무엇이 실패했고 어떻게 진단·해결하는가
```

## README 필수 항목

- 목적·범위·제외 범위
- 현재 상태와 검증된 사실
- 구성요소 5~7개 이하의 개요도
- 핵심 결정 3~5개
- 상세 문서 링크와 독자가 어떤 경우에 읽어야 하는지

## 상세 문서 규칙

| 문서 | 포함할 내용 | 포함하지 않을 내용 |
|---|---|---|
| `architecture.md` | 신뢰 경계, 구성요소 책임, 상세 흐름, 데이터 모델, 설계 근거 | 긴 설치 명령과 오류 이력 |
| `cookbook.md` | 준비물, 단계, 입력값 형식, 성공 판정, rollback, 관련 troubleshooting 링크 | 설계 배경의 반복 |
| `troubleshooting.md` | 증상, 원인, 확인 명령, 해결, 재발 방지 | secret 값, 원인 없는 임시 우회 |

## 그림 규칙

- README 개요도는 경계와 흐름만 보여 주고 화살표는 가능한 한 10개 이하로 유지한다.
- 포트, claim, redirect URI, DB role처럼 세부값이 필요한 내용은 상세도 또는 표로 분리한다.
- 그림 아래에 “이 그림에서 기억할 점”을 적는다.
- Mermaid를 쓸 때는 노드 이름을 짧게 하고, 긴 설명은 표 또는 본문으로 옮긴다.

## 보안과 검증

- 비밀번호·secret·token·cookie는 예시에도 넣지 않는다.
- 각 cookbook 단계는 성공 판정과 다음 조치를 포함한다.
- 문서를 마칠 때는 링크 유효성, Mermaid 문법, 용어 일관성, secret 노출 여부를 점검한다.