ML-For-Beginners/translations/ko/AGENTS.md

AGENTS.md

프로젝트 개요

이 프로젝트는 초보자를 위한 머신 러닝으로, Python(주로 Scikit-learn)과 R을 사용하여 고전적인 머신 러닝 개념을 다루는 12주, 26강의 종합 커리큘럼입니다. 이 저장소는 자율 학습 리소스로 설계되었으며, 실습 프로젝트, 퀴즈, 과제가 포함되어 있습니다. 각 강의는 전 세계 다양한 문화와 지역의 실제 데이터를 통해 머신 러닝 개념을 탐구합니다.

주요 구성 요소:

• 교육 콘텐츠: 머신 러닝 소개, 회귀, 분류, 클러스터링, NLP, 시계열, 강화 학습을 다루는 26개의 강의
• 퀴즈 애플리케이션: Vue.js 기반 퀴즈 앱으로 강의 전후 평가 제공
• 다국어 지원: GitHub Actions를 통해 40개 이상의 언어로 자동 번역
• 이중 언어 지원: Python(Jupyter 노트북)과 R(R Markdown 파일)로 제공되는 강의
• 프로젝트 기반 학습: 각 주제에 실습 프로젝트와 과제 포함

저장소 구조

ML-For-Beginners/
├── 1-Introduction/         # ML basics, history, fairness, techniques
├── 2-Regression/          # Regression models with Python/R
├── 3-Web-App/            # Flask web app for ML model deployment
├── 4-Classification/      # Classification algorithms
├── 5-Clustering/         # Clustering techniques
├── 6-NLP/               # Natural Language Processing
├── 7-TimeSeries/        # Time series forecasting
├── 8-Reinforcement/     # Reinforcement learning
├── 9-Real-World/        # Real-world ML applications
├── quiz-app/           # Vue.js quiz application
├── translations/       # Auto-generated translations
└── sketchnotes/       # Visual learning aids

각 강의 폴더는 일반적으로 다음을 포함합니다:

• README.md - 주요 강의 내용
• notebook.ipynb - Python Jupyter 노트북
• solution/ - 솔루션 코드(Python 및 R 버전)
• assignment.md - 연습 문제
• images/ - 시각 자료

설정 명령

Python 강의용

대부분의 강의는 Jupyter 노트북을 사용합니다. 필요한 종속성을 설치하세요:

# Install Python 3.8+ if not already installed
python --version

# Install Jupyter
pip install jupyter

# Install common ML libraries
pip install scikit-learn pandas numpy matplotlib seaborn

# For specific lessons, check lesson-specific requirements
# Example: Web App lesson
pip install flask

R 강의용

R 강의는 solution/R/ 폴더에 .rmd 또는 .ipynb 파일로 제공됩니다:

# Install R and required packages
# In R console:
install.packages(c("tidyverse", "tidymodels", "caret"))

퀴즈 애플리케이션

퀴즈 앱은 quiz-app/ 디렉토리에 위치한 Vue.js 애플리케이션입니다:

cd quiz-app
npm install

문서 사이트용

문서를 로컬에서 실행하려면:

# Install Docsify
npm install -g docsify-cli

# Serve from repository root
docsify serve

# Access at http://localhost:3000

개발 워크플로우

강의 노트북 작업

1. 강의 디렉토리로 이동 (예: 2-Regression/1-Tools/)
2. Jupyter 노트북 열기:

   jupyter notebook notebook.ipynb
   

3. 강의 내용과 연습 문제 진행
4. 필요 시 solution/ 폴더에서 솔루션 확인

Python 개발

• 강의는 표준 Python 데이터 과학 라이브러리를 사용
• Jupyter 노트북을 통한 대화형 학습
• 각 강의의 solution/ 폴더에 솔루션 코드 제공

R 개발

• R 강의는 .rmd 형식(R Markdown)으로 제공
• 솔루션은 solution/R/ 하위 디렉토리에 위치
• RStudio 또는 R 커널이 포함된 Jupyter를 사용하여 R 노트북 실행

퀴즈 애플리케이션 개발

