AGENTS.md

1# AGENTS.md
2 
3## 프로젝트 개요
4 
5이 저장소는 웹 개발 기초를 초보자에게 가르치기 위한 교육용 커리큘럼 저장소입니다. 이 커리큘럼은 Microsoft Cloud Advocates가 개발한 12주 과정의 포괄적인 교육 과정으로, JavaScript, CSS, HTML을 다루는 24개의 실습 중심 수업으로 구성되어 있습니다.
6 
7### 주요 구성 요소
8 
9- **교육 콘텐츠**: 프로젝트 기반 모듈로 조직된 24개의 체계적인 수업
10- **실습 프로젝트**: 테라리움, 타이핑 게임, 브라우저 확장 프로그램, 우주 게임, 은행 앱, 코드 편집기 및 AI 채팅 어시스턴트
11- **인터랙티브 퀴즈**: 각 3문항씩 구성된 48개의 퀴즈 (수업 전/후 평가)
12- **다국어 지원**: GitHub Actions를 통한 50개 이상 언어 자동 번역
13- **기술 스택**: HTML, CSS, JavaScript, Vue.js 3, Vite, Node.js, Express, Python (AI 프로젝트용)
14 
15### 아키텍처
16 
17- 수업 기반 구조의 교육용 저장소
18- 각 수업 폴더는 README, 코드 예제 및 솔루션 포함
19- 독립형 프로젝트가 별도 디렉터리에 있음 (quiz-app, 다양한 수업 프로젝트)
20- GitHub Actions를 이용한 번역 시스템 (co-op-translator)
21- Docsify로 제공되는 문서 및 PDF로도 이용 가능
22 
23## 설정 명령어
24 
25이 저장소는 주로 교육 콘텐츠 소비용입니다. 특정 프로젝트 작업 시:
26 
27### 메인 저장소 설정
28 
29```bash
30git clone https://github.com/microsoft/Web-Dev-For-Beginners.git
31cd Web-Dev-For-Beginners
32```
33 
34### 퀴즈 앱 설정 (Vue 3 + Vite)
35 
36```bash
37cd quiz-app
38npm install
39npm run dev        # 개발 서버 시작
40npm run build      # 프로덕션용 빌드
41npm run lint       # ESLint 실행
42```
43 
44### 은행 프로젝트 API (Node.js + Express)
45 
46```bash
47cd 7-bank-project/api
48npm install
49npm start          # API 서버 시작
50npm run lint       # ESLint 실행
51npm run format     # Prettier로 포맷팅
52```
53 
54### 브라우저 확장 프로젝트
55 
56```bash
57cd 5-browser-extension/solution
58npm install
59# 브라우저별 확장 프로그램 로딩 지침을 따르세요
60```
61 
62### 우주 게임 프로젝트
63 
64```bash
65cd 6-space-game/solution
66npm install
67# 브라우저에서 index.html을 열거나 Live Server를 사용하세요
68```
69 
70### 채팅 프로젝트 (Python 백엔드)
71 
72```bash
73cd 9-chat-project/solution/backend/python
74pip install openai
75# GITHUB_TOKEN 환경 변수를 설정하세요
76python api.py
77```
78 
79## 개발 워크플로우
80 
81### 콘텐츠 기여자를 위한 절차
82 
831. <strong>저장소를 포크</strong>하여 개인 GitHub 계정에 저장
842. **포크한 저장소를 로컬에 클론**
853. **변경을 위한 새 브랜치 생성**
864. 수업 콘텐츠 또는 코드 예제 수정
875. 관련 프로젝트 디렉터리에서 코드 변경 내용 테스트
886. 기여 지침에 따라 풀 리퀘스트 제출
89 
90### 학습자를 위한 절차
91 
921. 저장소 포크 또는 클론
932. 수업 디렉터리를 순서대로 탐색
943. 각 수업의 README 파일 읽기
954. https://ff-quizzes.netlify.app/web/ 에서 수업 전 퀴즈 완료
965. 수업 폴더 내 코드 예제 실습
976. 과제 및 도전 과제 완료
987. 수업 후 퀴즈 풀기
99 
100### 라이브 개발
101 
102- <strong>문서</strong>: 루트에서 `docsify serve` 실행 (포트 3000)
103- **퀴즈 앱**: quiz-app 디렉터리에서 `npm run dev` 실행
104- <strong>프로젝트</strong>: HTML 프로젝트는 VS Code Live Server 확장 사용
105- **API 프로젝트**: 각 API 디렉터리에서 `npm start` 실행
106 
107## 테스트 안내
108 
109### 퀴즈 앱 테스트
110 
111```bash
112cd quiz-app
113npm run lint       # 코드 스타일 문제 확인
114npm run build      # 빌드 성공 여부 확인
115```
116 
117### 은행 API 테스트
118 
119```bash
120cd 7-bank-project/api
121npm run lint       # 코드 스타일 문제 확인
122node server.js     # 서버가 오류 없이 시작하는지 확인
123```
124 
125### 일반 테스트 방법
126 
127- 본 저장소는 종합 자동화 테스트 없이 교육용으로 운영
128- 수동 테스트는 아래에 집중:
129  - 코드 예제가 오류 없이 실행되는지
130  - 문서 내 링크 정상 작동 여부
131  - 프로젝트 빌드 성공 여부
132  - 예제들이 모범 사례 준수 여부
133 
134### 제출 전 점검
135 
136- package.json이 있는 디렉터리에서 `npm run lint` 실행
137- 마크다운 링크 유효성 확인
138- 브라우저 또는 Node.js에서 코드 예제 테스트
139- 번역 파일이 올바른 구조 유지하는지 확인
140 
141## 코드 스타일 가이드
142 
143### JavaScript
144 
145- 최신 ES6+ 문법 사용
146- 프로젝트 내 기본 ESLint 설정 준수
147- 교육 목적의 명확한 변수 및 함수 명칭 사용
148- 학습자 이해를 돕는 주석 추가
149- 설정된 경우 Prettier로 포맷팅
150 
151### HTML/CSS
152 
153- 의미론적 HTML5 태그 사용
154- 반응형 디자인 원칙 준수
155- 명확한 클래스 네이밍 규칙
156- CSS 기법을 설명하는 주석 포함
157 
158### Python
159 
160- PEP 8 스타일 가이드 준수
161- 명확하고 교육적인 코드 예제 제공
162- 학습에 도움이 되는 타입 힌트 활용
163 
164### 마크다운 문서화
165 
166- 명확한 제목 계층 구조
167- 언어 지정된 코드 블록
168- 추가 리소스 링크
169- `images/` 내 스크린샷 및 이미지
170- 접근성을 위한 이미지 대체 텍스트
171 
172### 파일 구성
173 
174- 수업은 번호 순서대로 정렬 (1-getting-started-lessons, 2-js-basics 등)
175- 각 프로젝트는 `solution/` 및 대개 `start/` 또는 `your-work/` 디렉터리 포함
176- 수업 별 `images/` 폴더에 이미지 저장
177- 번역 파일은 `translations/{language-code}/` 구조로 관리
178 
179## 빌드 및 배포
180 
181### 퀴즈 앱 배포 (Azure Static Web Apps)
182 
183quiz-app은 Azure Static Web Apps 배포용으로 구성됨:
184 
185```bash
186cd quiz-app
187npm run build      # dist/ 폴더를 생성합니다
188# main 브랜치에 푸시할 때 GitHub Actions 워크플로우를 통해 배포합니다
189```
190 
191Azure Static Web Apps 구성:
192- **앱 위치**: `/quiz-app`
193- **출력 위치**: `dist`
194- <strong>워크플로우</strong>: `.github/workflows/azure-static-web-apps-ashy-river-0debb7803.yml`
195 
196### 문서 PDF 생성
197 
198```bash
199npm install                    # docsify-to-pdf 설치
200npm run convert               # docs에서 PDF 생성
201```
202 
203### Docsify 문서
204 
205```bash
206npm install -g docsify-cli    # Docsify를 전역 설치하기
207docsify serve                 # localhost:3000에서 서비스하기
208```
209 
210### 프로젝트별 빌드
211 
212각 프로젝트 폴더는 자체 빌드 프로세스를 가질 수 있음:
213- Vue 프로젝트: `npm run build`로 프로덕션 번들 생성
214- 정적 프로젝트: 빌드 단계 없이 파일을 직접 서비스
215 
216## 풀 리퀘스트 가이드라인
217 
218### 제목 형식
219 
220변경 영역을 명확히 나타내는 제목 사용:
221- `[Quiz-app] 수업 X를 위한 새 퀴즈 추가`
222- `[Lesson-3] 테라리움 프로젝트 오타 수정`
223- `[Translation] 5과 스페인어 번역 추가`
224- `[Docs] 설정 지침 업데이트`
225 
226### 필수 점검 사항
227 
228PR 제출 전:
229 
2301. **코드 품질**:
231   - 관련 프로젝트 디렉터리에서 `npm run lint` 실행
232   - 모든 린트 에러 및 경고 수정
233 
2342. **빌드 검증**:
235   - 해당 시 `npm run build` 실행
236   - 빌드 오류 없을 것
237 
2383. **링크 확인**:
239   - 모든 마크다운 링크 테스트
240   - 이미지 참조 확인
241 
2424. **내용 검토**:
243   - 맞춤법 및 문법 교정
244   - 코드 예제 올바르고 교육적임 확인
245   - 번역 내용 원문 의미 유지 확인
246 
247### 기여 요구 사항
248 
249- Microsoft CLA 동의 (첫 PR 시 자동 확인)
250- [Microsoft 오픈 소스 행동 강령](https://opensource.microsoft.com/codeofconduct/) 준수
251- 자세한 지침은 [CONTRIBUTING.md](./CONTRIBUTING.md) 참고
252- PR 설명에 관련 이슈 번호 명시 (해당 시)
253 
254### 검토 절차
255 
256- PR은 유지 관리자 및 커뮤니티가 검토
257- 교육적 명확성 우선 고려
258- 코드 예제는 최신 모범 사례에 부합해야 함
259- 번역은 정확성과 문화적 적합성 검토
260 
261## 번역 시스템
262 
263### 자동 번역
264 
265- GitHub Actions의 co-op-translator 워크플로우 사용
266- 50개 이상의 언어로 자동 번역 수행
267- 원본 파일은 메인 디렉터리에 위치
268- 번역 파일은 `translations/{language-code}/`에 저장
269 
270### 수동 번역 개선 추가
271 
2721. `translations/{language-code}/`에서 파일 찾기
2732. 구조를 유지하며 개선사항 반영
2743. 코드 예제는 정상 작동 유지해야 함
2754. 지역화된 퀴즈 콘텐츠 테스트
276 
277### 번역 메타데이터
278 
279번역 파일에는 메타데이터 헤더 포함:
280```markdown
281<!--
282CO_OP_TRANSLATOR_METADATA:
283{
284  "original_hash": "...",
285  "translation_date": "...",
286  "source_file": "...",
287  "language_code": "..."
288}
289-->
290```
291 
292## 디버깅 및 문제 해결
293 
294### 자주 발생하는 문제
295 
296**퀴즈 앱 실행 실패**:
297- Node.js 버전 확인 (v14 이상 권장)
298- `node_modules` 및 `package-lock.json` 삭제 후 `npm install` 재실행
299- 포트 충돌 검사 (기본 포트: Vite 5173)
300 
301**API 서버 실행 불가**:
302- Node.js 최소 버전 충족 확인 (node >=10)
303- 포트 사용 중인지 확인
304- 모든 의존성 `npm install`로 설치 완료 여부
305 
306**브라우저 확장 프로그램 로드 실패**:
307- manifest.json 형식 확인
308- 브라우저 콘솔 에러 체크
309- 브라우저별 확장 설치 지침 준수
310 
311**Python 채팅 프로젝트 문제**:
312- OpenAI 패키지 설치 확인: `pip install openai`
313- GITHUB_TOKEN 환경 변수 설정 여부
314- GitHub Models 접근 권한 확인
315 
316**Docsify가 문서를 제공하지 않음**:
317- docsify-cli 전역 설치: `npm install -g docsify-cli`
318- 저장소 루트에서 실행
319- `docs/_sidebar.md` 파일 존재 여부
320 
321### 개발 환경 팁
322 
323- HTML 프로젝트에 VS Code Live Server 확장 사용
324- 일관된 포맷팅을 위한 ESLint 및 Prettier 확장 설치
325- 브라우저 개발자 도구로 JavaScript 디버깅
326- Vue 프로젝트는 Vue DevTools 브라우저 확장 설치
327 
328### 성능 고려사항
329 
330- 번역 파일 다수가 존재(50개 이상 언어)해 전체 클론 시 용량 큼
331- 콘텐츠 작업만 할 경우 얕은 복제 사용: `git clone --depth 1`
332- 영어 콘텐츠 작업 시 번역 검색 제외
333- 초기 빌드 과정은 느릴 수 있음 (npm install, Vite 빌드)
334 
335## 보안 고려사항
336 
337### 환경 변수
338 
339- API 키는 저장소에 커밋 금지
340- `.env` 파일 사용 (이미 `.gitignore`에 포함)
341- 필수 환경 변수는 프로젝트 README에 문서화
342 
343### Python 프로젝트
344 
345- 가상 환경 사용 권장: `python -m venv venv`
346- 의존성 최신 상태 유지
347- GitHub 토큰 최소 권한 설정
348 
349### GitHub Models 접근
350 
351- GitHub Models 접근을 위한 개인 액세스 토큰(PAT) 필요
352- 토큰은 환경 변수로 저장
353- 토큰이나 자격 증명 절대 커밋 금지
354 
355## 추가 참고사항
356 
357### 대상 사용자
358 
359- 웹 개발 완전 초보자
360- 학생 및 독학자
361- 교실 수업에서 본 커리큘럼 사용하는 교사
362- 접근성 및 점진적 기술 향상을 고려한 콘텐츠 설계
363 
364### 교육 철학
365 
366- 프로젝트 기반 학습 접근법
367- 빈번한 지식 점검(퀴즈)
368- 실습 코딩 연습
369- 실제 적용 사례 예시
370- 프레임워크 도입 전 기초기에 집중
371 
372### 저장소 유지 관리
373 
374- 활발한 학습자 및 기여자 커뮤니티
375- 의존성과 콘텐츠 정기 업데이트
376- 유지 관리자가 이슈 및 토론 지속 모니터링
377- 번역 업데이트 자동화(GitHub Actions 활용)
378 
379### 관련 리소스
380 
381- [Microsoft Learn 모듈](https://docs.microsoft.com/learn/)
382- [학생 허브 리소스](https://docs.microsoft.com/learn/student-hub/)
383- 학습자를 위한 [GitHub Copilot](https://marketplace.visualstudio.com/items?itemName=GitHub.copilot) 권장
384- 추가 코스: 생성 AI, 데이터 과학, ML, IoT 커리큘럼 제공
385 
386### 개별 프로젝트 작업
387 
388각 프로젝트별 자세한 지침은 다음 README 파일 참조:
389- `quiz-app/README.md` - Vue 3 퀴즈 애플리케이션
390- `7-bank-project/README.md` - 인증 기능이 있는 은행 앱
391- `5-browser-extension/README.md` - 브라우저 확장 개발
392- `6-space-game/README.md` - 캔버스 기반 게임 개발
393- `9-chat-project/README.md` - AI 채팅 어시스턴트 프로젝트
394 
395### 모노레포 구조
396 
397전통적인 모노레포는 아니지만 여러 독립 프로젝트 포함:
398- 각 수업/프로젝트는 독립적임
399- 프로젝트 간 의존성 공유 없음
400- 개별 프로젝트 작업 시 타 프로젝트 영향 없음
401- 전체 커리큘럼 체험 위해 전체 저장소 클론 권장
402 
403---
404 
405<!-- CO-OP TRANSLATOR DISCLAIMER START -->
406**면책 조항**:  
407이 문서는 AI 번역 서비스 [Co-op Translator](https://github.com/Azure/co-op-translator)를 사용하여 번역되었습니다. 정확성을 위해 노력하고 있지만, 자동 번역에는 오류나 부정확성이 포함될 수 있음을 유의하시기 바랍니다. 원본 문서는 해당 언어로 된 원문이 권위 있는 출처로 간주되어야 합니다. 중요 정보의 경우 전문적인 인간 번역을 권장합니다. 이 번역 사용으로 인해 발생하는 모든 오해나 오역에 대해 당사는 책임을 지지 않습니다.
408<!-- CO-OP TRANSLATOR DISCLAIMER END -->