---
title: "문서 스타일 가이드"
description: Google 스타일과 Diataxis 구조를 바탕으로 한 프로젝트별 문서 작성 규칙
---

이 프로젝트는 [Google Developer 문서 스타일 가이드](https://developers.google.com/style)를 따르고 [Diataxis](https://diataxis.fr/)로 콘텐츠를 구조화합니다. 아래에는 프로젝트별 규칙만 정리합니다.

## 프로젝트별 규칙

| 규칙 | 사양 |
| --- | --- |
| 가로 구분선(`---`) 사용 금지 | 읽기 흐름을 끊습니다 |
| `####` 헤더 사용 금지 | 대신 굵은 글씨나 알림 상자를 사용합니다 |
| "관련 항목" 또는 "다음:" 섹션 금지 | 사이드바가 탐색을 담당합니다 |
| 깊게 중첩된 목록 금지 | 섹션으로 나누세요 |
| 코드가 아닌 내용에 코드 블록 사용 금지 | 대화 예시는 알림 상자를 사용합니다 |
| 콜아웃용 굵은 문단 금지 | 대신 알림 상자를 사용합니다 |
| 섹션당 알림 상자 1-2개까지 | 튜토리얼은 큰 섹션당 3-4개까지 허용합니다 |
| 표 셀 / 목록 항목 | 최대 1-2문장 |
| 헤더 예산 | 문서당 `##` 8-12개, 섹션당 `###` 2-3개 |

## 알림 상자(Starlight 문법)

```md
:::tip[제목]
단축키, 모범 사례
:::

:::note[제목]
맥락, 정의, 예시, 필수 조건
:::

:::caution[제목]
주의 사항, 잠재적 문제
:::

:::danger[제목]
데이터 손실, 보안 문제 같은 중대한 경고에만 사용
:::
```

### 표준 용도

| 알림 상자 | 사용처 |
| --- | --- |
| `:::note[필수 조건]` | 시작 전 필요한 의존성 |
| `:::tip[빠른 경로]` | 문서 상단의 짧은 요약 |
| `:::caution[중요]` | 중요한 주의 사항 |
| `:::note[예시]` | 명령/응답 예시 |

## 표준 표 형식

**단계:**

```md
| 단계 | 이름 | 내용 |
| --- | --- | --- |
| 1 | 분석 | 브레인스토밍, 리서치 *(선택 사항)* |
| 2 | 계획 | 요구사항 - PRD 또는 사양 *(필수)* |
```

**스킬:**

```md
| 스킬 | 에이전트 | 목적 |
| --- | --- | --- |
| `bmad-brainstorming` | 분석가 | 새 프로젝트 브레인스토밍 |
| `bmad-create-prd` | PM | 제품 요구사항 문서 생성 |
```

## 폴더 구조 블록

"달성한 것" 섹션에서는 다음처럼 표시합니다.

````md
```
your-project/
├── _bmad/                                   # BMad 설정
├── _bmad-output/
│   ├── planning-artifacts/
│   │   └── PRD.md                           # 요구사항 문서
│   ├── implementation-artifacts/
│   └── project-context.md                   # 구현 규칙 (선택 사항)
└── ...
```
````

## 튜토리얼 구조

```text
1. 제목 + 후킹 문장(결과를 설명하는 1-2문장)
2. 버전/모듈 안내(정보 또는 경고 알림 상자, 선택)
3. 배울 내용(결과 중심 글머리표 목록)
4. 필수 조건(정보 알림 상자)
5. 빠른 경로(tip 알림 상자 - 짧은 요약)
6. [주제] 이해하기(단계 전 맥락 - 단계/에이전트 표)
7. 설치(선택)
8. 1단계: [첫 번째 주요 작업]
9. 2단계: [두 번째 주요 작업]
10. 3단계: [세 번째 주요 작업]
11. 달성한 것(요약 + 폴더 구조)
12. 빠른 참조(스킬 표)
13. 자주 묻는 질문(FAQ 형식)
14. 도움 받기(커뮤니티 링크)
15. 핵심 요약(tip 알림 상자)
```

### 튜토리얼 체크리스트

- [ ] 후킹 문장이 결과를 1-2문장으로 설명합니다
- [ ] "배울 내용" 섹션이 있습니다
- [ ] 필수 조건이 알림 상자에 있습니다
- [ ] 상단에 빠른 경로 요약 알림 상자가 있습니다
- [ ] 단계, 스킬, 에이전트를 표로 제시합니다
- [ ] "달성한 것" 섹션이 있습니다
- [ ] 빠른 참조 표가 있습니다
- [ ] 자주 묻는 질문 섹션이 있습니다
- [ ] 도움 받기 섹션이 있습니다
- [ ] 마지막에 핵심 요약 알림 상자가 있습니다

## 사용 가이드 구조

```text
1. 제목 + 후킹 문장("`X` 워크플로를 사용해..." 한 문장)
2. 사용 시점(3-5개 글머리표 목록)
3. 건너뛸 시점(선택)
4. 필수 조건(note 알림 상자)
5. 단계(번호가 붙은 ### 하위 섹션)
6. 얻는 결과(생성되는 산출물)
7. 예시(선택)
8. 팁(선택)
9. 다음 단계(선택)
```

### 사용 가이드 체크리스트

- [ ] 후킹 문장이 "`X` 워크플로를 사용해..."로 시작합니다
- [ ] "사용 시점"에 3-5개 글머리표가 있습니다
- [ ] 필수 조건이 나열되어 있습니다
- [ ] 단계는 동작 동사로 시작하는 번호가 붙은 `###` 하위 섹션입니다
- [ ] "얻는 결과"가 산출물을 설명합니다

## 개념 설명 구조

### 유형

| 유형 | 예시 |
| --- | --- |
| **인덱스/랜딩** | `core-concepts/index.md` |
| **개념** | `what-are-agents.md` |
| **기능** | `quick-dev.md` |
| **철학** | `why-solutioning-matters.md` |
| **FAQ** | `established-projects-faq.md` |

### 일반 템플릿

```text
1. 제목 + 후킹 문장(1-2문장)
2. 개요/정의(무엇이며 왜 중요한지)
3. 핵심 개념(### 하위 섹션)
4. 비교 표(선택)
5. 사용할 때 / 사용하지 않을 때(선택)
6. 다이어그램(선택 - mermaid, 문서당 최대 1개)
7. 다음 단계(선택)
```

### 인덱스/랜딩 페이지

```text
1. 제목 + 후킹 문장(한 문장)
2. 콘텐츠 표(설명이 있는 링크)
3. 시작하기(번호 목록)
4. 경로 선택(선택 - 의사결정 트리)
```

### 개념 설명 문서

```text
1. 제목 + 후킹 문장(무엇인지)
2. 유형/범주(### 하위 섹션, 선택)
3. 주요 차이 표
4. 구성 요소/부분
5. 무엇을 사용해야 하나요?
6. 생성/커스터마이징(사용 가이드 링크)
```

### 기능 설명 문서

```text
1. 제목 + 후킹 문장(무엇을 하는지)
2. 빠른 정보(선택 - "적합한 경우:", "소요 시간:")
3. 사용할 때 / 사용하지 않을 때
4. 작동 방식(mermaid 다이어그램 선택)
5. 핵심 이점
6. 비교 표(선택)
7. 졸업/업그레이드 시점(선택)
```

### 철학/근거 문서

```text
1. 제목 + 후킹 문장(원칙)
2. 문제
3. 해결책
4. 핵심 원칙(### 하위 섹션)
5. 이점
6. 적용 시점
```

### 개념 설명 체크리스트

- [ ] 후킹 문장이 문서가 설명하는 내용을 말합니다
- [ ] 스캔하기 쉬운 `##` 섹션으로 구성합니다
- [ ] 3개 이상의 선택지가 있으면 비교 표를 사용합니다
- [ ] 다이어그램에는 명확한 라벨이 있습니다
- [ ] 절차적 질문에는 사용 가이드 링크를 제공합니다
- [ ] 문서당 알림 상자는 최대 2-3개입니다

## 참조 문서 구조

### 유형

| 유형 | 예시 |
| --- | --- |
| **인덱스/랜딩** | `workflows/index.md` |
| **카탈로그** | `agents/index.md` |
| **심층 설명** | `document-project.md` |
| **설정** | `core-tasks.md` |
| **용어집** | `glossary/index.md` |
| **종합 가이드** | `bmgd-workflows.md` |

### 참조 인덱스 페이지

```text
1. 제목 + 후킹 문장(한 문장)
2. 콘텐츠 섹션(각 범주에 ## 사용)
   - 링크와 설명이 있는 글머리표 목록
```

### 카탈로그 참조

```text
1. 제목 + 후킹 문장
2. 항목(각 항목에 ## 사용)
   - 짧은 설명(한 문장)
   - **스킬:** 또는 **핵심 정보:** 형태의 평평한 목록
3. 공통/공유 섹션(## 섹션, 선택)
```

### 항목 심층 참조

```text
1. 제목 + 후킹 문장(한 문장 목적)
2. 빠른 정보(note 알림 상자, 선택)
   - 모듈, 스킬, 입력, 출력 목록
3. 목적/개요(## 섹션)
4. 호출 방법(코드 블록)
5. 핵심 섹션(각 측면에 ## 사용)
   - 하위 선택지에는 ### 사용
6. 참고/주의 사항(tip 또는 caution 알림 상자)
```

### 설정 참조

```text
1. 제목 + 후킹 문장
2. 목차(항목이 4개 이상이면 점프 링크)
3. 항목(각 설정/작업에 ## 사용)
   - **굵은 요약** — 한 문장
   - **사용 시점:** 글머리표 목록
   - **작동 방식:** 번호 목록(최대 3-5개)
   - **출력:** 예상 결과(선택)
```

### 종합 참조 가이드

```text
1. 제목 + 후킹 문장
2. 개요(## 섹션)
   - 구성을 보여주는 다이어그램 또는 표
3. 주요 섹션(각 단계/범주에 ## 사용)
   - 항목(각 항목에 ### 사용)
   - 표준 필드: 스킬, 에이전트, 입력, 출력, 설명
4. 다음 단계(선택)
```

### 참조 체크리스트

- [ ] 후킹 문장이 문서가 참조하는 내용을 말합니다
- [ ] 구조가 참조 유형에 맞습니다
- [ ] 항목은 전체적으로 일관된 구조를 사용합니다
- [ ] 구조화/비교 데이터에는 표를 사용합니다
- [ ] 개념적 깊이가 필요한 곳에는 개념 설명 문서 링크를 둡니다
- [ ] 알림 상자는 최대 1-2개입니다

## 용어집 구조

Starlight는 헤더에서 오른쪽 "이 페이지에서" 탐색을 생성합니다.

- 범주는 `##` 헤더로 작성합니다. 오른쪽 탐색에 표시됩니다
- 용어는 개별 헤더가 아니라 표 안의 간결한 행으로 작성합니다
- 인라인 TOC는 사용하지 않습니다. 오른쪽 사이드바가 탐색을 담당합니다

### 표 형식

```md
## 범주 이름

| 용어 | 정의 |
| --- | --- |
| **에이전트** | 특정 전문성을 갖고 워크플로 전반에서 사용자를 안내하는 특화 AI 페르소나입니다. |
| **워크플로** | 산출물을 만들기 위해 AI 에이전트 활동을 조율하는 여러 단계의 안내형 프로세스입니다. |
```

### 정의 규칙

| 해야 할 것 | 하지 말 것 |
| --- | --- |
| 무엇인지 또는 무엇을 하는지로 시작합니다 | "이것은..." 또는 "이 용어는..."으로 시작합니다 |
| 1-2문장으로 유지합니다 | 여러 문단으로 설명합니다 |
| 셀 안의 용어명을 굵게 표시합니다 | 용어를 일반 텍스트로 둡니다 |

### 컨텍스트 표시

범위가 제한된 용어는 정의 시작에 이탤릭 컨텍스트를 추가합니다.

- `*빠른 흐름 전용.*`
- `*BMad Method/엔터프라이즈.*`
- `*N단계.*`
- `*BMGD.*`
- `*기존 프로젝트.*`

### 용어집 체크리스트

- [ ] 용어는 개별 헤더가 아니라 표에 있습니다
- [ ] 범주 안에서 용어를 사전순으로 정렬합니다
- [ ] 정의는 1-2문장입니다
- [ ] 컨텍스트 표시는 이탤릭입니다
- [ ] 셀 안의 용어명은 굵게 표시합니다
- [ ] "이것은..." 또는 "이 용어는..." 형태의 정의를 사용하지 않습니다

## FAQ 섹션

```md
## 질문

- [항상 아키텍처가 필요한가요?](#항상-아키텍처가-필요한가요)
- [나중에 계획을 바꿀 수 있나요?](#나중에-계획을-바꿀-수-있나요)

### 항상 아키텍처가 필요한가요?

BMad Method와 엔터프라이즈 트랙에서만 필요합니다. 빠른 흐름은 구현으로 바로 넘어갑니다.

### 나중에 계획을 바꿀 수 있나요?

예. `bmad-correct-course` 워크플로가 구현 중 범위 변경을 처리합니다.

**여기에 답이 없는 질문이 있나요?** [이슈를 열거나](...) [Discord](...)에서 물어보세요.
```

## 검증 명령

문서 변경을 제출하기 전에 다음을 실행하세요.

```bash
npm run docs:fix-links            # 링크 형식 수정 미리보기
npm run docs:fix-links -- --write # 수정 적용
npm run docs:validate-links       # 링크 존재 여부 확인
npm run docs:build                # 빌드 오류 없음 확인
```