콘텐츠로 이동

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

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

1. 파일 구조 템플릿

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

# 제목 (English Term / 한국어 용어)

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

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

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

### 하위 주제 2
...

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

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

## 다른 주제와의 연결
- 관련 파일에 대한 상호 참조 링크
- "이 주제를 이해하려면 먼저 X를 보세요"

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

2. 언어 규칙

한국어 + 영문 기술 용어

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

원칙

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

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에서 렌더링되므로 $...$와 $$...$$ 모두 사용 가능

4. 시각 자료

Mermaid 다이어그램

```mermaid
graph TD
    A[모델 학습] --> B{검증 성능 개선?}
    B -->|Yes| C[학습 계속]
    B -->|No| D[Early Stopping]
```　

마크다운 표

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

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

시각 자료 원칙

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

5. 상호 참조 (Cross-references)

같은 디렉토리 내

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

다른 디렉토리

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

원칙

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

6. 새 파일 추가하기

단계

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

새 카테고리 추가 시

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

7. 품질 체크리스트

파일 작성/수정 후 확인:

  • [ ] 파일 구조 템플릿을 따르고 있는가?
  • [ ] 핵심 수식이 LaTeX로 작성되어 있는가?
  • [ ] 처음 등장하는 용어에 영문 병기가 있는가?
  • [ ] 트레이드오프가 양면으로 설명되어 있는가?
  • [ ] "흔한 오해와 함정" 섹션이 있는가?
  • [ ] 다른 관련 파일에 대한 상호 참조 링크가 있는가?
  • [ ] Mermaid 다이어그램 문법에 오류가 없는가?
  • [ ] README.md 목차에 반영되어 있는가?

8. 주제별 깊이 기준

반드시 포함해야 하는 것

  • 정의: 무엇인가 (수학적 + 직관적)
  • 왜 중요한가: 실무에서 어떤 문제를 해결하는가
  • 어떻게 작동하는가: 핵심 메커니즘
  • 언제 쓰는가 / 안 쓰는가: 적용 조건과 한계
  • 흔한 실수: 실무자들이 자주 틀리는 것

선택적으로 포함하는 것

  • 면접 질문 예시
  • Python/sklearn/PyTorch 코드 스니펫
  • 역사적 맥락 (논문 발표 연도, 발전 과정)
  • 구현 세부사항 (라이브러리별 차이)

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

아직 다루지 않았지만 추가할 수 있는 주제들:

모델 유형

  • Graph Neural Networks (GNN)
  • Reinforcement Learning 기초
  • Bayesian Machine Learning
  • Time Series 모델 (ARIMA, Prophet, N-BEATS)
  • Anomaly Detection

이론

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

실무

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