# AGENTS.md ## 프로젝트 개요 Data Science for Beginners는 Microsoft Azure Cloud Advocates가 제작한 10주, 20강의 종합 커리큘럼입니다. 이 저장소는 Jupyter 노트북, 인터랙티브 퀴즈, 실습 과제를 포함한 프로젝트 기반 강의를 통해 데이터 과학의 기초 개념을 가르치는 학습 자료입니다. **주요 기술:** - **Jupyter 노트북**: Python 3을 사용한 주요 학습 매체 - **Python 라이브러리**: pandas, numpy, matplotlib을 활용한 데이터 분석 및 시각화 - **Vue.js 2**: 퀴즈 애플리케이션 (quiz-app 폴더) - **Docsify**: 오프라인 접근을 위한 문서 사이트 생성기 - **Node.js/npm**: JavaScript 구성 요소를 위한 패키지 관리 - **Markdown**: 모든 강의 내용 및 문서화 **아키텍처:** - 다국어 교육용 저장소로 광범위한 번역 제공 - 강의 모듈로 구성 (1-Introduction부터 6-Data-Science-In-Wild까지) - 각 강의는 README, 노트북, 과제, 퀴즈를 포함 - 독립 실행형 Vue.js 퀴즈 애플리케이션으로 강의 전후 평가 가능 - GitHub Codespaces 및 VS Code 개발 컨테이너 지원 ## 설정 명령어 ### 저장소 설정 ```bash # Clone the repository (if not already cloned) git clone https://github.com/microsoft/Data-Science-For-Beginners.git cd Data-Science-For-Beginners ``` ### Python 환경 설정 ```bash # Create a virtual environment (recommended) python -m venv venv source venv/bin/activate # On Windows: venv\Scripts\activate # Install common data science libraries (no requirements.txt exists) pip install jupyter pandas numpy matplotlib seaborn scikit-learn ``` ### 퀴즈 애플리케이션 설정 ```bash # Navigate to quiz app cd quiz-app # Install dependencies npm install # Start development server npm run serve # Build for production npm run build # Lint and fix files npm run lint ``` ### Docsify 문서 서버 ```bash # Install Docsify globally npm install -g docsify-cli # Serve documentation locally docsify serve # Documentation will be available at localhost:3000 ``` ### 시각화 프로젝트 설정 예: meaningful-visualizations (13강): ```bash # Navigate to starter or solution folder cd 3-Data-Visualization/13-meaningful-visualizations/starter # Install dependencies npm install # Start development server npm run serve # Build for production npm run build # Lint files npm run lint ``` ## 개발 워크플로우 ### Jupyter 노트북 작업 1. 저장소 루트에서 Jupyter 시작: `jupyter notebook` 2. 원하는 강의 폴더로 이동 3. `.ipynb` 파일 열어 연습 진행 4. 노트북은 설명과 코드 셀이 포함된 독립형 자료 5. 대부분의 노트북은 pandas, numpy, matplotlib을 사용 - 설치 확인 필요 ### 강의 구조 각 강의는 일반적으로 다음을 포함합니다: - `README.md` - 이론 및 예제를 포함한 주요 강의 내용 - `notebook.ipynb` - 실습 Jupyter 노트북 연습 - `assignment.ipynb` 또는 `assignment.md` - 실습 과제 - `solution/` 폴더 - 솔루션 노트북 및 코드 - `images/` 폴더 - 지원 시각 자료 ### 퀴즈 애플리케이션 개발 - Vue.js 2 애플리케이션으로 개발 중 핫 리로드 지원 - 퀴즈는 `quiz-app/src/assets/translations/`에 저장 - 각 언어는 자체 번역 폴더를 가짐 (en, fr, es 등) - 퀴즈 번호는 0부터 시작하여 총 40개 ### 번역 추가 - 번역은 저장소 루트의 `translations/` 폴더에 저장 - 각 언어는 영어 구조를 그대로 따름 - GitHub Actions를 통한 자동 번역 (co-op-translator.yml) ## 테스트 지침 ### 퀴즈 애플리케이션 테스트 ```bash cd quiz-app # Run lint checks npm run lint # Test build process npm run build # Manual testing: Start dev server and verify quiz functionality npm run serve ``` ### 노트북 테스트 - 노트북에 대한 자동화된 테스트 프레임워크는 없음 - 수동 검증: 모든 셀을 순서대로 실행하여 오류 없는지 확인 - 데이터 파일 접근 가능 여부 및 출력 생성 확인 - 시각화가 올바르게 렌더링되는지 확인 ### 문서 테스트 ```bash # Verify Docsify renders correctly docsify serve # Check for broken links manually by navigating through content # Verify all lesson links work in the rendered documentation ``` ### 코드 품질 검사 ```bash # Vue.js projects (quiz-app and visualization projects) cd quiz-app # or visualization project folder npm run lint # Python notebooks - manual verification recommended # Ensure imports work and cells execute without errors ``` ## 코드 스타일 지침 ### Python (Jupyter 노트북) - Python 코드에 대해 PEP 8 스타일 지침 준수 - 분석 중인 데이터를 설명하는 명확한 변수명 사용 - 코드 셀 앞에 설명이 포함된 Markdown 셀 추가 - 코드 셀은 단일 개념 또는 작업에 집중 - 데이터 조작에는 pandas, 시각화에는 matplotlib 사용 - 일반적인 import 패턴: ```python import pandas as pd import numpy as np import matplotlib.pyplot as plt ``` ### JavaScript/Vue.js - Vue.js 2 스타일 가이드 및 모범 사례 준수 - `quiz-app/package.json`에 ESLint 구성 - Vue 단일 파일 구성 요소 (.vue 파일) 사용 - 컴포넌트 기반 아키텍처 유지 - 변경 사항 커밋 전에 `npm run lint` 실행 ### Markdown 문서화 - 명확한 제목 계층 구조 사용 (# ## ### 등) - 언어 지정자를 포함한 코드 블록 추가 - 이미지에 alt 텍스트 추가 - 관련 강의 및 리소스 링크 추가 - 가독성을 위해 적절한 줄 길이 유지 ### 파일 구성 - 번호가 매겨진 폴더에 강의 내용 저장 (01-defining-data-science 등) - 솔루션은 전용 `solution/` 하위 폴더에 저장 - 번역은 영어 구조를 그대로 따르는 `translations/` 폴더에 저장 - 데이터 파일은 `data/` 또는 강의별 폴더에 저장 ## 빌드 및 배포 ### 퀴즈 애플리케이션 배포 ```bash cd quiz-app # Build production version npm run build # Output is in dist/ folder # Deploy dist/ folder to static hosting (Azure Static Web Apps, Netlify, etc.) ``` ### Azure Static Web Apps 배포 퀴즈 애플리케이션은 Azure Static Web Apps에 배포 가능: 1. Azure Static Web App 리소스 생성 2. GitHub 저장소 연결 3. 빌드 설정 구성: - 앱 위치: `quiz-app` - 출력 위치: `dist` 4. GitHub Actions 워크플로우가 푸시 시 자동 배포 ### 문서 사이트 ```bash # Build PDF from Docsify (optional) npm run convert # Docsify documentation is served directly from markdown files # No build step required for deployment # Deploy repository to static hosting with Docsify ``` ### GitHub Codespaces - 저장소에 개발 컨테이너 구성 포함 - Codespaces가 Python 및 Node.js 환경 자동 설정 - GitHub UI를 통해 저장소를 Codespace에서 열기 - 모든 종속성이 자동으로 설치됨 ## Pull Request 지침 ### 제출 전 ```bash # For Vue.js changes in quiz-app cd quiz-app npm run lint npm run build # Test changes locally npm run serve ``` ### PR 제목 형식 - 명확하고 설명적인 제목 사용 - 형식: `[컴포넌트] 간단한 설명` - 예시: - `[Lesson 7] Fix Python notebook import error` - `[Quiz App] Add German translation` - `[Docs] Update README with new prerequisites` ### 필수 검사 - 모든 코드가 오류 없이 실행되는지 확인 - 노트북이 완전히 실행되는지 검증 - Vue.js 애플리케이션이 성공적으로 빌드되는지 확인 - 문서 링크가 작동하는지 확인 - 수정된 경우 퀴즈 애플리케이션 테스트 - 번역이 일관된 구조를 유지하는지 확인 ### 기여 지침 - 기존 코드 스타일 및 패턴 준수 - 복잡한 로직에 대한 설명 주석 추가 - 관련 문서 업데이트 - 변경 사항이 적용되는 경우 여러 강의 모듈에서 테스트 - CONTRIBUTING.md 파일 검토 ## 추가 참고 사항 ### 사용된 주요 라이브러리 - **pandas**: 데이터 조작 및 분석 - **numpy**: 수치 계산 - **matplotlib**: 데이터 시각화 및 플로팅 - **seaborn**: 통계적 데이터 시각화 (일부 강의) - **scikit-learn**: 머신 러닝 (고급 강의) ### 데이터 파일 작업 - 데이터 파일은 `data/` 폴더 또는 강의별 디렉토리에 위치 - 대부분의 노트북은 상대 경로에서 데이터 파일을 기대 - CSV 파일이 주요 데이터 형식 - 일부 강의는 비관계형 데이터 예제를 위해 JSON 사용 ### 다국어 지원 - GitHub Actions를 통한 40개 이상의 언어 번역 - 번역 워크플로우는 `.github/workflows/co-op-translator.yml`에 있음 - 번역은 언어 코드가 포함된 `translations/` 폴더에 저장 - 퀴즈 번역은 `quiz-app/src/assets/translations/`에 저장 ### 개발 환경 옵션 1. **로컬 개발**: Python, Jupyter, Node.js를 로컬에 설치 2. **GitHub Codespaces**: 클라우드 기반 즉시 개발 환경 3. **VS Code Dev Containers**: 로컬 컨테이너 기반 개발 4. **Binder**: 클라우드에서 노트북 실행 (구성된 경우) ### 강의 내용 지침 - 각 강의는 독립적이지만 이전 개념을 기반으로 구축 - 강의 전 퀴즈는 사전 지식을 테스트 - 강의 후 퀴즈는 학습을 강화 - 과제는 실습 연습 제공 - 스케치노트는 시각적 요약 제공 ### 일반적인 문제 해결 **Jupyter 커널 문제:** ```bash # Ensure correct kernel is installed python -m ipykernel install --user --name=datascience ``` **npm 설치 실패:** ```bash # Clear npm cache and retry npm cache clean --force rm -rf node_modules package-lock.json npm install ``` **노트북에서 Import 오류:** - 필요한 모든 라이브러리가 설치되었는지 확인 - Python 버전 호환성 확인 (Python 3.7+ 권장) - 가상 환경이 활성화되었는지 확인 **Docsify가 로드되지 않음:** - 저장소 루트에서 제공 중인지 확인 - `index.html`이 존재하는지 확인 - 적절한 네트워크 접근 확인 (포트 3000) ### 성능 고려 사항 - 대규모 데이터셋은 노트북에서 로드 시간이 걸릴 수 있음 - 복잡한 플롯의 시각화 렌더링이 느릴 수 있음 - Vue.js 개발 서버는 빠른 반복을 위한 핫 리로드 제공 - 프로덕션 빌드는 최적화되고 축소됨 ### 보안 참고 사항 - 민감한 데이터나 자격 증명은 커밋하지 말 것 - 클라우드 강의에서 API 키는 환경 변수로 사용 - Azure 관련 강의는 Azure 계정 자격 증명이 필요할 수 있음 - 보안 패치를 위해 종속성을 최신 상태로 유지 ## 번역 기여 - GitHub Actions를 통해 자동 번역 관리 - 번역 정확성을 위한 수동 수정 환영 - 기존 번역 폴더 구조 준수 - 퀴즈 링크에 언어 매개변수 추가: `?loc=fr` - 번역된 강의가 올바르게 렌더링되는지 테스트 ## 관련 리소스 - 주요 커리큘럼: https://aka.ms/datascience-beginners - Microsoft Learn: https://docs.microsoft.com/learn/ - 학생 허브: https://docs.microsoft.com/learn/student-hub - 토론 포럼: https://github.com/microsoft/Data-Science-For-Beginners/discussions - 기타 Microsoft 커리큘럼: ML for Beginners, AI for Beginners, Web Dev for Beginners ## 프로젝트 유지 관리 - 콘텐츠를 최신 상태로 유지하기 위한 정기 업데이트 - 커뮤니티 기여 환영 - GitHub에서 문제 추적 - 커리큘럼 유지 관리자가 PR 검토 - 월간 콘텐츠 리뷰 및 업데이트 --- **면책 조항**: 이 문서는 AI 번역 서비스 [Co-op Translator](https://github.com/Azure/co-op-translator)를 사용하여 번역되었습니다. 정확성을 위해 최선을 다하고 있으나, 자동 번역에는 오류나 부정확성이 포함될 수 있습니다. 원본 문서의 원어 버전이 권위 있는 출처로 간주되어야 합니다. 중요한 정보의 경우, 전문적인 인간 번역을 권장합니다. 이 번역 사용으로 인해 발생하는 오해나 잘못된 해석에 대해 당사는 책임을 지지 않습니다.