cd quiz-app

# Start development server
npm run serve
# Access at http://localhost:8080

# Build for production
npm run build

# Lint and fix files
npm run lint

테스트 지침

퀴즈 애플리케이션 테스트

cd quiz-app

# Lint code
npm run lint

# Build to verify no errors
npm run build

참고: 이 저장소는 주로 교육용 커리큘럼입니다. 강의 내용에 대한 자동화된 테스트는 없습니다. 검증은 다음을 통해 이루어집니다:

• 강의 연습 문제 완료
• 노트북 셀을 성공적으로 실행
• 솔루션에서 예상 결과 확인

코드 스타일 지침

Python 코드

• PEP 8 스타일 지침 준수
• 명확하고 설명적인 변수 이름 사용
• 복잡한 작업에 대한 주석 포함
• Jupyter 노트북에는 개념을 설명하는 마크다운 셀 포함

JavaScript/Vue.js (퀴즈 앱)

• Vue.js 스타일 가이드 준수
• quiz-app/package.json에 ESLint 구성
• npm run lint 실행하여 문제 확인 및 자동 수정

문서

• 마크다운 파일은 명확하고 잘 구조화되어야 함
• 코드 예제는 fenced code blocks에 포함
• 내부 참조는 상대 링크 사용
• 기존 형식 규칙 준수

빌드 및 배포

퀴즈 애플리케이션 배포

퀴즈 앱은 Azure Static Web Apps에 배포할 수 있습니다:

1. 필수 조건:

   • Azure 계정
   • GitHub 저장소(이미 fork됨)

2. Azure에 배포:

   • Azure Static Web App 리소스 생성
   • GitHub 저장소 연결
   • 앱 위치 설정: /quiz-app
   • 출력 위치 설정: dist
   • Azure가 자동으로 GitHub Actions 워크플로우 생성

3. GitHub Actions 워크플로우:

   • .github/workflows/azure-static-web-apps-*.yml에 워크플로우 파일 생성
   • main 브랜치로 푸시 시 자동으로 빌드 및 배포

문서 PDF 생성

문서에서 PDF 생성:

npm install
npm run convert

번역 워크플로우

중요: 번역은 GitHub Actions를 통해 Co-op Translator를 사용하여 자동화됩니다.

• 번역은 main 브랜치에 변경 사항이 푸시될 때 자동 생성
• 콘텐츠를 수동으로 번역하지 마세요 - 시스템이 처리합니다
• 워크플로우는 .github/workflows/co-op-translator.yml에 정의
• Azure AI/OpenAI 서비스를 사용하여 번역
• 40개 이상의 언어 지원

기여 지침

콘텐츠 기여자용

1. 저장소를 fork하고 기능 브랜치 생성
2. 강의 콘텐츠 변경 시 추가/업데이트
3. 번역된 파일 수정 금지 - 자동 생성됨
4. 코드 테스트 - 모든 노트북 셀이 성공적으로 실행되도록 확인
5. 링크와 이미지가 올바르게 작동하는지 확인
6. 명확한 설명과 함께 pull request 제출

Pull Request 지침

• 제목 형식: [섹션] 변경 사항 간단 설명
  • 예: [Regression] 강의 5의 오타 수정
  • 예: [Quiz-App] 종속성 업데이트
• 제출 전:
  • 모든 노트북 셀이 오류 없이 실행되는지 확인
  • 퀴즈 앱 수정 시 npm run lint 실행
  • 마크다운 형식 확인
  • 새로운 코드 예제 테스트
• PR에 포함해야 할 내용:
  • 변경 사항 설명
  • 변경 이유
  • UI 변경 시 스크린샷
• 행동 강령: Microsoft 오픈 소스 행동 강령 준수
• CLA: Contributor License Agreement 서명 필요

강의 구조

각 강의는 일관된 패턴을 따릅니다:

1. 강의 전 퀴즈 - 기본 지식 테스트
2. 강의 내용 - 작성된 지침 및 설명
3. 코드 시연 - 노트북에서 실습 예제
4. 지식 확인 - 학습 이해도 확인
5. 도전 과제 - 개념을 독립적으로 적용
6. 과제 - 확장된 연습
7. 강의 후 퀴즈 - 학습 결과 평가

