CONTRIBUTING.md — 콘텐츠 작성 가이드

이 문서는 학습 자료를 작성하거나 수정할 때 따라야 할 상세 가이드라인입니다.

1. 파일 구조 템플릿

제목은 본문 # H1이 아니라 frontmatter의 title로 지정합니다. Starlight가 이를 H1으로 렌더링하므로, 본문에 #를 다시 쓰면 제목이 두 번 나옵니다.

모든 콘텐츠 파일은 아래 구조를 따릅니다:

---
title: "한국어 제목 (English Term)"
description: "검색 결과와 SNS 미리보기에 노출되는 완결된 한 문장. 본문을 잘라 붙이지 말 것."
sidebar:
  badge: { text: 중급, variant: note }   # 입문 | 중급 | 심화
---

> **핵심 요약**: 이 페이지의 결론을 3문장 이내로. 수식 없이, 비유를 곁들여서.

> **먼저 읽으면 좋아요**: [선행 주제](/카테고리/파일명/)

### 초보자를 위한 핵심 용어
- **용어(English)**: 한 문장 정의. 전문용어로 전문용어를 설명하지 말 것.

## 개요
한 문단으로 이 주제가 무엇이고, 왜 중요한지 설명합니다.

## 탄생 배경
누가, 언제, 어떤 문제를 풀려고 만들었는지. 인물과 연도를 명시합니다.

## 핵심 개념
- 정의와 공식 (LaTeX 수식 포함)
- 직관적 설명 (비유, 일상 예시)

#### 숫자로 이해하기
구체적인 숫자를 넣어 손으로 따라 계산할 수 있는 예시.
**모든 산술은 반드시 검산할 것.**

## 상세 내용
### 하위 주제 1
- 깊이 있는 설명
- Mermaid 다이어그램, 표, 비교

## 언제 사용하는가
- 실제 사용 시나리오 / 이 방법이 적합하지 않은 경우

## 실전 사례
실제 프로젝트의 성공 또는 실패 이야기. 구체적 수치를 포함하되,
**수치는 서로 모순되지 않아야 합니다.**

## 직접 해보기
복사해서 바로 실행되는 10~20줄 코드. 외부 데이터 파일 의존 금지.
가능하면 위 "숫자로 이해하기"와 같은 값을 재현할 것.

## 흔한 오해와 함정 (Common Pitfalls)
- 자주 범하는 실수 / 면접에서 자주 나오는 오해

## 스스로 점검하기
질문 3개. 정답은 `<details>` 접기로 숨깁니다.

## 다른 주제와의 연결
- 관련 파일에 대한 상호 참조 링크

## 참고 자료 (선택)
- 핵심 논문, 교과서 참조

2. 언어 규칙

한국어 + 영문 기술 용어

✅ 좋은 예: "정밀도 (Precision)는 양성으로 예측한 것 중 실제 양성의 비율이다."
✅ 좋은 예: "경사 하강법 (Gradient Descent)은 손실 함수를 최소화하는 방향으로..."
❌ 나쁜 예: "프리시전은 포지티브 프리딕션 중..."  (무분별한 음차)
❌ 나쁜 예: "Precision is the ratio of..."  (영문 문장)

원칙

처음 등장할 때: “한국어 (English)” 형태로 병기
이후 재등장: 한국어 또는 영문 약어 자유롭게 (문맥에 따라 자연스러운 쪽)
업계에서 영문 그대로 쓰는 용어: 그대로 사용 (예: Softmax, Adam, LSTM, Transformer)
존댓말 사용하지 않음: 격식체/평서형으로 작성 (“~이다”, “~한다”)

볼드 처리 — `**` 대신 `<strong>`을 쓰는 이유

CommonMark의 left-flanking delimiter 규칙 때문에, 한국어 문장에서 **가 볼드로 인식되지 않는 경우가 있습니다. 특히 ) 바로 뒤나 한글 바로 뒤에 공백 없이 **가 오면 그대로 별표가 노출됩니다.

❌ 정밀도(Precision)**가 높으면**...   → 별표가 그대로 보임
✅ 정밀도(Precision)<strong>가 높으면</strong>...

그래서 이 저장소는 인라인 볼드에 <strong> 태그를 사용합니다(Astro .md에서 원시 HTML은 정상 동작). 다만 목록 항목 맨 앞의 볼드는 **로 두어도 안전하므로 그대로 둡니다 — 그래서 두 표기가 한 파일에 섞여 있는 것은 의도된 것입니다.

변환은 자동화되어 있습니다:

node scripts/fix-bold.mjs      # 깨질 수 있는 ** 를 <strong>으로 변환

수식 $…$ 안에는 절대 <strong>을 넣지 마세요. KaTeX가 파싱하지 못합니다.

3. 수식 작성

LaTeX 문법

인라인: $\text{Precision} = \frac{TP}{TP + FP}$

