Doc Style

---
name: doc-style
description: 진행기록 문서(docs/*.md)를 쓰거나 고칠 때 사용한다. 문서 구조, GitHub 콜아웃, 상태 배지 색, 표·mermaid·이미지 규칙과 검사기가 잡는 형식 실수를 정한다.
---

# 문서 포맷 규칙

## 문서 구조

- 문서는 `# 제목` 으로 시작한 뒤 요약 헤더 블록, 그 아래 `---` 구분선 순서로 둔다.
  **파일 맨 첫 줄을 `---` 로 시작하지 않는다** - GitHub 이 Jekyll YAML frontmatter 로
  오인해 파싱 에러가 난다.
- `# 제목` 다음에 앵커 링크가 걸린 `## 목차` 를 둔다. 헤더를 추가·삭제·변경하면 목차도
  그 자리에서 같이 고친다.
- 예외 둘 - ADR(`docs/decisions/`)은 짧은 결정 카드라 목차를 두지 않는다. 아카이브
  (`docs/archive/`)는 이동 시점 원문 스냅샷이라 형식을 고치지도 내용을 갱신하지도 않는다.

## 콜아웃

GitHub 네이티브 알림 문법만 쓴다.

| 문법 | 쓰임 |
|---|---|
| `> [!NOTE]` | 핵심 요약 |
| `> [!TIP]` | 팁 |
| `> [!IMPORTANT]` | 놓치면 안 되는 전제 |
| `> [!WARNING]` | 경고 |
| `> [!CAUTION]` | 사고로 이어지는 것 |

## 말투

음슴체, 마침표 없이, AI 스러운 표현("~해드리겠습니다" 등) 없이. **장식용 이모지는 쓰지
않는다.**

## 상태 배지

상태는 텍스트 태그를 shields.io 정적 배지로 렌더링해 색으로도 구분되게 한다.

| 태그 | hex |
|---|---|
| COMPLETED | `#3F7D58` |
| IN_PROGRESS | `#E0A458` |
| BLOCKED | `#C4553B` |
| PENDING | `#6B7280` |

형식: `![COMPLETED](https://img.shields.io/badge/COMPLETED-3F7D58?style=flat-square)`
밑줄이 있는 태그는 `__` 로 이스케이프한다 - `IN__PROGRESS`.

상태·색상 표는 각 행에 배지와 `` `#HEX` `` 코드를 병기한다.

## 표·차트·다이어그램

- 진행률은 ASCII 프로그레스 바로: `[████████░░] 80%`
- 키-값 성격의 데이터는 불릿을 반복하지 말고 **표**로 정리한다
- 구조도·플로우는 중첩 리스트 대신 ```mermaid 블록을 쓴다. `classDef` 로 위 상태 색을 입힌다
- 긴 로그·터미널 출력·세세한 수정 목록은 `<details><summary>` 로 접는다
- 수치 추이가 있는 건 표만 두지 말고 실제 그래프(스크린샷)를 남긴다
- 마크다운으로 렌더링되지 않는 요소는 미리보기·출처 링크를 표에 병기한다

## 검사기가 잡는 형식 실수

> [!WARNING]
> **표 행 사이에 빈 줄 금지.** GFM 에서 표가 끊겨 이후 행이 표 밖 텍스트로 렌더링된다.
> 행을 추가할 땐 편집 앵커를 다음 헤더가 아니라 표의 **마지막 행 끝**으로 잡는다.

> [!WARNING]
> **헤더에 공백으로 감싼 구분 문자(` - `, ` · `) 금지.** 슬러그와 GitHub 실제 앵커가
> 하이픈 개수에서 갈려 목차 링크가 깨진다. `:` 처럼 앞 단어에 붙이면 일치한다.

문서를 고친 뒤에는 `python {notesDir}/.method/scripts/check_docs.py` 를 돌린다.

## 이미지

- `docs/screenshots/` 에 그대로 저장하고 번호를 이어서 참조한다 - **크롭하지 않는다**
- 저장소가 비공개면 로컬 상대경로(`screenshots/파일명.png`)로 참조한다
- 설비 화면·로그·고객 정보가 담긴 자료는 **저장소 밖(외부 호스팅)으로 내보내지 않는다**

## 경로

로컬 절대경로를 문서에 새로 기록하지 않는다 - 저장소를 가리킬 땐 저장소 이름만 쓴다.
그 값 자체가 사실인 절대경로(설비 레지스트리 경로 등)는 예외다.