AGENTS.md

1# AGENTS.md
2 
3## プロジェクト概要
4 
5これは初心者にウェブ開発の基礎を教えるための教育用カリキュラムリポジトリです。カリキュラムはMicrosoft Cloud Advocatesによって開発された包括的な12週間のコースで、JavaScript、CSS、HTMLをカバーする24の実践的なレッスンが含まれています。
6 
7### 主な構成要素
8 
9- <strong>教育コンテンツ</strong>: プロジェクトベースのモジュールに整理された24の構造化レッスン
10- <strong>実践プロジェクト</strong>: テラリウム、タイピングゲーム、ブラウザ拡張機能、スペースゲーム、銀行アプリ、コードエディター、AIチャットアシスタント
11- <strong>インタラクティブなクイズ</strong>: 各3問の48のクイズ（レッスン前後の評価）
12- <strong>多言語サポート</strong>: GitHub Actionsによる50以上の言語への自動翻訳
13- <strong>技術スタック</strong>: 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. リポジトリをGitHubアカウントに<strong>フォーク</strong>
842. フォークをローカルに<strong>クローン</strong>
853. 変更用に<strong>新しいブランチを作成</strong>
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- <strong>クイズアプリ</strong>: 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### Markdownドキュメンテーション
165 
166- 明確な見出し階層
167- 言語指定付きコードブロック
168- 追加リソースへのリンク
169- `images/`フォルダ内のスクリーンショット・画像
170- アクセシビリティのための画像のaltテキスト
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- <strong>アプリ場所</strong>: `/quiz-app`
193- <strong>出力場所</strong>: `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. <strong>コード品質</strong>:
231   - 影響を受けるプロジェクトディレクトリで `npm run lint` 実行
232   - すべてのエラー・警告を修正
233 
2342. <strong>ビルド検証</strong>:
235   - 該当すれば `npm run build` 実行
236   - ビルドエラーなしを確認
237 
2383. <strong>リンク検証</strong>:
239   - すべてのマークダウンリンクをテスト
240   - 画像参照が有効か確認
241 
2424. <strong>コンテンツレビュー</strong>:
243   - スペル・文法を校正
244   - コード例が正しく教育的か確認
245   - 翻訳が意味を維持しているか検証
246 
247### コントリビューション要件
248 
249- Microsoft CLAに同意（初回PRで自動チェック）
250- [Microsoft Open Source Code of Conduct](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<strong>クイズアプリが起動しない</strong>:
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<strong>ブラウザ拡張機能が読み込まれない</strong>:
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- 初回実行はビルドや依存インストールのため遅い可能性あり
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- [Student Hub リソース](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` - Canvasベースゲーム開発
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 -->