공통 명령 참조

# Python/Jupyter
jupyter notebook                    # Start Jupyter server
jupyter notebook notebook.ipynb     # Open specific notebook
pip install -r requirements.txt     # Install dependencies (where available)

# Quiz App
cd quiz-app
npm install                        # Install dependencies
npm run serve                      # Development server
npm run build                      # Production build
npm run lint                       # Lint and fix

# Documentation
docsify serve                      # Serve documentation locally
npm run convert                    # Generate PDF

# Git workflow
git checkout -b feature/my-change  # Create feature branch
git add .                         # Stage changes
git commit -m "Description"       # Commit changes
git push origin feature/my-change # Push to remote

추가 리소스

• Microsoft Learn Collection: 초보자를 위한 머신 러닝 모듈
• 퀴즈 앱: 온라인 퀴즈
• 토론 게시판: GitHub Discussions
• 비디오 워크스루: YouTube 재생 목록

주요 기술

• Python: 머신 러닝 강의의 주요 언어(Scikit-learn, Pandas, NumPy, Matplotlib)
• R: tidyverse, tidymodels, caret을 사용하는 대안 구현
• Jupyter: Python 강의를 위한 대화형 노트북
• R Markdown: R 강의를 위한 문서
• Vue.js 3: 퀴즈 애플리케이션 프레임워크
• Flask: 머신 러닝 모델 배포를 위한 웹 애플리케이션 프레임워크
• Docsify: 문서 사이트 생성기
• GitHub Actions: CI/CD 및 자동 번역

보안 고려 사항

• 코드에 비밀 정보 없음: API 키나 자격 증명을 커밋하지 않음
• 종속성: npm 및 pip 패키지 최신 상태 유지
• 사용자 입력: Flask 웹 앱 예제는 기본 입력 유효성 검사 포함
• 민감한 데이터: 예제 데이터셋은 공개적이고 민감하지 않음

문제 해결

Jupyter 노트북

• 커널 문제: 셀이 멈추면 커널 재시작: Kernel → Restart
• Import 오류: pip으로 필요한 패키지가 설치되었는지 확인
• 경로 문제: 노트북이 포함된 디렉토리에서 실행

퀴즈 애플리케이션

• npm install 실패: npm 캐시 삭제: npm cache clean --force
• 포트 충돌: 포트 변경: npm run serve -- --port 8081
• 빌드 오류: node_modules 삭제 후 재설치: rm -rf node_modules && npm install

R 강의

• 패키지 없음: 설치 명령: install.packages("package-name")
• RMarkdown 렌더링: rmarkdown 패키지가 설치되었는지 확인
• 커널 문제: Jupyter에서 IRkernel 설치 필요할 수 있음

프로젝트 관련 참고 사항

• 이 프로젝트는 주로 학습 커리큘럼이며, 프로덕션 코드가 아님
• 실습을 통한 머신 러닝 개념 이해에 초점
• 코드 예제는 최적화보다 명확성을 우선
• 대부분의 강의는 독립적으로 완료 가능
• 솔루션 제공되지만 학습자가 먼저 연습 문제를 시도해야 함
• 저장소는 Docsify를 사용하여 빌드 단계 없이 웹 문서 제공
• 스케치 노트로 개념의 시각적 요약 제공
• 다국어 지원으로 콘텐츠를 글로벌하게 접근 가능

---

면책 조항:
이 문서는 AI 번역 서비스 Co-op Translator를 사용하여 번역되었습니다. 정확성을 위해 최선을 다하고 있으나, 자동 번역에는 오류나 부정확성이 포함될 수 있습니다. 원본 문서의 원어 버전을 신뢰할 수 있는 권위 있는 자료로 간주해야 합니다. 중요한 정보의 경우, 전문적인 인간 번역을 권장합니다. 이 번역 사용으로 인해 발생하는 오해나 잘못된 해석에 대해 당사는 책임을 지지 않습니다.