bmad-code-org__bmad-method/docs/ko-kr/_STYLE_GUIDE.md

title, description

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

이 프로젝트는 Google Developer 문서 스타일 가이드를 따르고 Diataxis로 콘텐츠를 구조화합니다. 아래에는 프로젝트별 규칙만 정리합니다.

쉬운 한국어로 쓰기

핵심을 쉽게 찾고 바로 행동으로 옮길 수 있게 쓰세요. 다음 규칙은 모든 페이지에 적용합니다.

• 첫머리에서 문서의 목적과 독자가 알아야 할 내용을 분명히 밝힙니다.
• 구체적이고 익숙한 단어와 짧은 문장을 사용합니다.
• BMad를 사용하는 데 필요한 전문 용어만 씁니다. 낯선 용어는 처음 나올 때 정의합니다.
• 문자 그대로 명확하게 씁니다. 장식적인 비유를 피하세요. 작동 방식을 설명하는 대신 비유로 얼버무리지 않습니다.
• 조건과 세부 작동 방식을 설명하기 전에 요점부터 제시합니다.
• 구현 세부 사항은 독자가 문서의 목적을 이해하거나 행동하는 데 도움이 될 때만 넣습니다. 정확한 작동 방식과 계약은 참조 문서나 링크한 심층 자료에 둡니다.
• 반복, 요점을 늦추는 도입부, 과장된 주장, 독자의 결정에 영향을 주지 않는 단서는 삭제합니다.

프로젝트별 규칙

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

알림 상자(Starlight 문법)

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

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

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

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

표준 용도

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

표준 표 형식

단계:

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

스킬:

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

폴더 구조 블록

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

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

튜토리얼 구조

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

사용 가이드 구조

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

사용 가이드 체크리스트

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

개념 설명 구조

유형

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

일반 템플릿

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

인덱스/랜딩 페이지

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

개념 설명 문서

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

기능 설명 문서

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

철학/근거 문서

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

참조 인덱스 페이지

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

카탈로그 참조

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

항목 심층 참조

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

설정 참조

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

종합 참조 가이드

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

참조 체크리스트

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

용어집 구조

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

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

표 형식

## 범주 이름

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

정의 규칙

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

컨텍스트 표시

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

• *직접 진입 구현 전용.*
• *BMad Method/엔터프라이즈.*
• *N단계.*
• *BMGD.*
• *기존 프로젝트.*

용어집 체크리스트

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

FAQ 섹션

## 질문

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

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

아키텍처가 도움이 되는 작업에만 필요합니다. 범위가 명확한 작업은 구현으로 바로 들어갈 수 있습니다.

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

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

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

검증 명령

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

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