# 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 노트북을 사용합니다. 필요한 종속성을 설치하세요: ```bash # 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` 파일로 제공됩니다: ```bash # Install R and required packages # In R console: install.packages(c("tidyverse", "tidymodels", "caret")) ``` ### 퀴즈 애플리케이션 퀴즈 앱은 `quiz-app/` 디렉토리에 위치한 Vue.js 애플리케이션입니다: ```bash cd quiz-app npm install ``` ### 문서 사이트용 문서를 로컬에서 실행하려면: ```bash # 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 노트북 열기: ```bash jupyter notebook notebook.ipynb ``` 3. 강의 내용과 연습 문제 진행 4. 필요 시 `solution/` 폴더에서 솔루션 확인 ### Python 개발 - 강의는 표준 Python 데이터 과학 라이브러리를 사용 - Jupyter 노트북을 통한 대화형 학습 - 각 강의의 `solution/` 폴더에 솔루션 코드 제공 ### R 개발 - R 강의는 `.rmd` 형식(R Markdown)으로 제공 - 솔루션은 `solution/R/` 하위 디렉토리에 위치 - RStudio 또는 R 커널이 포함된 Jupyter를 사용하여 R 노트북 실행 ### 퀴즈 애플리케이션 개발 ```bash 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 ``` ## 테스트 지침 ### 퀴즈 애플리케이션 테스트 ```bash 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 생성: ```bash 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 오픈 소스 행동 강령](CODE_OF_CONDUCT.md) 준수 - **CLA**: Contributor License Agreement 서명 필요 ## 강의 구조 각 강의는 일관된 패턴을 따릅니다: 1. **강의 전 퀴즈** - 기본 지식 테스트 2. **강의 내용** - 작성된 지침 및 설명 3. **코드 시연** - 노트북에서 실습 예제 4. **지식 확인** - 학습 이해도 확인 5. **도전 과제** - 개념을 독립적으로 적용 6. **과제** - 확장된 연습 7. **강의 후 퀴즈** - 학습 결과 평가 ## 공통 명령 참조 ```bash # 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**: [초보자를 위한 머신 러닝 모듈](https://learn.microsoft.com/en-us/collections/qrqzamz1nn2wx3?WT.mc_id=academic-77952-bethanycheum) - **퀴즈 앱**: [온라인 퀴즈](https://ff-quizzes.netlify.app/en/ml/) - **토론 게시판**: [GitHub Discussions](https://github.com/microsoft/ML-For-Beginners/discussions) - **비디오 워크스루**: [YouTube 재생 목록](https://aka.ms/ml-beginners-videos) ## 주요 기술 - **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](https://github.com/Azure/co-op-translator)를 사용하여 번역되었습니다. 정확성을 위해 최선을 다하고 있으나, 자동 번역에는 오류나 부정확성이 포함될 수 있습니다. 원본 문서의 원어 버전을 신뢰할 수 있는 권위 있는 자료로 간주해야 합니다. 중요한 정보의 경우, 전문적인 인간 번역을 권장합니다. 이 번역 사용으로 인해 발생하는 오해나 잘못된 해석에 대해 당사는 책임을 지지 않습니다.