블록:
$$
E[(y - \hat{f}(x))^2] = \text{Bias}[\hat{f}(x)]^2 + \text{Var}[\hat{f}(x)] + \sigma^2
$$

수식 작성 규칙

모든 핵심 공식은 반드시 LaTeX로 표기
변수 정의를 수식 바로 아래에 명시 (예: “여기서 $TP$ 는 True Positive, $FP$ 는 False Positive”)
유도 과정이 중요한 경우 단계별로 보여줌
이 사이트는 GitHub가 아니라 remark-math + rehype-katex로 빌드 시점에 렌더링됩니다. 아래 두 함정을 반드시 지킬 것.

⚠️ 함정 1 — 금액의 `$`는 반드시 이스케이프

한 줄(또는 표 한 칸)에 $가 2개 이상 있으면 remark-math가 이를 수식 구분자로 짝지어 버립니다. 그 결과 $ 기호가 사라지고, 사이에 낀 한글이 이탤릭 수식체로 바뀌며 띄어쓰기까지 뭉개집니다.

❌ 나쁜 예: 총 비용 $3M (인건비 $2M + 인프라 $700K)
   → 렌더 결과: "3M(인건비" — $ 사라지고 공백 소실

✅ 좋은 예: 총 비용 \$3M (인건비 \$2M + 인프라 \$700K)

$가 하나뿐이어도 항상 $로 이스케이프하세요. 나중에 금액이 하나 추가되는 순간 깨집니다.

⚠️ 함정 2 — 조건부 확률은 `\|`가 아니라 `\mid`

마크다운 표 안에서 세로줄은 셀 구분자와 충돌하므로 이스케이프가 필요합니다. 그런데 KaTeX는 \|를 노름 기호 ‖(U+2225)로 해석합니다. 조건부 확률에 쓰면 뜻이 달라집니다.

용도	올바른 표기	렌더 결과
조건부 확률 $P(A \mid B)$	`\mid`	∣ (홑세로줄)
절댓값 (스칼라)	`\lvert x \rvert`	\| \|
노름 · KL 발산	`\|`	‖ (겹세로줄) — 이 경우엔 올바름

\mid, \lvert, \rvert는 파이프 문자를 포함하지 않으므로 표 안에서도 안전합니다.

일괄 치환(sed replace-all)은 금지입니다. 노름과 KL 발산에서는 \|가 정답이므로, 조건부 확률만 골라서 고쳐야 합니다.

4. 시각 자료

Mermaid 다이어그램

.md 파일 안에 ```mermaid 코드 펜스로 작성하면, pnpm render:mermaid(빌드 시 자동 실행)가 SVG로 변환하고 이미지 참조로 원본을 덮어씁니다.

graph LR
    A[입력 데이터] --> B[전처리]
    B --> C[모델 학습]
    C --> D[평가]
    D -->|성능 부족| B
    D -->|성능 충족| E[배포]

변환 후에는 이렇게 바뀝니다:

![파이프라인 다이어그램](/diagrams/카테고리--파일명--0.svg)

변환은 되돌릴 수 없습니다. 원본 Mermaid 코드는 git 히스토리에만 남으므로, 다이어그램을 수정하려면 커밋 이력에서 원본을 찾거나 새로 작성해야 합니다.

이 가이드 문서(contributing.md)만은 scripts/render-mermaid.mjs의 제외 목록에 있어 위 예시가 코드로 유지됩니다.

이미지 대체 텍스트 (alt)

자동 생성된 alt 텍스트는 앞선 제목을 그대로 따온 것이라 언제 사용하는가 다이어그램처럼 중복되고 정보가 없습니다. 다이어그램이 무엇을 보여주는지 서술형으로 직접 작성하세요 — 스크린리더 사용자에게는 이것이 유일한 정보입니다.

마크다운 표

비교가 필요할 때 적극 활용:

| 속성 | Ridge (L2) | Lasso (L1) | Elastic Net |
|---|---|---|---|
| 희소성 | 없음 | 있음 | 있음 |
| 특성 선택 | 불가 | 가능 | 가능 |
| 상관된 특성 | 잘 처리 | 불안정 | 잘 처리 |

시각 자료 원칙

트레이드오프는 반드시 양면을 시각적으로 보여줄 것 (표, 다이어그램)
의사결정 흐름은 Mermaid flowchart로
아키텍처 구조는 Mermaid graph로
수치 비교는 표로

5. 상호 참조 (Cross-references)

같은 디렉토리 내

자세한 내용은 [Precision-Recall Trade-off](../02-precision-recall-tradeoff/)를 참고한다.

다른 디렉토리

이 개념은 [Bias-Variance Trade-off](/01-evaluation-metrics/05-bias-variance-tradeoff/)와 직접적으로 관련된다.

원칙

“이 주제를 이해하려면 먼저 X를 보세요” 형태의 선행 지식 안내
관련 주제에 대한 “더 알아보기” 링크
매 파일 하단 “다른 주제와의 연결” 섹션에서 정리

6. 새 파일 추가하기

단계

해당 카테고리 디렉토리에 번호-파일명.md 형식으로 생성
- 번호는 기존 파일의 마지막 번호 + 1
- 파일명은 영문 kebab-case (예: 09-graph-neural-networks.md)
위의 파일 구조 템플릿을 따라 작성
README.md의 해당 카테고리 목차 표에 항목 추가
관련 파일들에 상호 참조 링크 추가

새 카테고리 추가 시

번호-카테고리명/ 디렉토리 생성
README.md에 새 섹션 추가
CLAUDE.md의 저장소 구조와 카테고리별 설명 업데이트

7. 품질 체크리스트

파일 작성/수정 후 확인:

정확성 (가장 중요)

“숫자로 이해하기”의 모든 산술을 직접 검산했는가? (계산기·python으로)
“실전 사례”의 수치들이 서로 모순되지 않는가? (예: “전부 음성으로 예측”인데 Recall이 0이 아닌 경우)
표의 합계가 본문의 합계와 일치하는가?
인물·연도·논문 제목·파라미터 수를 1차 출처로 확인했는가?
같은 개념을 다른 페이지에서 다르게 설명하고 있지는 않은가?

렌더링

금액의 $를 $로 이스케이프했는가? (§3 함정 1)
조건부 확률에 \mid를 썼는가? (§3 함정 2)
pnpm build 후 dist/에 katex-error가 없는가?
다이어그램 alt 텍스트를 서술형으로 직접 썼는가?

구조

frontmatter에 title, 완결된 description, 난이도 badge가 있는가?
핵심 요약 / 초보자를 위한 핵심 용어 / 탄생 배경 / 숫자로 이해하기 / 실전 사례 / 직접 해보기 / 흔한 오해와 함정 / 스스로 점검하기 / 다른 주제와의 연결이 모두 있는가?
트레이드오프가 양면으로 설명되어 있는가?
상호 참조 링크의 대상 파일이 실제로 존재하는가?
README.md 목차에 반영되어 있는가?

빌드 후 자동 점검:

pnpm build

# 1) KaTeX 파싱 오류 — 반드시 CSS 클래스로 검사할 것
#    ('katex-error' 문자열만 찾으면 이 가이드 문서 자신이 걸린다)
grep -rl 'class="katex-error' dist/          # 결과 없어야 정상

# 2) 금액 $가 수식으로 먹히지 않았는지
grep -ro 'application/x-tex">[^<]*' dist/ | grep -E '인건비|비용|인프라'   # 없어야 정상

8. 주제별 깊이 기준

반드시 포함해야 하는 것

정의: 무엇인가 (수학적 + 직관적)
왜 중요한가: 실무에서 어떤 문제를 해결하는가
어떻게 작동하는가: 핵심 메커니즘
언제 쓰는가 / 안 쓰는가: 적용 조건과 한계
흔한 실수: 실무자들이 자주 틀리는 것
초보자 진입로: 핵심 요약, 용어 해설, 비유, 숫자 워크스루
역사적 맥락: 누가·언제·왜 만들었는가 (탄생 배경)
실행 가능한 코드: 복사해서 바로 돌아가는 스니펫 (직접 해보기)
자가 점검: 질문 3개 + 접힌 정답

선택적으로 포함하는 것

면접 질문 예시
구현 세부사항 (라이브러리별 차이)
참고 논문 목록

대중 교육 원칙

이 자료는 ML 입문자도 따라올 수 있는 것을 목표로 합니다.

수식보다 직관이 먼저 — 공식을 던지기 전에 “무엇을 재는 값인지”를 한 문장으로 말합니다.
전문용어로 전문용어를 설명하지 않기 — 처음 쓰는 용어는 그 자리에서 풀어씁니다.
비유를 하나씩 — 어려운 개념일수록 일상 비유가 필요합니다. 좋은 본보기: 과적합과 과소적합의 학생-시험 비유.
손으로 따라 계산할 수 있게 — 추상적 설명 뒤에는 구체적 숫자를 붙입니다.
낡지 않게 쓰기 — “현재 13만 회 인용”, “최신 모델은 X”처럼 시간이 지나면 틀려지는 표현 대신, 개념 서술이나 “~중 하나”처럼 견디는 표현을 씁니다. 꼭 필요한 수치는 연도를 함께 적습니다.

9. 콘텐츠 확장 계획 (후보 주제)

아직 다루지 않았지만 추가할 수 있는 주제들입니다. (GNN, 강화학습, Bayesian ML, 시계열 모델은 이미 작성되어 목록에서 제외했습니다.)

모델 유형

Anomaly Detection (이상 탐지)
추천 시스템 (협업 필터링, 행렬 분해)

이론

Information Theory와 ML의 관계
Causal Inference 기초
Differential Privacy

실무

ML 인터뷰 준비 가이드
논문 읽는 법
ML 프로젝트 포트폴리오 구성