freeCodeCamp 教學手冊：企業 AI Agent 軟體工程能力培訓與實務

企業 AI Agent 開發工程師的 freeCodeCamp 學習、實作、逆向工程、Framework Upgrade 與軟體工程能力培訓手冊

Documentation Status

• Document Version：v1.1
• Research Date：2026-09-29（v1.1 二次查證）
• freeCodeCamp Repository：github.com/freeCodeCamp/freeCodeCamp（branch main；查證時最後 push 為 2026-09-28）
• Official Website：www.freecodecamp.org
• Contributor Documentation：contribute.freecodecamp.org（原始碼：freeCodeCamp/contribute）
• 查證方式：GitHub REST API 直接讀取 Repository 根目錄、package.json、pnpm-workspace.yaml、sample.env、api/、client/、curriculum/structure/curriculum.json、.github/workflows/；contribute 文件站；官方 README 與 Academic Honesty Policy；freeCodeCamp News / Forum 官方公告（Checkpoint Certifications、Curriculum Restructure、各認證上線公告）；相關 Repository freeCodeCamp/exam-env、freeCodeCamp/socrates
• Target Audience：PM、SA、Software Architect、Senior Developer、Developer、QA、DevOps、AI Agent Developer、新進同仁

[!IMPORTANT] 【資訊時效性】

freeCodeCamp 是非常活躍的開源專案（每天都有 commit、Renovate 會持續更新相依套件），課程也已進入 v9 Full-Stack Developer Curriculum。 本手冊中所有版本號、目錄結構、指令、環境變數，均以 2026-09-29 查閱的官方 Repository 為準。

請以官方 Repository / Documentation 的最新版本為準。

無法從官方來源確認的內容，一律標記為 ⚠️ 需確認目前版本。

[!WARNING] 【Academic Honesty 與 AI 使用】

freeCodeCamp 官方 Academic Honesty Policy 要求學習者承諾：認證專案的程式碼由本人撰寫，除非課程明確允許，否則不得使用 AI 工具產生解答。違反者的認證會被撤銷。

因此本手冊中所有「AI Agent + freeCodeCamp」的做法都遵守一個原則： AI 用來「解釋、提問、檢查、延伸練習」；freeCodeCamp 的認證專案必須由本人完成。 企業內部若要把 freeCodeCamp 認證當作訓練指標，必須把這條規定寫進內部訓練規範。

修訂紀錄

執行摘要（Executive Summary）

背景

企業導入 GitHub Copilot、Claude Code、OpenAI Codex 等 AI Coding Agent 後，產出品質的上限取決於工程師能否判斷、驗證、審查 Agent 的產出。這項判斷力建立在 HTTP、JavaScript、SQL、Git、演算法、測試等基礎能力之上。freeCodeCamp 提供免費、以專案為核心，且有考試把關的基礎訓練，同時也是一個可以合法拿來研究的大型開源 TypeScript Monorepo。

核心結論

建議行動

1. 0–30 天：新進人員完成 Responsive Web Design 的 HTML／CSS 基礎 Module 與本機環境建置（第 7–10 章、Lab 1–3）。
2. 31–90 天：依職能選定第一張目標認證（每張約 300 小時，以 6–9 個月完成為原則，見 37.7 節），並完成第 38 章的 Lab 4–8（AI 協作延伸練習）。
3. 91–180 天：以 freeCodeCamp Repository 為對象，執行 Reverse Engineering 與 Framework Upgrade Playbook（第 40–41 章），再轉用到內部 Legacy 系統。
4. 治理：把「認證專案不使用 AI 產生解答」、「AI 產出必須經人工 Review」、「.env 與公司程式碼不得進入 Prompt」寫進內部訓練規範（第 35、39.4 節）。

關鍵風險

課程與版本快速變動（每季重新查證）、AI 幻覺與過度依賴、教學程式碼不等於 Production 標準、課程內容版權。詳見第 45 章。

目錄（Table of Contents）

• 修訂紀錄
• 執行摘要（Executive Summary）
  • 背景
  • 核心結論
  • 建議行動
  • 關鍵風險
• 0. 閱讀指引
  • 0.1 內容標籤說明
  • 0.2 建議閱讀路徑
  • 0.3 本手冊的核心主張
  • 0.4 名詞對照
• Part A — 認識 freeCodeCamp
  • 1. 文件目的
    • 1.1 為什麼要寫這份手冊
    • 1.2 本手冊回答的問題
    • 1.3 能力轉換模型
    • 1.4 本手冊「不是」什麼
    • 1.5 實務案例與注意事項
  • 2. freeCodeCamp 簡介
    • 2.1 freeCodeCamp 是什麼
    • 2.2 學習模式
    • 2.3 Project-based Learning
    • 2.4 Community 與 Open Source
    • 2.5 實務案例與注意事項
  • 3. freeCodeCamp 生態系
    • 3.1 生態系總覽
    • 3.2 各元件的角色與關係
    • 3.3 組織內相關 Repository（查證日期 2026-09-29）
    • 3.4 實務案例與注意事項
  • 4. GitHub Repository
    • 4.1 基本資訊
    • 4.2 根目錄一覽
    • 4.3 Root scripts 重點
    • 4.4 實務案例與注意事項
  • 5. 系統架構
    • 5.1 Frontend
    • 5.2 Backend
    • 5.3 Data Layer
    • 5.4 Content / Curriculum
    • 5.5 Build / Deployment
    • 5.6 實務案例與注意事項
  • 6. Repository Architecture
    • 6.1 從 Repository 到 Certification
    • 6.2 目錄角色詳解
    • 6.3 Package 相依關係
    • 6.4 用 AI Agent 快速建立 Repository Map
    • 6.5 實務案例與注意事項
• Part B — 安裝與開發環境
  • 7. 安裝
    • 7.1 系統需求
    • 7.2 Windows（WSL2）
    • 7.3 macOS
    • 7.4 Linux（Ubuntu / Debian 為例）
    • 7.5 GitHub Codespaces / Dev Container（替代方案）
    • 7.6 版本驗證清單
    • 7.7 實務案例與注意事項
  • 8. 開發環境
    • 8.1 VS Code 建議設定
    • 8.2 GitHub 帳號準備
    • 8.3 Repository Clone
    • 8.4 實務案例與注意事項
  • 9. Configuration
    • 9.1 建立 .env
    • 9.2 sample.env 分組說明
    • 9.3 開發加速變數
    • 9.4 Configuration 安全原則
    • 9.5 實務案例與注意事項
  • 10. Local Development
    • 10.1 完整流程
    • 10.2 逐步操作
    • 10.3 服務位址
    • 10.4 測試指令
    • 10.5 開發迴圈
    • 10.6 常見問題速查
    • 10.7 實務案例與注意事項
• Part C — 學習平台與學習路徑
  • 11. Learning Platform
    • 11.1 平台組成
    • 11.2 Learning Flow
    • 11.3 平台功能與企業訓練對應
    • 11.4 實務案例與注意事項
  • 12. Curriculum
    • 12.1 名詞階層
    • 12.2 檔案結構
    • 12.3 Superblock JSON 範例
    • 12.4 Challenge Markdown 格式
    • 12.5 課程工具
    • 12.6 目前可見的 Superblock（摘錄，2026-09-29）
    • 12.7 實務案例與注意事項
  • 13. Certification
    • 13.1 認證體系總覽
    • 13.2 Certification Flow
    • 13.3 Exam Environment（考試環境）
    • 13.4 Legacy 認證與 Archive
    • 13.5 Academic Honesty 與 AI
    • 13.6 企業使用認證的原則
    • 13.7 實務案例與注意事項
  • 14. Web Development Learning Path
    • 14.1 路徑總覽
    • 14.2 各階段說明
    • 14.3 實務案例與注意事項
  • 15. Programming Learning Path
    • 15.1 路徑
    • 15.2 各主題對照
    • 15.3 AI Agent 學習模式（Mode 1 — Learning）
    • 15.4 實務案例與注意事項
  • 16. Computer Science Learning Path
    • 16.1 路徑
    • 16.2 課程對照
    • 16.3 為什麼 CS 基礎對 AI Agent 協作特別重要
    • 16.4 實務案例與注意事項
  • 17. Git / GitHub
    • 17.1 學習流程
    • 17.2 核心概念
    • 17.3 日常指令
    • 17.4 Conventional Commits
    • 17.5 實務案例與注意事項
  • 18. Open Source Contribution
    • 18.1 為什麼用 freeCodeCamp 做第一次 Open Source 貢獻
    • 18.2 Contributor Flow
    • 18.3 PR 規則
    • 18.4 First-time Contributor 企業練習方案
    • 18.5 實務案例與注意事項
• Part D — AI Agent 工程能力
  • 19. AI Agent Integration
    • 19.1 AI Agent 的定義
    • 19.2 Developer × freeCodeCamp × AI Agent 工作流
    • 19.3 五種 AI Agent 使用模式
    • 19.4 案例研究：Socrates — 教學型 AI 提示服務的架構
    • 19.5 與企業 AI Coding Tools 的搭配
    • 19.6 AI Agent 不應該做什麼（禁止事項）
    • 19.7 Case 1：使用 freeCodeCamp 學習 JavaScript
    • 19.8 實務注意事項
  • 20. AI-assisted Web Development
    • 20.1 freeCodeCamp 在 AI 開發流程中的角色
    • 20.2 實作流程（SDD 風格）
    • 20.3 Case 2：使用 AI Agent 開發 Web Application
    • 20.4 Case 4：AI Agent 產生 REST API
    • 20.5 實務注意事項
  • 21. AI-assisted Reverse Engineering
    • 21.1 freeCodeCamp 如何建立 Reverse Engineering 基礎能力
    • 21.2 Reverse Engineering 流程
    • 21.3 用 freeCodeCamp Repository 練習 Reverse Engineering
    • 21.4 Case 3：AI Agent 分析 Legacy JavaScript Application
    • 21.5 實務注意事項
  • 22. AI-assisted Framework Upgrade
    • 22.1 freeCodeCamp 的角色
    • 22.2 Framework Upgrade 流程
    • 22.3 從 freeCodeCamp 學升級實務
    • 22.4 Case 5：AI Agent 協助 Framework Upgrade
    • 22.5 實務注意事項
  • 23. AI-assisted Refactoring
    • 23.1 Refactoring 原則
    • 23.2 freeCodeCamp 延伸練習：重構自己的 Lab
    • 23.3 Case 7：AI Agent 協助 Code Review
    • 23.4 實務注意事項
  • 24. AI-assisted Testing
    • 24.1 測試層級
    • 24.2 freeCodeCamp 的 Playwright 慣例
    • 24.3 Case 6：AI Agent 協助建立 Test
    • 24.4 實務注意事項
  • 25. AI-assisted Documentation
    • 25.1 文件類型與 AI 適用性
    • 25.2 向 freeCodeCamp 學文件工程
    • 25.3 Case 8：AI Agent 協助 Repository Documentation
    • 25.4 實務注意事項
  • 26. Context Engineering
    • 26.1 什麼是 Context Engineering
    • 26.2 Context 組裝流程
    • 26.3 以 freeCodeCamp 為例的 Repository Context 檔
    • 26.4 Context 原則
    • 26.5 實務注意事項
  • 27. RAG / Knowledge Base
    • 27.1 freeCodeCamp 作為 AI Agent Knowledge Base
    • 27.2 授權與使用前提（先讀這段）
    • 27.3 Chunking 策略
    • 27.4 Metadata 設計
    • 27.5 簡化的索引腳本範例
    • 27.6 Retrieval 與 Citation 原則
    • 27.7 實務注意事項
  • 28. Spec-Driven Development
    • 28.1 SDD 與 freeCodeCamp
    • 28.2 企業 SDD 流程
    • 28.3 Specification 範本
    • 28.4 實務注意事項
  • 29. TDD / BDD
    • 29.1 學習到 TDD 的橋樑
    • 29.2 TDD 循環
    • 29.3 範例（Vitest）
    • 29.4 BDD（Given-When-Then）
    • 29.5 測試金字塔與 AI Agent
    • 29.6 實務注意事項
• Part E — 安全、治理與維運
  • 30. Security
    • 30.1 OWASP Top 10:2025
    • 30.2 常見漏洞與防護
    • 30.3 從 freeCodeCamp Repository 學供應鏈安全
    • 30.4 AI Agent Security Review Checklist
    • 30.5 AI 功能本身的安全（LLM Application Security）
    • 30.6 實務注意事項
  • 31. Open Source Governance
    • 31.1 License
    • 31.2 企業使用情境與治理
    • 31.3 Dependency / Third-party Component / SBOM
    • 31.4 OSS Governance 流程
    • 31.5 實務注意事項
  • 32. Maintenance
    • 32.1 freeCodeCamp 如何維護自己
    • 32.2 本機維護常用指令
    • 32.3 企業可借鏡的維護實踐
    • 32.4 實務注意事項
  • 33. Upgrade
    • 33.1 通用升級流程
    • 33.2 以 freeCodeCamp 本機環境為例：升級 Fork 到最新上游
    • 33.3 如何利用 AI Agent 協助 freeCodeCamp 升級
    • 33.4 實務注意事項
  • 34. Troubleshooting
    • 34.1 Troubleshooting Guide
    • 34.2 系統化排錯流程
    • 34.3 請 AI Agent 協助排錯的 Prompt
    • 34.4 實務注意事項
• Part F — 企業導入
  • 35. Enterprise Adoption
    • 35.1 定位原則
    • 35.2 建議的企業架構
    • 35.3 企業導入 SOP
    • 35.4 導入 KPI 建議
    • 35.5 實務注意事項
  • 36. Developer Skill Matrix
    • 36.1 企業學習分級
    • 36.2 AI Agent Developer Skill Matrix
    • 36.3 freeCodeCamp 對應課程
    • 36.4 實務注意事項
  • 37. Learning Roadmap
    • 37.1 總覽
    • 37.2 Day 1–30：基礎 Web Development
    • 37.3 Day 31–60：Full Stack Development
    • 37.4 Day 61–90：Software Engineering
    • 37.5 Day 91–120：AI-assisted Development
    • 37.6 Day 121–180：AI Agent + Reverse Engineering + Modernization
    • 37.7 認證時數規劃
    • 37.8 實務注意事項
  • 38. Hands-on Labs
    • 38.1 Lab 總覽
    • 38.2 Lab 1 — HTML Web Page
    • 38.3 Lab 2 — Responsive Web Page
    • 38.4 Lab 3 — JavaScript Application
    • 38.5 Lab 4 — REST API
    • 38.6 Lab 5 — Database Application
    • 38.7 Lab 6 — Full Stack Application
    • 38.8 Lab 7 — Unit Test
    • 38.9 Lab 8 — Refactoring
    • 38.10 Lab 9 — Reverse Engineering（使用 freeCodeCamp Repository）
    • 38.11 Lab 10 — Framework Upgrade
    • 38.12 Lab 11 — Context Engineering
    • 38.13 Lab 12 — RAG Mini Knowledge Base
    • 38.14 實務注意事項
  • 39. AI Agent Prompt Library
    • 39.1 Prompt 結構原則
    • 39.2 Prompt 索引
    • 39.3 Prompts
    • 39.4 AI Agent 工作安全規則
    • 39.5 實務注意事項
  • 40. Reverse Engineering Playbook
    • 40.1 核心原則
    • 40.2 Legacy System Modernization 流程
    • 40.3 階段詳解
    • 40.4 業務規則萃取表範本
    • 40.5 以 freeCodeCamp 練習的建議題目
    • 40.6 實務注意事項
  • 41. Framework Upgrade Playbook
    • 41.1 核心原則
    • 41.2 流程與關卡
    • 41.3 Migration Specification 範本
    • 41.4 freeCodeCamp 參考點
    • 41.5 實務注意事項
  • 42. Enterprise SDLC Integration
    • 42.1 三者分工
    • 42.2 SDLC 各階段對照
    • 42.3 AI 產出的品質關卡
    • 42.4 實務注意事項
  • 43. PM / SA / Architect / Developer 使用指南
    • 43.1 PM
    • 43.2 SA
    • 43.3 Developer
    • 43.4 Architect
    • 43.5 實務注意事項
• Part G — 附錄
  • 44. 常見錯誤
    • 44.1 Do Not Misuse
    • 44.2 實務注意事項
  • 45. 限制與風險
  • 46. FAQ
    • 46.1 學習與認證
    • 46.2 環境與開發
    • 46.3 AI 與企業治理
    • 46.4 手冊維護
  • 47. Checklist
    • 47.1 新進成員 Quick Start Checklist
    • 47.2 AI Agent 任務前 Checklist
    • 47.3 AI 產出 Review Checklist
    • 47.4 手冊品質關卡（Quality Gate）
  • 48. References
    • 48.1 freeCodeCamp Official
    • 48.2 freeCodeCamp 官方公告（課程與認證）
    • 48.3 Platform & Tooling
    • 48.4 Languages & Frameworks
    • 48.5 Security & Governance
    • 48.6 AI

0. 閱讀指引

0.1 內容標籤說明

0.2 建議閱讀路徑

所有角色都建議先讀「執行摘要」，再依上表選讀。主管與訓練單位另外參考 13.6（企業使用認證的原則）與 37.7（認證時數規劃）。

0.3 本手冊的核心主張

freeCodeCamp  ≠  Enterprise SDLC
freeCodeCamp  ≠  AI Coding Agent
freeCodeCamp  ≠  Enterprise Architecture Standard

三者的正確關係：

freeCodeCamp
   │
   │ Developer Knowledge（能力培養）
   ▼
Developer
   │
   │ Engineering Practice（工程實踐）
   ▼
Enterprise SDLC（治理與交付）
   │
   │ AI Assistance（工程協作）
   ▼
AI Coding Agent
   │
   ▼
Enterprise Software Delivery

freeCodeCamp 負責「能力培養」，AI Agent 負責「工程協作」，企業 SDLC 負責「治理與交付」。 三者互相支援，但不可混為一談。

本手冊使用 freeCodeCamp 的方式有兩種，請務必區分：

第二種用法經常被忽略，但對 AI Agent 訓練極有價值：它是一個真實運作中、規模大、測試完整、文件完整、授權寬鬆（BSD-3-Clause） 的 TypeScript 全端專案，非常適合拿來練習「讓 AI Agent 讀懂一個陌生的大型 Repository」。

0.4 名詞對照

1. 文件目的

1.1 為什麼要寫這份手冊

公司正在導入 GitHub Copilot、Claude Code、OpenAI Codex、Gemini 等 AI Coding 工具，以及 MCP、Agent Skills、Spec-Driven Development（SDD）與 AI-assisted SDLC。實務上我們觀察到一個現象：

AI Agent 的產出品質，上限取決於「使用它的工程師」的基礎能力。

一位不懂 HTTP、不懂 SQL、不懂非同步 JavaScript 的工程師，即使拿到最強的 AI Agent，也無法判斷 Agent 產出的程式碼是否正確、安全、可維護。

因此本手冊把 freeCodeCamp 定位成：

AI Agent 開發能力的基礎教育與實作訓練平台。

1.2 本手冊回答的問題

本手冊不只是介紹「如何學 freeCodeCamp」，而是回答：

1. freeCodeCamp 是什麼？它的課程、認證與開源專案如何運作？
2. freeCodeCamp 的 Repository 與系統架構長什麼樣子？如何在本機跑起來？
3. 如何用 freeCodeCamp 建立 Web、Programming、Computer Science 基礎能力？
4. 如何把這些能力轉換成 AI Agent 能協助的工程能力：
   • Web Application Development
   • Reverse Engineering
   • Framework Upgrade
   • Testing
   • Refactoring
   • Documentation
5. 企業如何在 SDLC、Security、OSS Governance 的框架下導入？

1.3 能力轉換模型

flowchart TB
    subgraph FCC["freeCodeCamp 能力來源"]
        M[Mathematics]
        P[Programming]
        CS[Computer Science]
        WD[Web Development]
        BE[Backend Development]
        DB[Database]
        ALG[Algorithms]
        SE[Software Engineering]
    end

    FCC --> DC["Developer Capability<br/>判斷力 + 基礎知識"]
    DC --> AG["AI Coding Agent<br/>工程協作"]

    AG --> U1[Web Application Development]
    AG --> U2[Reverse Engineering]
    AG --> U3[Legacy Modernization]
    AG --> U4[Framework Upgrade]
    AG --> U5[Test Generation]
    AG --> U6[Code Understanding]
    AG --> U7[Documentation]

1.4 本手冊「不是」什麼

1.5 實務案例與注意事項

• 案例：某團隊導入 AI Coding Agent 三個月後，發現 PR 退回率反而上升。Root Cause 是新進工程師無法判斷 Agent 產生的 SQL 是否有 N+1 問題、是否有 Injection 風險。改善方式是要求新進人員先完成 freeCodeCamp 的 Relational Databases 相關課程，再進入 AI 協作開發。
• 注意：本手冊引用的版本號會過期，請在每季度的內部訓練更新時，重新核對第 4–10 章的版本資訊。

2. freeCodeCamp 簡介

2.1 freeCodeCamp 是什麼 [Official]

依官方 README 說明，freeCodeCamp.org 是一個「讓你可以免費學習寫程式的友善社群」，由捐款支持的非營利組織營運，目標是協助成年人轉職進入科技產業。

2.2 學習模式 [Official]

依 contribute 文件，目前核心課程是第 9 版（v9），包含五種學習單元：

每張認證需要完成 5 個必要專案（required projects） 才能參加考試（Exam），通過考試後才能領取認證。考試在官方開源的 Exam Environment 桌面 App 中進行（詳見 13.3 節）。

課程演進時間軸 [Official]：

2.3 Project-based Learning

freeCodeCamp 最重要的教學設計是「做中學」：

Theory Lesson → Workshop（跟著做）→ Lab（自己做）→ Review → Quiz → Certification Project → Exam

這個流程與企業 AI Agent 協作的能力要求高度吻合：

2.4 Community 與 Open Source

• Forum：forum.freecodecamp.org，提問與討論
• Discord：貢獻者與學習者的即時交流
• News：freecodecamp.org/news，大量技術教學文章
• YouTube：免費完整課程影片
• GitHub：整個平台都是開源，歡迎貢獻（詳見第 18 章）

2.5 實務案例與注意事項

• 注意：freeCodeCamp 課程以 JavaScript / Python / SQL 為主，沒有涵蓋企業常用的 Java / Spring Boot / .NET 企業框架（雖有 Foundational C# with Microsoft 認證，屬基礎程度）。Java 團隊應把 freeCodeCamp 定位為 Web 基礎、演算法、SQL、Git 的訓練來源，而不是框架訓練來源。
• 建議 [Engineering Recommendation]：在企業學習平台登記學員的 freeCodeCamp 公開 Profile 連結，用認證頁面作為學習成果證明，不需自行建置學習紀錄系統。

3. freeCodeCamp 生態系

3.1 生態系總覽

freeCodeCamp Ecosystem
├── Learning Platform ........ freecodecamp.org/learn（互動式學習介面）
├── Curriculum ............... Repository 中的 /curriculum（Markdown + JSON 結構）
├── Certifications ........... 6 張 Checkpoint 認證 + Certified Full Stack Developer + 語言認證 + C# 認證
├── Coding Challenges ........ Challenge、Daily Coding Challenge
├── Projects ................. Workshop、Lab、Certification Project
├── Documentation ............ contribute.freecodecamp.org（貢獻者文件）
├── Community ................ Discord、YouTube
├── Forum .................... forum.freecodecamp.org
├── News ..................... freecodecamp.org/news（技術出版）
├── GitHub Repository ........ freeCodeCamp/freeCodeCamp（平台主程式 Monorepo）
├── Contributor Ecosystem .... Issue、PR、Crowdin 翻譯、Moderator
├── Exam Environment ......... exam-env 桌面 App（認證考試）
├── AI Hints ................. Socrates（引導式 AI 提示服務）
└── Mobile / Related Projects  mobile、ui、curriculum-helpers、news、devdocs…

3.2 各元件的角色與關係

flowchart LR
    Learner((Learner)) -->|學習| LP[Learning Platform<br/>freecodecamp.org/learn]
    LP -->|讀取課程內容| CUR[Curriculum<br/>/curriculum]
    LP -->|進度 / 認證| API[freeCodeCamp API<br/>api.freecodecamp.org]
    API --> CERT[Certifications]
    LP -->|卡關時請求提示| SOC[Socrates<br/>AI Hint API]
    Learner -->|認證考試| EXAM[Exam Environment<br/>桌面 App]
    EXAM --> API
    Learner -->|提問| FORUM[Forum]
    Learner -->|閱讀| NEWS[News]
    Learner -->|手機學習| MOB[Mobile App]

    Contributor((Contributor)) -->|閱讀指南| DOCS[contribute.freecodecamp.org]
    Contributor -->|Issue / PR| REPO[GitHub Repository]
    REPO -->|建置| LP
    REPO -->|建置| API
    REPO -->|包含| CUR
    Translator((Translator)) -->|Crowdin| I18N[i18n-curriculum]
    I18N --> CUR

3.3 組織內相關 Repository（查證日期 2026-09-29）

⚠️ Repository 的狀態會改變。引用前請先用 gh repo view freeCodeCamp/<name> 或 GitHub 頁面確認是否 Archived。

3.4 實務案例與注意事項

• 案例：想練習 Flutter 行動開發的團隊，可以用 freeCodeCamp/mobile 作為 Reverse Engineering 的練習對象（contribute 文件有 mobile 本機設定指南）。
• 注意：不要把 chapter 等已封存專案當作最佳實踐範本；封存代表不再維護，相依套件可能已有漏洞。

4. GitHub Repository

4.1 基本資訊 [Official]

4.2 根目錄一覽

freeCodeCamp/
├── .devcontainer/        # Dev Container / GitHub Codespaces 設定
├── .github/              # GitHub Actions workflows、Issue/PR 範本
├── .husky/               # Git hooks（commit 前執行 lint-staged）
├── api/                  # 後端 API（Fastify + Prisma + MongoDB）
├── client/               # 前端學習平台（Gatsby + React + Redux）
├── curriculum/           # 課程內容（Markdown + JSON 結構）
├── docker/               # 本機開發用 docker compose（MongoDB、Mailpit）
├── e2e/                  # Playwright End-to-End 測試
├── packages/             # 共用套件（challenge-builder、challenge-linter、eslint-config、shared）
├── tools/                # 開發工具（challenge 編輯器、parser、seed 腳本…）
├── .nvmrc                # Node.js 版本
├── package.json          # Root scripts（build、develop、test、seed…）
├── pnpm-workspace.yaml   # Workspace 定義與供應鏈安全設定
├── renovate.json         # Renovate 自動更新相依套件
├── knip.jsonc            # Knip：找出未使用的檔案 / 相依套件
├── sample.env            # 環境變數範本
├── tsconfig-base.json    # 共用 TypeScript 設定
└── turbo.json            # Turborepo pipeline 設定

4.3 Root scripts 重點 [Official]

以下依用途分組整理 Root package.json 的 scripts（2026-09-29 查證，共 50 餘個；完整清單請以 jq .scripts package.json 為準）：

表中的 script 都以 pnpm run <script> 執行。

4.4 實務案例與注意事項

• 案例：Architect 在評估公司 Monorepo 工具鏈時，可以直接參考 freeCodeCamp 的 pnpm-workspace.yaml + turbo.json 組合，觀察一個大型開源專案如何管理多個 Package 的建置順序與快取。
• 注意：package.json 中的 scripts 會隨版本變動。在寫內部 SOP 前，請以 cat package.json | jq .scripts 取得最新清單。

5. 系統架構

本章從 Software Architecture 角度分析 freeCodeCamp 學習平台。內容來自原始碼目錄與相依套件分析；正式環境的部署拓撲、資料庫規模等細節並未完整公開，屬 ⚠️ 需確認目前版本。

5.1 Frontend [Official]

Browser execution：學習者在瀏覽器撰寫的程式碼，會由前端在瀏覽器內執行並跑 Challenge 的測試（hints），這是 freeCodeCamp 能大規模免費運作的關鍵設計之一：測試運算發生在使用者端，而不是伺服器端。

client/src 主要目錄：

5.2 Backend [Official]

api/src 主要結構：

Socrates（AI-powered hints）：API 端的 routes/protected/socrates.ts 負責驗證登入、記錄用量（SocratesUsage Model），再以 SOCRATES_API_KEY／SOCRATES_ENDPOINT 呼叫獨立部署的 Socrates 服務。Socrates 本身是另一個 Fastify + TypeScript 專案，收到學習者程式碼、題目說明與失敗的測試後，回傳「只引導、不給答案」的提示。它的架構設計詳見 19.4 節，可以作為企業內部 AI 助教的參考範本。

5.3 Data Layer [Official]

• 資料庫：MongoDB（api/prisma/schema.prisma 的 datasource provider 為 mongodb；本機 MONGOHQ_URL=mongodb://127.0.0.1:27017/freecodecamp）
• Schema 檔案：schema.prisma、exam-environment.prisma、exam-creator.prisma
• 主要 Model（摘錄）：

Curriculum 不存在資料庫：課程內容是 Repository 中的 Markdown 檔案，在 Build Time 被解析並產生前端頁面；使用者進度（完成了哪些 Challenge ID）才存在資料庫。這是一個「Content as Code」的設計。

5.4 Content / Curriculum [Official]

詳見第 12 章。

5.5 Build / Deployment [Official]

正式環境的主機、負載平衡、資料庫叢集等配置 ⚠️ 需確認目前版本；本手冊只描述 Repository 中可見的部分。

5.6 實務案例與注意事項

• 學習點：freeCodeCamp 是「靜態產生前端 + API 後端 + 內容即程式碼」的典型案例。對於需要大量靜態內容、同時需要使用者狀態的系統（例如企業內部教育訓練平台），這個架構值得參考。
• 注意：不要因為 freeCodeCamp 用 MongoDB，就推論企業系統也應該用 MongoDB。技術選型必須依自身需求（交易一致性、報表、既有團隊技能）評估，並寫成 ADR。

6. Repository Architecture

6.1 從 Repository 到 Certification

flowchart TB
    R["Repository<br/>freeCodeCamp/freeCodeCamp"] --> AL["Application Layer<br/>api/ + client/"]
    AL --> LP["Learning Platform<br/>freecodecamp.org/learn"]
    LP --> CUR["Curriculum<br/>curriculum/ Markdown + JSON"]
    CUR --> UL["User Learning<br/>Lesson / Workshop / Lab / Quiz"]
    UL --> CERT["Certification<br/>5 Projects + Exam"]

6.2 目錄角色詳解

6.3 Package 相依關係

flowchart LR
    subgraph packages
        SH[shared]
        ESL[eslint-config]
        CB[challenge-builder]
        CL[challenge-linter]
    end
    subgraph tools
        CP[challenge-parser]
        CHS[challenge-helper-scripts]
        SEED[scripts/seed]
    end
    CUR[curriculum] --> CP
    CUR --> CL
    CLIENT[client] --> CUR
    CLIENT --> CB
    CLIENT --> SH
    API[api] --> SH
    E2E[e2e] --> CLIENT
    E2E --> API
    SEED --> API
    CHS --> CUR
    ESL -. lint .-> CLIENT
    ESL -. lint .-> API

上圖為依 pnpm-workspace.yaml 與目錄職責整理的邏輯相依，精確的套件相依請以各 package.json 的 dependencies 為準（可用 pnpm why <pkg> 或 pnpm -r list --depth 0 查詢）。

6.4 用 AI Agent 快速建立 Repository Map

你是 Senior Software Architect。請閱讀 freeCodeCamp Repository，不要修改任何檔案。

1. 讀取 pnpm-workspace.yaml、turbo.json、根目錄 package.json。
2. 列出每一個 workspace package 的名稱、路徑、主要相依套件、build / test script。
3. 畫出 package 之間的相依關係（Mermaid flowchart）。
4. 對每一個頂層目錄，用一句話說明它在系統中的角色。
5. 標出你「不確定」的推論，並說明需要讀哪個檔案才能確認。

輸出格式：Markdown，包含表格與 Mermaid 圖。

6.5 實務案例與注意事項

• 案例：新進 Senior Developer 的第一週任務，可以設定為「用 AI Agent 產出 freeCodeCamp 的 Repository Map，再由自己逐項驗證」。這同時訓練了 Code Understanding 與「不盲信 AI」的習慣。
• 注意：AI Agent 常把「目錄名稱」直接當成「職責」（例如看到 tools/ 就說是工具）。務必要求它引用實際檔案作為推論依據。

7. 安裝

7.1 系統需求 [Official]

依 contribute 文件「How to Set Up freeCodeCamp Locally」：

官方文件特別提醒：使用與文件列出不同的版本，是安裝失敗最常見的原因。

7.2 Windows（WSL2）

官方要求 Windows 使用者先安裝 WSL2，再在 WSL2 內依照一般流程操作，並建議使用 Windows Terminal，而不是 Command Prompt、Git Bash 或 PowerShell。

# 在 PowerShell（系統管理員）執行
wsl --install
# 重開機後，設定 Ubuntu 使用者帳號
wsl -l -v   # 確認 VERSION 為 2

進入 WSL（Ubuntu）後：

# 更新套件
sudo apt update && sudo apt upgrade -y

# 安裝 Git
sudo apt install -y git

# 安裝 nvm 管理 Node.js（請至 nvm 官方 Repository 確認最新安裝指令）
# 安裝完成後：
nvm install 24
nvm use 24

# 以 corepack 啟用 pnpm（Node.js 內建）
corepack enable
corepack prepare pnpm@10 --activate

node -v && pnpm -v

Docker：在 Windows 安裝 Docker Desktop，並在 Settings → Resources → WSL Integration 啟用你的 Ubuntu distro。

⚠️ 重要：請把 Repository clone 在 WSL 的 Linux 檔案系統（例如 ~/projects/），不要放在 /mnt/c/Users/...。官方 Troubleshooting 指出，放在 Windows 與 WSL 共用的目錄會有效能與穩定性問題。

7.3 macOS

# 安裝 Homebrew（若尚未安裝，請至 brew.sh 取得官方指令）
brew install git

# 使用 nvm 或其他 Node 版本管理工具
nvm install 24
nvm use 24

corepack enable
corepack prepare pnpm@10 --activate

# 安裝 Docker Desktop（或其他相容 Docker Compose 2.x 的方案）
docker compose version

7.4 Linux（Ubuntu / Debian 為例）

sudo apt update
sudo apt install -y git curl build-essential

nvm install 24 && nvm use 24
corepack enable && corepack prepare pnpm@10 --activate

# 安裝 Docker Engine 與 Compose plugin（依 Docker 官方文件）
docker compose version

# 讓目前使用者可以不用 sudo 執行 docker
sudo usermod -aG docker $USER   # 重新登入後生效

7.5 GitHub Codespaces / Dev Container（替代方案）

官方提供 .devcontainer/ 設定，可直接在 GitHub Codespaces 開啟完整開發環境，適合：

• 公司電腦權限受限、無法安裝 Docker / WSL2
• 只需要短時間修改課程內容
• 教育訓練課堂上需要所有學員環境一致

Codespaces 操作要點 [Official]：

7.6 版本驗證清單

git --version
node -v                 # 應為 v24.x
pnpm -v                 # 應為 10.x
docker compose version  # 應為 v2.x

7.7 實務案例與注意事項

• 案例：企業代理伺服器（Proxy）環境下 pnpm install 失敗。官方文件提醒「受限網路或防火牆可能阻擋下載」。解法是設定 HTTPS_PROXY，並向資安單位申請 registry.npmjs.org、github.com、Docker Hub 的白名單。
• 注意：公司若有內部 npm mirror（例如 Nexus / Artifactory），請確認 mirror 同步的套件版本符合 pnpm-lock.yaml，否則會出現 lockfile 不一致錯誤。

8. 開發環境

8.1 VS Code 建議設定 [Engineering Recommendation]

// .vscode/settings.json（個人設定，勿提交到 freeCodeCamp Repository）
{
  "editor.formatOnSave": true,
  "editor.defaultFormatter": "esbenp.prettier-vscode",
  "eslint.workingDirectories": [{ "mode": "auto" }],
  "typescript.tsdk": "node_modules/typescript/lib"
}

8.2 GitHub 帳號準備

1. 建立或使用個人 GitHub 帳號（不要使用公司機密 Repository 所在的帳號去 Fork 公開專案時洩漏公司資訊）
2. 啟用 2FA
3. 設定 SSH Key 或使用 GitHub CLI（gh auth login）
4. 設定 commit 身分：

git config --global user.name "Your Name"
git config --global user.email "you@example.com"

8.3 Repository Clone [Official]

# 1. 在 GitHub 上 Fork：https://github.com/freeCodeCamp/freeCodeCamp/fork

# 2. Clone 自己的 Fork（--depth=1 只抓最新一個 commit，大幅減少下載量）
git clone --depth=1 https://github.com/YOUR_USER_NAME/freeCodeCamp.git
cd freeCodeCamp

# 3. 加入 upstream（官方 Repository），之後用來同步最新程式碼
git remote add upstream https://github.com/freeCodeCamp/freeCodeCamp.git

# 4. 初始化 git submodule（例如 curriculum/i18n-curriculum 翻譯內容）
git submodule update --init

各命令的目的：

git remote -v
# origin    https://github.com/YOUR_USER_NAME/freeCodeCamp.git (fetch)
# origin    https://github.com/YOUR_USER_NAME/freeCodeCamp.git (push)
# upstream  https://github.com/freeCodeCamp/freeCodeCamp.git (fetch)
# upstream  https://github.com/freeCodeCamp/freeCodeCamp.git (push)

git branch
# * main

git status
# On branch main
# nothing to commit, working tree clean

淺層 clone 之後若需要完整歷史（例如做 git log 分析、git blame），可執行 git fetch --unshallow。Reverse Engineering 練習通常需要完整歷史。

8.4 實務案例與注意事項

• 案例：Reverse Engineering 訓練時，學員用 --depth=1 clone，結果 AI Agent 無法用 git log -p 追溯某段程式碼的演進原因。解法：訓練用 clone 改為完整 clone，或事後 git fetch --unshallow。
• 注意：.vscode/、個人 AI Agent 設定檔（例如 CLAUDE.md、.cursorrules）若只是個人使用，請加到 .git/info/exclude，避免誤提交到開源專案。

9. Configuration

9.1 建立 .env [Official]

cp sample.env .env

本機開發時，sample.env 的預設值大多不需要修改即可運作。

9.2 sample.env 分組說明

9.3 開發加速變數 [Official]

contribute 文件說明可以用下列變數只建置 / 測試特定課程，大幅縮短時間：

# 只測試單一 Challenge
FCC_CHALLENGE_ID=646cf6cbca98e258da65c979 pnpm run test-curriculum-content

# 只測試單一 Block（使用 Block 的 dashedName，也就是資料夾名稱）
FCC_BLOCK='basic-html-and-html5' pnpm run test-curriculum-content

# 只測試單一 Superblock
FCC_SUPERBLOCK='responsive-web-design' pnpm run test-curriculum-content

同樣的變數也能套用在 develop，只建置需要的課程頁面，讓 Gatsby 開發伺服器更快啟動：

# 只建置 v9 Responsive Web Design 課程
FCC_SUPERBLOCK='responsive-web-design-v9' pnpm run develop

# 只建置單一 Block
FCC_BLOCK='workshop-curriculum-outline' pnpm run develop

9.4 Configuration 安全原則

1. .env 絕對不可提交（Repository 的 .gitignore 已排除，但仍要自我檢查）
2. 本機假值（例如 STRIPE_PUBLIC_KEY=pk_test_...）只是範例，不可拿到任何可對外存取的環境
3. FCC_ENABLE_DEV_LOGIN_MODE=true 代表不需密碼即可登入，只能用在本機
4. 讓 AI Agent 讀取專案時，要排除 .env（詳見第 26、30 章）

9.5 實務案例與注意事項

• 案例：學員在 Codespaces 中把 port 3000 設為 Public 後忘記關閉 Codespace。官方文件明確提醒：Public port 任何人拿到網址都能存取，而開發登入路由不需要密碼。用完一定要停止 Codespace。
• 企業延伸 [Engineering Recommendation]：freeCodeCamp 的 sample.env 是很好的「環境變數範本」教材：分組清楚、每組有註解、預設值可直接用於本機。企業專案可以仿照此格式建立自己的 .env.example。

10. Local Development

10.1 完整流程

flowchart TB
    A[Fork & Clone] --> S["git submodule update --init"]
    S --> C[cp sample.env .env]
    C --> B[pnpm install]
    B --> D["啟動 MongoDB / Mailpit<br/>docker compose up -d"]
    D --> E["pnpm run seed"]
    E --> F["pnpm run develop"]
    F --> G["開啟瀏覽器<br/>localhost:8000"]
    G --> H["執行測試<br/>pnpm run test"]
    H --> I[修改程式碼]
    I --> J["驗證<br/>lint + test + e2e"]
    J -->|有問題| I

10.2 逐步操作 [Official]

以下假設已完成 8.3 節的 Fork、Clone、upstream 與 submodule 設定。

# Step 1 — 建立環境變數檔
cp sample.env .env

# Step 2 — 安裝相依套件
#（WSL 使用者請先執行：pnpm run playwright:install-build-tools）
pnpm install

# Step 3 — 啟動 MongoDB（與 Mailpit）
docker compose -f docker/docker-compose.yml -f docker/docker-compose.ports.yml up -d

# Step 4 — 建立本機測試資料
pnpm run seed
# 若需要「已認證」的測試使用者（E2E 測試需要）：
# pnpm run seed:certified-user

# Step 5 — 啟動開發伺服器（API + Client）
pnpm run develop

10.3 服務位址

10.4 測試指令

# 全部測試（turbo）
pnpm run test

# 只測 API / Client
pnpm run test-api
pnpm run test-client

# 課程內容測試（第一次需安裝 puppeteer）
pnpm -F=curriculum install-puppeteer
pnpm run test-curriculum-content

# Lint（type-check + eslint + prettier + stylelint）
pnpm run lint

# E2E（需先 seed:certified-user 並啟動 develop）
pnpm run playwright:run
# 或在 e2e 目錄下使用 Playwright UI 模式
npx playwright test --ui

10.5 開發迴圈

修改程式碼
   ↓
儲存（Gatsby / tsx watch 自動重新載入）
   ↓
瀏覽器驗證
   ↓
執行相關單元測試（vitest --watch）
   ↓
pnpm run lint
   ↓
（若影響頁面行為）撰寫 / 執行 Playwright 測試
   ↓
git commit（husky + lint-staged 自動檢查）

10.6 常見問題速查

完整 Troubleshooting 請見第 34 章。

10.7 實務案例與注意事項

• 案例：用 AI Agent 協助環境排錯。學員把 pnpm run develop 的錯誤訊息貼給 AI Agent 時，應同時提供 node -v、pnpm -v、OS、是否 WSL、.env 是否存在（不要貼 .env 內容）。資訊不足時，AI 很容易給出通用但錯誤的建議。
• 注意：git clean -ifdX 會刪除被 .gitignore 忽略的檔案（包括 .env！）。使用互動模式（-i）逐項確認，並先備份 .env。

11. Learning Platform

11.1 平台組成

學習者在 freecodecamp.org/learn 看到的畫面，背後由第 5 章的三層組成：

sequenceDiagram
    autonumber
    actor L as Learner
    participant C as Client（Gatsby/React）
    participant E as 瀏覽器內執行環境
    participant A as API（Fastify）
    participant D as MongoDB

    L->>C: 開啟 Challenge 頁面（Build Time 已產生的靜態頁）
    C->>A: 取得使用者狀態（已登入時）
    A->>D: 讀取 user / 進度
    D-->>A: 進度資料
    A-->>C: 使用者狀態
    L->>C: 在 Monaco Editor 撰寫程式碼
    L->>C: 點擊「Check your code」
    C->>E: 執行學習者程式碼 + hints 測試
    E-->>C: 測試結果（通過 / 失敗訊息）
    C->>A: 提交完成紀錄（通過時）
    A->>D: 更新 completedChallenges
    A-->>C: 更新後的進度

上圖為依原始碼職責整理的簡化流程；實際 API 端點與欄位名稱請以 api/src/routes/ 與 api/src/schemas/ 為準。

11.2 Learning Flow

flowchart LR
    S[選擇 Superblock / 認證] --> CH[Chapter]
    CH --> MO[Module]
    MO --> LE[Theory Lesson]
    LE --> WS[Workshop]
    WS --> LAB[Lab]
    LAB --> RV[Review]
    RV --> QZ[Quiz]
    QZ -->|下一個 Module| MO
    QZ -->|全部完成| CP[Certification Projects x5]
    CP --> EX[Exam]
    EX --> CERT[Claim Certification]

11.3 平台功能與企業訓練對應

11.4 實務案例與注意事項

• 案例：某部門將每週五下午 30 分鐘設為「Daily Challenge Dojo」，由一人投影解題，其他人用 AI Agent 提出不同解法並比較時間 / 空間複雜度。重點是讓 AI 當討論對象，而不是答案產生器。
• 注意：課程介面、路徑與課程名稱會隨版本更新（例如 v9 課程網址帶有 -v9 後綴）。內部文件引用課程時，請附上查詢日期。

12. Curriculum

12.1 名詞階層 [Official]

依 contribute 文件「Curriculum File Structure」：

Certification  使用者領取的證書（與 Superblock 名稱分開）
Superblock     最上層課程集合（部分對應認證，部分是課程或額外練習）
  └─ Chapter      Module 的分組（v9 新課程使用；舊課程為扁平 Block 清單）
      └─ Module     Block 的分組
          └─ Block      一組 Challenge（例如某 Workshop、某 Lab）
              └─ Challenge  單一課程單元（一個 Markdown 檔）

12.2 檔案結構

curriculum/
├─ challenges/
│  └─ english/
│     ├─ blocks/
│     │  └─ <block>/
│     │     └─ <challenge>.md
│     └─ certifications/
│        └─ <certification>.yml
├─ i18n-curriculum/          # git submodule，翻譯內容
├─ structure/
│  ├─ curriculum.json        # 所有 superblocks 與 certifications 清單
│  ├─ superblocks/<superblock>.json
│  └─ blocks/<block>.json    # Block metadata 與 Challenge 順序
├─ schema/                   # 課程資料的驗證 schema
├─ dictionaries/
└─ src/

12.3 Superblock JSON 範例

簡單型（只有 blocks）：

{
  "blocks": ["basic-html-and-html5", "basic-css", "applied-visual-design"]
}

v9 型（Chapter → Module → Block）：

{
  "chapters": [
    {
      "dashedName": "html",
      "modules": [
        {
          "dashedName": "basic-html",
          "blocks": ["lecture-welcome-to-freecodecamp", "lab-debug-camperbots-profile-page"]
        }
      ]
    }
  ]
}

Module / Chapter 可帶的特殊屬性：moduleType: "cert-project"、moduleType: "review"、comingSoon: true、chapterType: "exam"。

12.4 Challenge Markdown 格式 [Official]

每一個 Challenge 是一個 Markdown 檔，以特殊標題切分區段（以下為依官方範本簡化的示意）：

---
id: 5f0000000000000000000001
title: Build a Greeting Function
challengeType: 1
---

# --description--

Create a function `greet` that returns a greeting.

# --hints--

`greet('Ada')` should return `Hello, Ada!`.

```js
assert.strictEqual(greet('Ada'), 'Hello, Ada!');
```

# --seed--

## --seed-contents--

```js
function greet(name) {

}
```

# --solutions--

```js
function greet(name) {
  return `Hello, ${name}!`;
}
```

企業觀點：--hints-- + --solutions-- 的設計就是「規格即測試（Specification as Test）」。每一條 hint 是一條可驗證的 Acceptance Criteria，而 solutions 保證這些測試「可以被滿足」。這正是 SDD / TDD 的核心精神（詳見第 28、29 章）。

12.5 課程工具 [Official]

# 以互動式 CLI 建立新的 lecture / workshop / lab / review / quiz
pnpm run create-new-project

# 在 Block 內新增 / 插入 / 刪除 / 重新排序 Challenge（在 Block 目錄下執行，詳見 contribute 文件）
pnpm run create-next-challenge
pnpm run insert-challenge
pnpm run delete-challenge
pnpm run update-challenge-order

12.6 目前可見的 Superblock（摘錄，2026-09-29）

curriculum/structure/curriculum.json 目前列出約 103 個 Superblock 與約 30 個 Certification 定義。依用途分類如下：

⚠️ Superblock 是否已上線、是否為 Beta，請以 freecodecamp.org/learn 實際顯示為準；Repository 中存在的檔案可能是 comingSoon 或受 SHOW_UPCOMING_CHANGES 控制的未上線內容。

12.7 實務案例與注意事項

• 案例：AI Agent Developer 訓練時，先閱讀 learn-rag-mcp-fundamentals 課程建立 RAG / MCP 基礎概念，再進入第 27 章的企業 RAG 實作。
• 注意：舊版（Legacy）認證與 v9 認證並存。2025-11-13 課程重組後，舊課程集中在 freecodecamp.org/learn/archive。企業訓練規劃請一律以 v9 為準，避免學員走到舊路徑。
• 注意：主題式 Superblock（例如 css-flexbox、introduction-to-asynchronous-javascript）的內容通常與 v9 認證課程重複，是同一批課程的另一種入口。安排訓練時請避免讓學員重複上同樣的內容。⚠️ 各主題課與認證課程的實際對應，請以官方課程頁為準。

13. Certification

13.1 認證體系總覽 [Official]

2025 年 9 月起，freeCodeCamp 把原本約 1,800 小時的單一 Full-Stack 路徑拆成 6 張 Checkpoint Certification，每張約 300 小時，並以 Capstone 專案 + 綜合考試 作為最終的 Certified Full Stack Developer 認證：

Certified Full Stack Developer（Capstone 專案 + 綜合考試）
  ▲ 需先取得以下 6 張 Checkpoint Certification
  ├─ 1. Responsive Web Design
  ├─ 2. JavaScript
  ├─ 3. Front End Development Libraries
  ├─ 4. Python
  ├─ 5. Relational Databases
  └─ 6. Back End Development and APIs

「核心內容」欄是依課程名稱與 Superblock 內容整理的概述，詳細 Module 以官方課程頁為準。

其他認證 [Official]：

2026 路線圖（已宣布、尚未全面上線） ⚠️ 需確認目前版本：

• 低階程式設計與高效能運算認證：以 C／C++ 實作編譯器與搜尋引擎
• 擴充 Python Machine Learning 內容

企業若想用這些新課程做訓練規劃，請先到 freecodecamp.org/learn 確認已經開放，不要只依公告排課。

13.2 Certification Flow

flowchart TB
    START([選擇 Checkpoint 認證]) --> MODS["完成各 Module<br/>Lesson / Workshop / Lab / Review / Quiz"]
    MODS --> P5{"5 個必要專案<br/>皆完成？"}
    P5 -- 否 --> MODS
    P5 -- 是 --> APP["下載並登入<br/>Exam Environment App"]
    APP --> EXAM["參加認證考試<br/>（約 50 題）"]
    EXAM --> PASS{通過？}
    PASS -- 否 --> REVIEW[複習後重考] --> EXAM
    PASS -- 是 --> CLAIM[Claim Certification]
    CLAIM --> VERIFIED[可驗證的認證連結]
    VERIFIED --> SIX{"6 張 Checkpoint<br/>皆取得？"}
    SIX -- 是 --> CAP["Capstone 專案<br/>資深開發者 Code Review"]
    CAP --> FINAL[綜合考試]
    FINAL --> FSD([Certified Full Stack Developer])
    VERIFIED -. 發現違規 .-> REVOKE["撤銷認證<br/>Academic Honesty Policy"]
    EXAM -. 異常行為 .-> HUMAN[標記送人工審查]

13.3 Exam Environment（考試環境） [Official]

企業觀點 [Engineering Recommendation]：Exam Environment 本身就是一個「在隱私、公平與可用性之間取捨」的系統設計案例。Architect 可以閱讀 exam-env 與 api/src/exam-environment/，練習分析「桌面用戶端 + API + 人工審查」的信任邊界（見第 21 章 Reverse Engineering）。

13.4 Legacy 認證與 Archive [Official]

企業處理原則 [Engineering Recommendation]：

• 已持有 Legacy 認證的同仁：人資系統照常登錄，但在 2027 年底前檢視是否要升級到新版。
• 新進同仁：一律走 v9 Checkpoint 路徑。
• 內部文件中的課程連結：全面換成新版路徑，舊連結改指向 Archive。

13.5 Academic Honesty 與 AI [Official]

官方 Academic Honesty Policy 的重點：

1. 專案程式碼必須 100% 由本人撰寫（開源函式庫與清楚標註來源的片段除外）
2. 除非課程明確允許，不得使用 AI 工具產生解答
3. 發現抄襲時，認證會被撤銷

平台內建的 AI 提示（Socrates）與政策不衝突：Socrates 的設計目標是「引導而不給答案」，回傳的是提問式提示（例如「你的函式沒有 return 時會回傳什麼？」），是平台允許的學習輔助。相對地，把題目丟給外部 AI 工具直接產生解答，就違反了這項政策。

13.6 企業使用認證的原則 [Engineering Recommendation]

13.7 實務案例與注意事項

• 案例：內部訓練辦法中明定「freeCodeCamp 認證專案禁止使用 AI 產生程式碼；認證取得後的延伸 Lab 則必須使用 AI Agent 完成，並提交 Prompt 紀錄與人工審查紀錄」。這樣同時保護了認證的公信力，也訓練了 AI 協作能力。
• 案例：公司電腦若限制安裝軟體，Exam Environment App 可能無法安裝。訓練單位應事先向 IT 申請白名單，或允許學員使用個人電腦應考。
• 注意：認證名稱與組成可能調整（例如 v9 與舊版並存、新認證陸續上線）。人資或訓練單位登錄認證時，請保存認證頁面連結而非只記名稱。

14. Web Development Learning Path

14.1 路徑總覽

flowchart TB
    H[HTML] --> C[CSS]
    C --> R[Responsive Web Design]
    R --> JS[JavaScript]
    JS --> DS[Data Structures]
    DS --> FL[Frontend Libraries]
    FL --> BE[Backend Development]
    BE --> API[APIs]
    API --> DB[Database]
    DB --> FS[Full Stack]
    FS --> SE[Software Engineering]

14.2 各階段說明

Stage 1 — HTML

Stage 2 — CSS

Stage 3 — Responsive Web Design

Stage 4 — JavaScript

// 常見錯誤：忘記 await，拿到的是 Promise 而不是資料
async function loadUser(id) {
  const res = fetch(`/api/users/${id}`);   // ❌ 少了 await
  return res.json();                       // TypeError: res.json is not a function
}

// 正確
async function loadUserFixed(id) {
  const res = await fetch(`/api/users/${id}`);
  if (!res.ok) throw new Error(`HTTP ${res.status}`);
  return res.json();
}

Stage 5 — Data Structures

Stage 6 — Frontend Libraries

Stage 7–9 — Backend / APIs / Database

// ❌ SQL Injection 風險：字串串接
const rows = await db.query(`SELECT * FROM users WHERE email = '${email}'`);

// ✅ Parameterized Query（以 node-postgres 為例）
const rows2 = await db.query('SELECT * FROM users WHERE email = $1', [email]);

Stage 10 — Full Stack

Stage 11 — Software Engineering

freeCodeCamp 課程涵蓋較少，需由企業補足：Architecture、Design Pattern、Testing Strategy、CI/CD、Code Review、Security、Observability。建議搭配本手冊第 19–34 章與公司內部規範。

14.3 實務案例與注意事項

• 案例：Java 後端工程師轉前端時，直接從 Stage 4 開始，並用 AI Agent 做「Java ↔ JavaScript 概念對照」（例如 Java CompletableFuture 對照 JS Promise），可顯著縮短學習時間。
• 注意：freeCodeCamp 後端課程以 Node.js 為主；企業使用 Spring Boot 的團隊，應把 Stage 7–9 的重點放在 HTTP、REST 語意、SQL 這些可跨語言的概念。

15. Programming Learning Path

15.1 路徑

Computer Basics → Bash → JavaScript 或 Python 基礎 → OOP → Functional Programming
→ Error Handling → Debugging → Regex → Testing 概念 → TypeScript（企業補充）

15.2 各主題對照

15.3 AI Agent 學習模式（Mode 1 — Learning）

我正在學 freeCodeCamp 的「<課程名稱>」。
請不要直接給我答案。
1. 用 3 句話解釋這個概念。
2. 給我一個與課程不同的小例子。
3. 問我 2 個問題確認我理解了。
4. 如果我答錯，指出錯在哪裡，但仍然不要給完整解答。

15.4 實務案例與注意事項

• 案例：新人使用上面的 Learning Prompt 學習 closure，AI 給出一個「計數器工廠」例子，並提問「兩個計數器會共用同一個 count 嗎？」，強迫學員思考，效果比直接看答案好。
• 注意：AI 解釋可能過度簡化或錯誤。遇到有疑慮的說法，一律回 MDN 或語言官方文件查證。

16. Computer Science Learning Path

16.1 路徑

Mathematics（Algebra / Precalculus）
   ↓
Algorithms & Data Structures 入門
   ↓
Recursion
   ↓
Sorting / Searching
   ↓
Graphs & Trees
   ↓
Dynamic Programming
   ↓
Coding Interview Prep / Project Euler / Rosetta Code

16.2 課程對照

16.3 為什麼 CS 基礎對 AI Agent 協作特別重要

# 圖的 BFS：Reverse Engineering 時「找出某個函式影響哪些模組」的基本演算法
from collections import deque

def impacted_modules(call_graph: dict[str, list[str]], start: str) -> set[str]:
    """call_graph: 被呼叫者 -> 呼叫者清單；回傳所有會受 start 變更影響的模組。"""
    seen, queue = {start}, deque([start])
    while queue:
        node = queue.popleft()
        for caller in call_graph.get(node, []):
            if caller not in seen:
                seen.add(caller)
                queue.append(caller)
    return seen - {start}

16.4 實務案例與注意事項

• 案例：AI Agent 在一個報表功能中產生了 O(n²) 的巢狀迴圈比對，測試資料 100 筆時沒問題，正式資料 50 萬筆時逾時。具備 Big-O 基礎的 Reviewer 在 Code Review 就能攔下。
• 注意：演算法練習的目的是建立判斷力，不是背題目。不要讓 AI 替你解 Project Euler，否則失去練習意義。

17. Git / GitHub

17.1 學習流程

flowchart LR
    L[Learn] --> P[Practice]
    P --> G[Git]
    G --> GH[GitHub]
    GH --> I[Issue]
    I --> B[Branch]
    B --> C[Commit]
    C --> PR[Pull Request]
    PR --> R[Review]
    R --> M[Merge]

freeCodeCamp 相關課程：introduction-to-git-and-github、Relational Databases 認證中的 Git 練習。

17.2 核心概念

17.3 日常指令

# 同步 upstream 最新 main（main 分支不應有自己的 commit）
git fetch upstream
git checkout main
git reset --hard upstream/main          # ⚠️ 會丟棄本地 main 上的變更
git push origin main --force-with-lease # 讓 Fork 的 main 與 upstream 一致

# 建立功能分支
git checkout -b fix/typo-in-css-grid-lesson

# 提交（遵守 Conventional Commits）
git add <files>
git commit -m "fix(curriculum): correct typo in css grid lesson"

# 推送並建立 PR
git push origin fix/typo-in-css-grid-lesson
gh pr create --repo freeCodeCamp/freeCodeCamp --base main --fill

17.4 Conventional Commits [Official]

freeCodeCamp 的 PR 標題與 commit 採用 Conventional Commits：

<type>([optional scope(s)]): <description>

常見 Scope：curriculum、a11y、i18n、api、client、tools。

官方範例：

fix(a11y): improved search bar contrast
feat: add more tests to HTML and CSS challenges
fix(api,client): prevent CORS errors on form submission
docs(i18n): fix links to be relative instead of absolute

17.5 實務案例與注意事項

• 案例：公司內部直接沿用 freeCodeCamp 的 type / scope 表格作為 Commit 規範範本，只把 scope 換成公司系統模組名稱。
• 注意：git reset --hard、git push --force 是破壞性操作。AI Agent 執行這類指令前必須經人工確認（見第 39.4 節安全規則）。

18. Open Source Contribution

18.1 為什麼用 freeCodeCamp 做第一次 Open Source 貢獻

18.2 Contributor Flow

flowchart TB
    A[閱讀 contribute 文件] --> B["找 Issue<br/>確認無人處理"]
    B --> C[Fork]
    C --> D[Clone + upstream]
    D --> E[建立 Branch]
    E --> F[修改]
    F --> G["本機測試<br/>lint / test / e2e"]
    G --> H["Commit<br/>Conventional Commits"]
    H --> I[Push 到自己的 Fork]
    I --> J["開 PR 到 upstream main<br/>填寫 Checklist、Closes #issue"]
    J --> K[CI 檢查]
    K --> L[Moderator Review]
    L -->|要求修改| F
    L -->|核准| M[Merge]

18.3 PR 規則 [Official]

1. 不要直接在 GitHub 網頁上編輯檔案送 PR
2. PR 標題遵守 Conventional Commits
3. 確實遵循 PR Checklist，而非只是打勾
4. 用正確方式連結 Issue：在描述最後寫 Closes #123
5. 不要 @mention 維護者，請耐心等待；有問題請到 Forum 的 freeCodeCamp Community 分類或 Discord
6. 不要在自己的 main 分支上工作
7. 只修改英文課程；翻譯請透過 Crowdin
8. 若改動影響頁面行為，要附上對應的 Playwright 測試
9. UI 變更要附截圖
10. 說明是否已在本機測試

18.4 First-time Contributor 企業練習方案 [Engineering Recommendation]

公司政策提醒：

• 貢獻開源前，請確認公司是否有「員工參與開源」政策（著作權歸屬、是否需要主管核准、是否可用上班時間）
• 絕對不可把公司程式碼、內部網址、客戶資料放進開源 PR 或 Issue
• 若使用 AI Agent 協助撰寫 PR，必須由本人完全理解並負責內容；freeCodeCamp 有 github-spam.yml、github-pr-guidelines.yml 等 workflow 處理不符規範的 PR（⚠️ 對 AI 產出內容的具體規範請以最新 contribute 文件為準）

18.5 實務案例與注意事項

• 案例：新人第一個 PR 是修正課程中的一個錯字，看似簡單，但過程中學會了 Fork、upstream 同步、Conventional Commits、CI 檢查失敗處理、回應 Reviewer，這些都是企業日常流程。
• 注意：開源維護者時間寶貴。不要為了「完成訓練 KPI」大量提交低品質 PR。企業應把指標設為「PR 被 Merge」或「學到的經驗報告」，而不是「PR 數量」。

19. AI Agent Integration

本章是全手冊最重要的章節之一。

19.1 AI Agent 的定義

本手冊不把 AI Agent 定義為「幫我寫程式的聊天機器人」，而定義為：

具備程式碼理解、規劃、實作、測試、驗證與重構能力的 Software Engineering Agent。

19.2 Developer × freeCodeCamp × AI Agent 工作流

flowchart TB
    DEV[Developer] --> K["freeCodeCamp Knowledge<br/>Web / Programming / CS / SQL / Git"]
    K --> AG[AI Agent]
    AG --> RU[Repository Understanding]
    RU --> PL[Plan]
    PL -->|人工核准| IM[Implementation]
    IM --> TE[Test]
    TE --> RV["Review<br/>人工 + AI 輔助"]
    RV --> DOC[Documentation]
    RV -->|退回| PL

關鍵：Developer 的知識是整個流程的「驗證者」。沒有這層知識，Plan 的核准與 Review 都會流於形式。

19.3 五種 AI Agent 使用模式

Mode 4 — Reverse Engineering 流程

Legacy Application → AI Agent → Repository Analysis → Code Understanding
→ Business Logic Extraction → Architecture Reconstruction → Specification → Test

Mode 5 — Framework Upgrade 流程

Old Framework → Dependency Analysis → API Analysis → Breaking Changes
→ Migration Plan → Code Transformation → Test → Regression Test

19.4 案例研究：Socrates — 教學型 AI 提示服務的架構 [Official]

freeCodeCamp 的 Socrates 是一個很好的「企業內部 AI 助教」參考範本。它要解決的問題和企業訓練一樣：學員卡關時要給幫助，但不能直接給答案。

19.4.1 架構

sequenceDiagram
    autonumber
    actor L as Learner
    participant C as Client（瀏覽器）
    participant A as freeCodeCamp API<br/>routes/protected/socrates.ts
    participant S as Socrates 服務<br/>Fastify + TypeScript
    participant R as Redis<br/>Token Bucket
    participant G as LLM 推論服務<br/>（Groq）

    L->>C: 測試失敗，點選「取得提示」
    C->>A: 程式碼 + 題目 + 測試結果（需登入）
    A->>A: 驗證身分、記錄用量（SocratesUsage）
    A->>S: POST /hint（X-API-Key）
    S->>R: 檢查使用者與全域速率限制
    R-->>S: 允許／拒絕
    S->>S: 依挑戰類型（HTML／CSS／JS／Python）組 System Prompt
    S->>G: 呼叫模型（Circuit Breaker 保護）
    G-->>S: 模型輸出
    S->>S: 輸出消毒：只保留不含屬性的 <code> 標籤
    S-->>A: hint + model_used
    A-->>C: 引導式提示

19.4.2 關鍵設計決策

⚠️ 預設模型、推論供應商與端點都可能變更，請以 Socrates Repository 最新的 README 為準。

19.4.3 練習題 [Engineering Recommendation]

以 Socrates 為範本，替公司內部的 Java 訓練平台設計一個「AI 助教」服務，並寫成 ADR：

1. 輸入契約（哪些欄位可以送、哪些禁止，例如客戶資料）
2. Prompt 管理方式（版本控管、依課程切換）
3. 防止直接給答案的機制（Prompt 規則 + 輸出檢查）
4. 速率限制與成本上限
5. 輸出消毒與前端呈現方式
6. 模型與供應商選擇（資料落地、合規要求）

19.5 與企業 AI Coding Tools 的搭配

⚠️ 本表只描述「在 freeCodeCamp 學習 / 練習情境下的建議用途」，不是工具能力評比。各工具功能變化快速，請以各廠商官方文件與公司核准清單為準。

19.6 AI Agent 不應該做什麼（禁止事項）

19.7 Case 1：使用 freeCodeCamp 學習 JavaScript

我是 Java 工程師，正在學 freeCodeCamp JavaScript v9 的非同步章節。
請用 Java 的 CompletableFuture 對照說明 JavaScript 的 Promise 與 async/await。
規則：
1. 只給概念對照與小例子，不要解 freeCodeCamp 的 Lab 題目。
2. 最後出 3 題「這段程式碼會印出什麼」的題目讓我作答。
3. 標示出 Java 與 JavaScript 行為「不同」的地方（例如單執行緒 Event Loop）。

19.8 實務注意事項

• AI Agent 的能力會隨版本改變，但「先理解、再規劃、後修改、必驗證」的原則不會變。
• 讓 Agent 在 freeCodeCamp 這類公開 Repository 上練習，不會有公司機密外洩風險，是導入初期最安全的練習場。

20. AI-assisted Web Development

20.1 freeCodeCamp 在 AI 開發流程中的角色

flowchart TB
    R[Requirement] --> AG[AI Agent]
    AG --> KR["Knowledge Retrieval<br/>freeCodeCamp 課程 / 官方文件 / 公司規範"]
    KR --> AR[Architecture]
    AR --> IM[Implementation]
    IM --> UT[Unit Test]
    UT --> IT[Integration Test]
    IT --> CR[Code Review]
    CR --> DP[Deployment]

20.2 實作流程（SDD 風格）

1. 撰寫需求（User Stories + Acceptance Criteria）
2. 讓 Agent 產生 Specification，人工確認
3. 讓 Agent 產生 Plan（檔案清單、步驟、測試策略），人工核准
4. Agent 先寫測試（依 Acceptance Criteria）
5. Agent 實作直到測試通過
6. 執行 lint / type-check / test
7. 人工 Code Review（安全、效能、可維護性）
8. 合併

20.3 Case 2：使用 AI Agent 開發 Web Application

你是 Senior Full-Stack Engineer。
需求：
- 使用者可以看到讀書會場次列表（名稱、日期、剩餘名額）
- 使用者可以報名，名額滿時顯示錯誤
- 同一使用者不可重複報名同一場次

請依序執行，每一步完成後停下來等我確認：
1. 產生 spec.md：功能、API 規格（method / path / request / response / error）、資料表設計、Acceptance Criteria（Given-When-Then）
2. 產生 plan.md：要新增 / 修改的檔案、實作順序、測試策略
3. 先寫測試，再寫實作
4. 執行 lint、type-check、test，回報結果

限制：
- 使用 Parameterized Query，禁止字串串接 SQL
- 「名額檢查 + 新增報名」必須在同一個 Transaction 中完成，避免超賣
- 不新增 plan.md 以外的相依套件

20.4 Case 4：AI Agent 產生 REST API

參考 freeCodeCamp api/ 的模式：每個 route 用 TypeBox 定義 request / response schema，並附 .test.ts。
請在我們的專案中新增 GET /api/v1/users/{userId}/progress：
1. 先閱讀 src/routes/ 下現有的 2 個 route 與其測試，總結我們的慣例。
2. 依慣例產生 route、schema、service、測試。
3. 授權規則：一般使用者只能查自己的 userId；管理者可查任何人。
4. 錯誤：401 未登入、403 無權限、404 使用者不存在。
5. 回應需分頁（page、pageSize，pageSize 上限 100）。
不要修改其他 route。完成後列出所有變更檔案。

學習點：freeCodeCamp 的 api/src/routes/protected/ 與 public/ 分離、每個 route 都有同名 .test.ts、以 TypeBox schema 產生 Swagger 文件，這些都是值得參考的 API 工程實踐（但要依公司技術棧轉換，不是照抄）。

20.5 實務注意事項

• AI 產生的 Web 程式碼最常漏掉的是：授權檢查、輸入驗證、錯誤處理、併發控制。Code Review Checklist 要特別列出。
• 前端表單驗證只是使用者體驗，後端必須重新驗證。

21. AI-assisted Reverse Engineering

21.1 freeCodeCamp 如何建立 Reverse Engineering 基礎能力

21.2 Reverse Engineering 流程

flowchart TB
    SS[Source System] --> AG[AI Agent]
    AG --> SA["Static Analysis<br/>目錄、進入點、設定檔"]
    SA --> DA["Dependency Analysis<br/>package.json / pom.xml / imports"]
    DA --> CF["Call Flow<br/>Route → Controller → Service → Repository"]
    CF --> BR["Business Rule<br/>條件判斷、計算、驗證"]
    BR --> DM["Data Model<br/>Schema、Entity、關聯"]
    DM --> API["API<br/>端點、Request / Response"]
    API --> AR[Architecture]
    AR --> SP[Specification]
    SP --> HV{人工驗證}
    HV -->|不正確| SA
    HV -->|正確| T[Characterization Test]

21.3 用 freeCodeCamp Repository 練習 Reverse Engineering

freeCodeCamp 是理想的練習對象：真實、大型、有測試（可以驗證你的推論）、有文件（可以對答案）。

21.3.1 練習題：萃取「認證申請」的業務規則

你是 Reverse Engineering 工程師。目標 Repository：freeCodeCamp/freeCodeCamp。
不要修改任何檔案。

任務：萃取「使用者申請認證（claim certification）」的業務規則。
1. 從 api/src/routes/ 找出與 certificate 相關的 route，列出 method、path、檔案位置。
2. 追蹤呼叫鏈：route → schema → 檢查邏輯 → 資料庫存取（Prisma）。
3. 列出所有「申請被拒絕」的條件，每一條都要引用檔案與行號。
4. 找出對應的測試檔（*.test.ts），確認你的推論是否有測試覆蓋。
5. 產出：業務規則表（規則 / 來源檔案:行號 / 是否有測試）+ Sequence Diagram（Mermaid）。
6. 明確標註「推論」與「已由程式碼確認」的差別。

驗證方式：拿 AI 萃取的規則，對照 certificate.test.ts 中的測試案例；對不上的部分就是 AI 誤判或遺漏。

21.4 Case 3：AI Agent 分析 Legacy JavaScript Application

21.5 實務注意事項

• AI Agent 最常見的錯誤是「用命名推論行為」（例如看到 validateUser 就假設它做了完整驗證）。務必要求引用程式碼行號。
• 動態語言（JavaScript）的 Reverse Engineering 要特別注意：動態屬性存取、eval、執行期才決定的路由。靜態分析找不到的，要用執行期追蹤（日誌、Debugger）補足。
• Legacy System Modernization 詳見第 40 章 Playbook。

22. AI-assisted Framework Upgrade

22.1 freeCodeCamp 的角色

freeCodeCamp 是基礎 Web / Programming / Computer Science 能力來源，不應被視為特定企業 Framework Migration 工具。

freeCodeCamp 能提供的是：

• 理解 Framework 背後的 Web 基礎（HTTP、DOM、非同步、模組系統），讓工程師能判斷 Breaking Change 的影響
• 一個真實的升級案例：freeCodeCamp Repository 使用 Renovate 持續升級相依套件，每一個 Renovate PR 都是「套件升級 + CI 驗證」的真實範例

22.2 Framework Upgrade 流程

flowchart TB
    V1[Framework v1] --> INV[Dependency Inventory]
    INV --> COMP[Compatibility Analysis]
    COMP --> BC[Breaking Change Analysis]
    BC --> MS[Migration Specification]
    MS --> HA{Human Approval}
    HA -->|核准| MOD[Code Modification]
    HA -->|退回| MS
    MOD --> CMP[Compile / Type-check]
    CMP --> UT[Unit Test]
    UT --> IT[Integration Test]
    IT --> RT[Regression Test]
    RT --> DONE[完成]

22.3 從 freeCodeCamp 學升級實務

22.4 Case 5：AI Agent 協助 Framework Upgrade

22.5 實務注意事項

• 不要讓 Agent 一次升級所有套件。一次一個主要框架、每步都要能 build 與 test。
• Agent 對「最新版本」的知識可能過時。Breaking Changes 必須以官方 Release Notes / Migration Guide 為準，並要求 Agent 附上引用來源。
• 詳見第 41 章 Framework Upgrade Playbook。

23. AI-assisted Refactoring

23.1 Refactoring 原則

Refactoring = 在不改變外部行為的前提下改善內部結構。

因此前提一定是：先有測試。

flowchart LR
    A[確認現有測試覆蓋] --> B{覆蓋足夠？}
    B -- 否 --> C[補 Characterization Test]
    C --> A
    B -- 是 --> D[小步重構]
    D --> E[執行測試]
    E --> F{全部通過？}
    F -- 否 --> G[還原該步] --> D
    F -- 是 --> H{還有要改的？}
    H -- 是 --> D
    H -- 否 --> I[Code Review]

23.2 freeCodeCamp 延伸練習：重構自己的 Lab

完成認證專案之後（Academic Honesty），用自己的 Lab 程式碼做重構練習：

// 重構前：典型的初學者程式碼
function calc(a, b, op) {
  if (op == '+') { return a + b; }
  else if (op == '-') { return a - b; }
  else if (op == '*') { return a * b; }
  else if (op == '/') { if (b == 0) { return 'error'; } else { return a / b; } }
}

// 重構後：查表取代條件分支、明確錯誤處理、嚴格相等
const OPERATIONS = {
  '+': (a, b) => a + b,
  '-': (a, b) => a - b,
  '*': (a, b) => a * b,
  '/': (a, b) => {
    if (b === 0) throw new RangeError('Division by zero');
    return a / b;
  },
};

function calculate(a, b, op) {
  const fn = OPERATIONS[op];
  if (!fn) throw new TypeError(`Unsupported operator: ${op}`);
  return fn(a, b);
}

注意：這個重構改變了外部行為（除以零從回傳 'error' 改為丟出例外）。這在 Refactoring 中是不允許的，除非另外開一個「行為變更」的任務並更新測試。這正是 Code Review 要抓出的問題。

23.3 Case 7：AI Agent 協助 Code Review

23.4 實務注意事項

• AI 重構常見問題：順手改了行為、一次改太多、改了測試來配合程式碼。Review 時要特別看測試檔的 diff。
• 大規模重構（跨多模組）屬於 HUMAN APPROVAL 等級（第 39.4 節）。

24. AI-assisted Testing

24.1 測試層級

24.2 freeCodeCamp 的 Playwright 慣例 [Official]

contribute 文件建議：

• 優先使用 getByRole 等語意化 locator（同時兼顧無障礙）
• 無法用語意 locator 時，最後手段才用 data-playwright-test-label 屬性，且該屬性只能用於測試
• E2E 測試前需 pnpm run seed:certified-user

import { test, expect } from '@playwright/test';

test('landing page shows main heading', async ({ page }) => {
  await page.goto('/');
  await expect(
    page.getByRole('heading', { level: 1 })
  ).toBeVisible();
});

npx playwright test --ui              # UI 模式
npx playwright test landing.spec.ts   # 單一檔案
npx playwright test -g "heading"      # 依標題篩選
npx playwright test --debug           # 除錯
npx playwright show-report            # 報告

24.3 Case 6：AI Agent 協助建立 Test

24.4 實務注意事項

• AI 產生的測試常見問題：斷言太弱（只檢查不是 undefined）、測試實作細節、Mock 過多導致沒測到東西。
• 驗證測試有效性的簡單方法：故意改壞被測程式碼，看測試會不會失敗。

25. AI-assisted Documentation

25.1 文件類型與 AI 適用性

25.2 向 freeCodeCamp 學文件工程

• Documentation as Code：contribute 文件站本身是一個 Repository（freeCodeCamp/contribute，Astro Starlight），用 PR 流程更新
• Writing Style Guide：contribute 文件站有寫作風格指南（writing-style-guide）
• 環境變數即文件：sample.env 分組 + 註解
• Schema 即文件：API 以 TypeBox 定義，自動產生 /documentation

25.3 Case 8：AI Agent 協助 Repository Documentation

25.4 實務注意事項

• AI 產生的文件最大風險是「看起來很完整但指令是錯的」。每一個指令都要實際執行過。
• 文件要標示「最後驗證日期」與「適用版本」，就像本手冊開頭的 Documentation Status。

26. Context Engineering

26.1 什麼是 Context Engineering

AI Agent 的輸出品質由「它在當下看到什麼」決定。Context Engineering 是有意識地設計並控制 Agent 的上下文，而不是把所有東西都丟進去。

26.2 Context 組裝流程

flowchart LR
    T[Task] --> RK[Relevant Knowledge]
    RK --> RC[Repository Context]
    RC --> AC[Architecture Context]
    AC --> CR[Coding Rules]
    CR --> AG[AI Agent]

26.3 以 freeCodeCamp 為例的 Repository Context 檔

以下是為 freeCodeCamp Monorepo 撰寫 Agent 指引檔的範例（放在自己 Fork 的本機，加入 .git/info/exclude，不要提交到上游）：

# Agent Guide — freeCodeCamp（個人練習用）

## Environment
- Node 24（.nvmrc）、pnpm 10；Windows 必須在 WSL2 內執行
- 啟動：docker compose -f docker/docker-compose.yml -f docker/docker-compose.ports.yml up -d
        → pnpm run seed → pnpm run develop

## Layout
- api/：Fastify 5 + TypeBox + Prisma（MongoDB）；route 在 api/src/routes/{public,protected}
- client/：Gatsby 5 + React 18 + Redux + redux-saga
- curriculum/：challenges/english/blocks/<block>/<challenge>.md；結構在 structure/

## Verify before claiming done
- pnpm run lint
- pnpm run test-api / pnpm run test-client
- 課程：FCC_BLOCK=<block> pnpm run test-curriculum-content

## Rules
- 不要讀取或輸出 .env
- 不要修改 i18n-curriculum（翻譯走 Crowdin）
- commit 訊息使用 Conventional Commits：<type>(<scope>): <description>

26.4 Context 原則

1. 少而精：只給與任務相關的檔案
2. 指令可執行：Build / Test 指令必須是真的能跑的
3. 規則要具體：「不要讀 .env」比「注意安全」有效
4. 分層：全域規則（公司）→ Repository 規則 → 任務規則
5. 會過期：Context 檔也是程式碼，要隨專案更新

26.5 實務注意事項

• 把整個 Repository 塞進 Context 不但浪費 token，還會稀釋重點，導致 Agent 注意力分散。
• Agent 指引檔中不可包含機密（密碼、Token、內部 IP）。

27. RAG / Knowledge Base

27.1 freeCodeCamp 作為 AI Agent Knowledge Base

flowchart LR
    FCC[freeCodeCamp] --> CUR["Curriculum<br/>Markdown"]
    CUR --> PRE["前處理<br/>解析 front matter 與區段"]
    PRE --> CH[Chunking]
    CH --> MD[Metadata]
    MD --> EMB["Embedding / Index"]
    EMB --> RAG[RAG Retrieval]
    RAG --> AG[AI Agent]
    AG --> CIT["回答 + Citation"]

不應直接將整個 Repository 無差別塞入 AI Context Window。 正確做法是：建立索引 → 依任務檢索相關片段 → 附上引用來源。

27.2 授權與使用前提（先讀這段）

[Engineering Recommendation]：若法務尚未核准，企業 RAG 只索引「自己寫的學習筆記 + freeCodeCamp 課程連結」，而不是課程原文。

27.3 Chunking 策略

freeCodeCamp 課程天然有良好的結構，建議依結構切塊：

建議：以 Challenge 為單位；超過上限時依 # --section-- 切分。

27.4 Metadata 設計

{
  "source": "freeCodeCamp/freeCodeCamp",
  "commit": "<git SHA>",
  "path": "curriculum/challenges/english/blocks/<block>/<challenge>.md",
  "superblock": "javascript-v9",
  "block": "<block dashedName>",
  "challengeId": "<front matter id>",
  "title": "<front matter title>",
  "challengeType": 1,
  "section": "description",
  "language": "english",
  "indexedAt": "2026-09-29"
}

27.5 簡化的索引腳本範例

"""把 freeCodeCamp 課程 Markdown 切成 chunks（示意，需依實際格式調整與驗證）。"""
import json
import re
import subprocess
from pathlib import Path

import yaml  # pip install pyyaml

REPO = Path("~/projects/freeCodeCamp").expanduser()
BLOCKS = REPO / "curriculum/challenges/english/blocks"
SECTION_RE = re.compile(r"^# --([a-z-]+)--\s*$", re.MULTILINE)


def git_sha(repo: Path) -> str:
    return subprocess.check_output(["git", "-C", str(repo), "rev-parse", "HEAD"], text=True).strip()


def split_sections(body: str) -> dict[str, str]:
    parts = SECTION_RE.split(body)
    # parts = [前導文字, name1, content1, name2, content2, ...]
    return {parts[i]: parts[i + 1].strip() for i in range(1, len(parts) - 1, 2)}


def iter_chunks(block_filter: str | None = None):
    sha = git_sha(REPO)
    for md in BLOCKS.glob("*/*.md"):
        block = md.parent.name
        if block_filter and block != block_filter:
            continue
        text = md.read_text(encoding="utf-8")
        _, fm, body = text.split("---", 2)
        meta = yaml.safe_load(fm)
        for section, content in split_sections(body).items():
            if section in {"solutions"}:   # 不索引解答，避免 Agent 直接提供答案
                continue
            yield {
                "text": content,
                "metadata": {
                    "source": "freeCodeCamp/freeCodeCamp",
                    "commit": sha,
                    "path": str(md.relative_to(REPO)),
                    "block": block,
                    "challengeId": meta.get("id"),
                    "title": meta.get("title"),
                    "challengeType": meta.get("challengeType"),
                    "section": section,
                },
            }


if __name__ == "__main__":
    for chunk in iter_chunks():
        print(json.dumps(chunk, ensure_ascii=False))

設計重點：刻意不索引 --solutions--，讓以此 Knowledge Base 為基礎的學習助理只能給提示而非答案，與 Academic Honesty Policy 一致。

27.6 Retrieval 與 Citation 原則

1. 回答必須附上 path 與 commit
2. 找不到相關內容時，Agent 要回答「知識庫中沒有」，而不是自行編造
3. 定期（例如每月）以最新 commit 重建索引；舊索引保留版本以利追溯

27.7 實務注意事項

• 課程內容以英文為主，中文查詢的檢索效果需測試；可考慮多語 Embedding 模型或查詢翻譯。
• freeCodeCamp 的 learn-rag-mcp-fundamentals 課程可作為團隊 RAG 概念的共同入門教材。

28. Spec-Driven Development

28.1 SDD 與 freeCodeCamp

flowchart LR
    FCC[freeCodeCamp] --> PK[Programming Knowledge]
    PK --> AG[AI Agent]
    AG --> SP[Specification]
    SP --> IM[Implementation]
    IM --> TE[Test]

freeCodeCamp 的每一個 Lab 其實就是一份 mini-spec：

學員在 freeCodeCamp 養成「先讀清楚規格、再寫程式、以測試判定完成」的習慣，正是 SDD 需要的基本功。

28.2 企業 SDD 流程

Requirement → Specification → Architecture → Task → Code → Test

28.3 Specification 範本

# Spec: 讀書會報名

## Context
內部讀書會需要線上報名，取代目前的 Excel。

## User Stories
- US-1 身為員工，我想看到可報名的場次，以便選擇參加。
- US-2 身為員工，我想報名場次，名額滿時我應該知道。

## Acceptance Criteria
- AC-1 Given 場次剩餘名額 > 0, When 使用者報名, Then 報名成功且名額減 1
- AC-2 Given 場次剩餘名額 = 0, When 使用者報名, Then 回傳 409 且名額不變
- AC-3 Given 使用者已報名該場次, When 再次報名, Then 回傳 409

## API
| Method | Path | Request | Response | Errors |
|--------|------|---------|----------|--------|
| GET | /api/sessions | - | Session[] | - |
| POST | /api/sessions/{id}/registrations | - | Registration | 401, 404, 409 |

## Non-functional
- 併發：同時 100 人報名最後 1 個名額，只能有 1 人成功
- 安全：需登入；使用者只能看到自己的報名紀錄

## Out of Scope
- 取消報名、候補

28.4 實務注意事項

• Spec 要寫「什麼」與「為什麼」，不要寫「怎麼做」（那是 Plan 的工作）。
• 每一條 AC 都要能被測試驗證；無法驗證的 AC 要改寫。

29. TDD / BDD

29.1 學習到 TDD 的橋樑

Learn → Understand → Write Test → Implement → Refactor

差別在於：freeCodeCamp 的測試是別人寫好的；TDD 要求自己先寫測試。

29.2 TDD 循環

flowchart LR
    R["Red<br/>寫一個會失敗的測試"] --> G["Green<br/>寫最少程式碼讓它通過"]
    G --> RF["Refactor<br/>在測試保護下整理"]
    RF --> R

29.3 範例（Vitest）

// registration.test.ts — 先寫測試（Red）
import { describe, it, expect } from 'vitest';
import { register } from './registration';

describe('register', () => {
  it('succeeds when seats are available', () => {
    const session = { id: 's1', seats: 1, attendees: [] as string[] };
    const result = register(session, 'u1');
    expect(result.ok).toBe(true);
    expect(session.seats).toBe(0);
  });

  it('fails with FULL when no seats left', () => {
    const session = { id: 's1', seats: 0, attendees: [] as string[] };
    expect(register(session, 'u1')).toEqual({ ok: false, reason: 'FULL' });
  });

  it('fails with DUPLICATE when already registered', () => {
    const session = { id: 's1', seats: 5, attendees: ['u1'] };
    expect(register(session, 'u1')).toEqual({ ok: false, reason: 'DUPLICATE' });
  });
});

// registration.ts — 最少實作（Green）
export type Session = { id: string; seats: number; attendees: string[] };
export type Result = { ok: true } | { ok: false; reason: 'FULL' | 'DUPLICATE' };

export function register(session: Session, userId: string): Result {
  if (session.attendees.includes(userId)) return { ok: false, reason: 'DUPLICATE' };
  if (session.seats <= 0) return { ok: false, reason: 'FULL' };
  session.attendees.push(userId);
  session.seats -= 1;
  return { ok: true };
}

這是記憶體內的示意。真實系統的併發控制必須在資料庫層（Transaction / 條件更新）處理，單元測試無法證明併發正確性，需另外做整合測試。

29.4 BDD（Given-When-Then）

Feature: 讀書會報名

  Scenario: 名額已滿
    Given 場次 "TypeScript 入門" 剩餘名額為 0
    When 使用者 "Ada" 報名該場次
    Then 系統回應 "名額已滿"
    And 場次剩餘名額仍為 0

29.5 測試金字塔與 AI Agent

29.6 實務注意事項

• 讓 AI Agent 做 TDD 時，要求它先只輸出測試並停下來，由人確認測試是否正確表達需求，再讓它實作。否則 Agent 常會同時寫測試與實作，測試只是在「證明實作是它寫的樣子」。
• 測試檔的 diff 要與實作一起 Review。

30. Security

freeCodeCamp 的教學範例不應直接等同於企業 Production Security Standard。 教學程式碼為了聚焦概念，常省略輸入驗證、授權、錯誤處理與日誌。

30.1 OWASP Top 10:2025

依 OWASP Top 10:2025（查證日期 2026-09-29；2021 版到 2025 版的主要變動：新增 A03 Software Supply Chain Failures 與 A10 Mishandling of Exceptional Conditions，SSRF 併入 A01）：

30.2 常見漏洞與防護

XSS（Cross-Site Scripting）

// ❌ 把使用者輸入直接當 HTML
element.innerHTML = userComment;

// ✅ 當純文字處理
element.textContent = userComment;

React 預設會跳脫字串；使用 dangerouslySetInnerHTML 時必須先以可信任的 Sanitizer 處理。

SQL Injection

// ❌
await db.query(`SELECT * FROM orders WHERE id = ${req.params.id}`);
// ✅
await db.query('SELECT * FROM orders WHERE id = $1', [req.params.id]);

Authentication / Authorization

// ❌ 只檢查登入，沒檢查擁有權（IDOR）
app.get('/api/orders/:id', requireLogin, async (req, res) => {
  res.json(await Orders.findById(req.params.id));
});

// ✅ 檢查資源擁有者
app.get('/api/orders/:id', requireLogin, async (req, res) => {
  const order = await Orders.findById(req.params.id);
  if (!order) return res.sendStatus(404);
  if (order.userId !== req.user.id && !req.user.isAdmin) return res.sendStatus(403);
  res.json(order);
});

CSRF

以 Cookie 做 Session 的系統需要 CSRF 防護。freeCodeCamp API 使用 @fastify/csrf-protection 並有 api/src/plugins/csrf.ts 與對應測試，是很好的參考實作。

Secrets

• 機密只放環境變數或 Secret Manager，絕不進版控
• freeCodeCamp 的 sample.env 只放假值，真正的 .env 被 .gitignore 排除
• CI 中以 dotenv-linter 檢查 sample.env 格式（見 node.js-tests.yml）

Input Validation

• 後端以 Schema 驗證所有輸入（freeCodeCamp 用 TypeBox；Java 可用 Bean Validation）
• 白名單優於黑名單

30.3 從 freeCodeCamp Repository 學供應鏈安全

30.4 AI Agent Security Review Checklist

• 所有輸入都經後端驗證
• 所有資料存取都檢查授權（不只檢查登入）
• 沒有字串串接的 SQL / Shell / HTML
• 沒有硬編碼的密碼、金鑰、Token
• 錯誤訊息不洩漏堆疊與內部路徑
• 新增的相依套件確實存在、來源可信、授權相容、無已知高風險漏洞
• 日誌不包含個資與機密
• 開發用開關（例如 dev login）在正式環境關閉

30.5 AI 功能本身的安全（LLM Application Security）

當系統本身包含 AI 功能（例如 19.4 節的 Socrates、企業內部 AI 助教、RAG 問答）時，除了傳統的 OWASP Top 10 之外，還要對照 OWASP Top 10 for LLM Applications 2025：

30.6 實務注意事項

• 套件名稱幻覺：AI 有時會建議不存在的套件名稱，攻擊者可能搶先註冊同名惡意套件。新增任何套件前，先到官方 Registry 確認其存在、維護狀態與下載量。
• freeCodeCamp 的漏洞通報範圍僅限其官方平台。不要對 freecodecamp.org 做任何未授權的安全測試；練習請在本機環境進行。

31. Open Source Governance

31.1 License [Official]

BSD-3-Clause 的主要義務：

1. 原始碼再散布需保留版權聲明、條件與免責聲明
2. 二進位再散布需在文件或其他材料中重現上述聲明
3. 未經書面許可，不得使用版權持有者或貢獻者名稱為衍生產品背書或推廣

31.2 企業使用情境與治理

31.3 Dependency / Third-party Component / SBOM

即使只是在本機跑 freeCodeCamp，它也帶入上千個 npm 套件。企業學習環境建議：

# 列出所有 workspace 的直接相依
pnpm -r list --depth 0

# 查詢某套件為何被安裝
pnpm why <package>

# 已知漏洞稽核
pnpm audit

# 產生 SBOM（CycloneDX 格式，工具需另行安裝，以下為示意）
npx @cyclonedx/cyclonedx-npm --output-file sbom.json

SBOM 工具對 pnpm workspace 的支援程度不一，請先在小範圍驗證輸出是否完整。⚠️ 需確認目前版本。

31.4 OSS Governance 流程

flowchart LR
    A[想引入 OSS 元件] --> B[License 檢查]
    B --> C[安全掃描<br/>已知漏洞]
    C --> D[維護狀態<br/>是否 Archived]
    D --> E[登錄 SBOM /<br/>Third-party Notice]
    E --> F[核准使用]
    F --> G[持續監控<br/>Renovate / Dependabot]

31.5 實務注意事項

• 「開源」不等於「沒有義務」。BSD-3 雖寬鬆，仍有保留聲明與不得背書的要求。
• 本手冊只描述授權檔案內容，不構成法律意見；正式判斷請交由法務。

32. Maintenance

32.1 freeCodeCamp 如何維護自己 [Official]

32.2 本機維護常用指令

# 與上游同步（含 submodule）
git fetch upstream && git rebase upstream/main
git submodule update --init

# 相依有變動時重新安裝
pnpm install

# 只清除 Turborepo 快取（建置結果怪異時先試這個）
pnpm run clean:turbo

# 清除所有建置產物與 node_modules 後重建
pnpm run clean-and-develop

# 找出未使用的檔案 / 相依
pnpm run knip

# 格式化
pnpm run format

32.3 企業可借鏡的維護實踐 [Engineering Recommendation]

32.4 實務注意事項

• 維護工作最怕「累積」：半年不升級，一次要處理幾十個 Breaking Changes。freeCodeCamp 的持續小步升級是值得學習的紀律。

33. Upgrade

33.1 通用升級流程

flowchart TB
    CV[Current Version] --> INV[Inventory]
    INV --> RN[Release Notes]
    RN --> BC[Breaking Changes]
    BC --> DA[Dependency Analysis]
    DA --> MP[Migration Plan]
    MP --> BK[Backup]
    BK --> UP[Upgrade]
    UP --> BD[Build]
    BD --> TS[Test]
    TS --> RT[Regression Test]
    RT --> VL[Validation]

33.2 以 freeCodeCamp 本機環境為例：升級 Fork 到最新上游

# 1. Inventory：記錄目前狀態
git log -1 --format='%H %cd'
node -v; pnpm -v
cat .nvmrc

# 2. 取得上游變更並閱讀差異
git fetch upstream
git log --oneline HEAD..upstream/main | head -50
git diff HEAD..upstream/main -- .nvmrc package.json pnpm-workspace.yaml sample.env

# 3. 若 .nvmrc 或 engines 變動，先升級 Node
nvm install "$(cat .nvmrc)" && nvm use

# 4. 若 sample.env 有新增變數，同步到自己的 .env
diff <(grep -o '^[A-Z_]*' sample.env | sort) <(grep -o '^[A-Z_]*' .env | sort)

# 5. 更新與重建
git rebase upstream/main
pnpm install
pnpm run clean && pnpm run seed && pnpm run develop

# 6. 驗證
pnpm run lint && pnpm run test

33.3 如何利用 AI Agent 協助 freeCodeCamp 升級

你現在是 Senior Software Architect。

請先分析目前 freeCodeCamp Repository（本機 Fork，已 fetch upstream）。
不要立即修改程式碼。

請先完成：
1. Dependency Inventory：各 workspace package 的主要框架與版本（gatsby、react、fastify、prisma、typescript、vitest、playwright）
2. Runtime Version：.nvmrc、engines、CI 使用的 Node 版本是否一致
3. Build Tool：turbo、pnpm 版本與設定
4. Framework Version：目前版本 vs 最新穩定版（請引用官方 Release 頁面，無法確認時標示「需確認」）
5. Breaking Changes：列出可能影響本專案的項目，每項附官方來源連結
6. Deprecated API：搜尋程式碼中已被標為 deprecated 的用法，附檔案:行號
7. Security Risk：pnpm audit 結果摘要
8. Test Impact：哪些測試可能受影響
9. Migration Risk：高 / 中 / 低，並說明理由

最後產生 Migration Plan（分階段、每階段的驗證指令與回滾方式）。

完成 Plan 並取得人工確認前，不可修改程式碼。

33.4 實務注意事項

• 升級 freeCodeCamp 本身是上游維護者的工作；我們在 Fork 上的「升級」主要是同步上游。這個練習的價值在於熟悉升級流程，再套用到公司專案。
• 公司專案的升級必須走變更管理流程（第 42 章）。

34. Troubleshooting

34.1 Troubleshooting Guide

以上依 contribute 文件「Troubleshoot issues with your development setup」與「How to Set Up freeCodeCamp Locally」整理（2026-09-29）。官方也提醒：先決條件工具（Node、Docker 等）本身的問題請不要到 freeCodeCamp 開 GitHub Issue，請到 Forum 或 Discord 求助。

34.2 系統化排錯流程

flowchart TB
    E[發生錯誤] --> R[完整閱讀錯誤訊息]
    R --> V{版本正確？<br/>node / pnpm / docker}
    V -- 否 --> FIX1[修正版本] --> RETRY[重試]
    V -- 是 --> ENV{.env 存在？<br/>MongoDB 在跑？}
    ENV -- 否 --> FIX2[修正環境] --> RETRY
    ENV -- 是 --> CLEAN[clean + install + seed]
    CLEAN --> OK{解決？}
    OK -- 是 --> DONE[記錄到團隊 FAQ]
    OK -- 否 --> SEARCH[搜尋官方 Troubleshooting / Forum]
    SEARCH --> AI["請 AI Agent 協助分析<br/>附版本資訊，不附機密"]
    AI --> ASK[到 Forum / Discord 提問]

34.3 請 AI Agent 協助排錯的 Prompt

我在本機建立 freeCodeCamp 開發環境時遇到錯誤。
環境：
- OS：Windows 11 + WSL2 Ubuntu 24.04
- 專案路徑：~/projects/freeCodeCamp（不在 /mnt/c）
- node -v：<貼上>
- pnpm -v：<貼上>
- docker compose version：<貼上>
- .env：已由 sample.env 複製（不提供內容）
- 執行的指令：<貼上>
- 完整錯誤訊息：<貼上>

請：
1. 列出最可能的 3 個原因，依可能性排序。
2. 每個原因給出「驗證方法」與「修正方法」。
3. 引用 contribute.freecodecamp.org 相關頁面（若你不確定某頁存在，請說明）。
4. 不要建議任何會刪除資料的指令，除非先說明風險。

34.4 實務注意事項

• 團隊內部維護一份「freeCodeCamp 環境 FAQ」，記錄公司網路環境特有的問題（Proxy、憑證、內部 mirror），新人效率會大幅提升。

35. Enterprise Adoption

35.1 定位原則

不要把 freeCodeCamp 包裝成企業正式開發標準。

35.2 建議的企業架構

                Enterprise AI Development
                         │
        ┌────────────────┼────────────────┐
        │                │                │
   Learning         Engineering       Governance
        │                │                │
 freeCodeCamp        SDLC/SDD         Security
        │                │                │
        └────────────────┼────────────────┘
                         │
                     AI Agent
                         │
             ┌───────────┼───────────┐
             │           │           │
          Coding      Reverse     Upgrade
                     Engineering

flowchart TB
    EAD[Enterprise AI Development]
    EAD --> L[Learning]
    EAD --> E[Engineering]
    EAD --> G[Governance]
    L --> FCC[freeCodeCamp]
    E --> SDLC[SDLC / SDD]
    G --> SEC[Security / Engineering Standard]
    FCC --> AG[AI Agent]
    SDLC --> AG
    SEC --> AG
    AG --> C[Coding]
    AG --> RE[Reverse Engineering]
    AG --> UP[Framework Upgrade]

35.3 企業導入 SOP

35.4 導入 KPI 建議 [Engineering Recommendation]

35.5 實務注意事項

• 導入初期先在「公開 Repository（freeCodeCamp）」上練習 AI Agent，再進入公司 Repository，可降低機密外洩風險，也讓 AI 使用規範有時間成熟。

36. Developer Skill Matrix

36.1 企業學習分級

36.2 AI Agent Developer Skill Matrix

圖例：必修＝該級必須具備；建議＝該級建議具備；進階＝該級應深入；實務能力＝該級需能在專案中獨立運用並指導他人；—＝不要求。

36.3 freeCodeCamp 對應課程

36.4 實務注意事項

• Skill Matrix 用於規劃學習，不是績效評分表。
• 每年檢視一次，AI Agent 相關能力的要求變化最快。

37. Learning Roadmap

37.1 總覽

gantt
    title 企業 AI Agent 開發工程師 180 天 Roadmap
    dateFormat  YYYY-MM-DD
    axisFormat  %m/%d
    section 基礎
    30 Days 基礎 Web Development       :a1, 2026-10-01, 30d
    60 Days Full Stack Development      :a2, after a1, 30d
    section 工程
    90 Days Software Engineering        :a3, after a2, 30d
    section AI
    120 Days AI-assisted Development    :a4, after a3, 30d
    180 Days AI Agent + Reverse Engineering + Modernization :a5, after a4, 60d

37.2 Day 1–30：基礎 Web Development

37.3 Day 31–60：Full Stack Development

37.4 Day 61–90：Software Engineering

37.5 Day 91–120：AI-assisted Development

37.6 Day 121–180：AI Agent + Reverse Engineering + Modernization

37.7 認證時數規劃

官方公告每張 Checkpoint Certification 約 300 小時。180 天 Roadmap 以 20–30% 工時估算（約 200–300 小時），只夠完成一張認證。因此 Roadmap 以「能力與延伸 Lab」為主，認證則採長期規劃：

建議的 12 個月認證規劃 [Engineering Recommendation]：

已具備基礎的同仁可以直接挑戰認證的 5 個專案與考試，不必從頭上完所有課程。

37.8 實務注意事項

• 有經驗的工程師可跳過前 60 天，但仍建議完成本機環境與 Git 練習，並以認證考試驗證基礎。
• Roadmap 以 20–30% 工時估算；若全職學習可壓縮為一半時間。
• 規劃時請先確認目標認證已開放考試（13.1 節上線狀態），尚未開放的認證只能先完成課程。

38. Hands-on Labs

重要規則：以下 Lab 是 freeCodeCamp 課程之外的企業延伸練習。凡標示「AI Prompt」者，皆在延伸 Lab 中使用，不可用於 freeCodeCamp 認證專案本身（Academic Honesty Policy）。

38.1 Lab 總覽

38.2 Lab 1 — HTML Web Page

• Goal：建立語意正確、通過無障礙檢查的「團隊介紹頁」

• Prerequisite：完成 Responsive Web Design v9 的 HTML 相關 Module

• Steps：

  1. 自己手寫 index.html（header、nav、main、section、footer）
  2. 加入含 <label> 的聯絡表單
  3. 用瀏覽器 DevTools Lighthouse 跑 Accessibility 檢查
  4. 請 AI 審查，再自行修正

• AI Prompt：

  請以無障礙（WCAG）與語意化 HTML 的角度審查以下 HTML。
  只列出問題與原因，並說明對螢幕閱讀器使用者的影響，不要直接給我修改後的完整程式碼。
  <貼上 HTML>

• Expected Result：頁面結構語意化；表單元素皆有 label

• Verification：Lighthouse Accessibility ≥ 90；用鍵盤 Tab 可操作所有互動元素

• Extension：加入 lang 屬性與 skip link；用螢幕閱讀器（NVDA / VoiceOver）實測

38.3 Lab 2 — Responsive Web Page

• Goal：讓 Lab 1 頁面在 320px～1440px 都正常顯示

• Prerequisite：Lab 1；CSS Flexbox / Grid 相關課程

• Steps：

  1. 採用 Mobile-first 撰寫 CSS
  2. 使用 Grid 排列成員卡片，Flexbox 排列 nav
  3. 加入 1 個 media query（例如 min-width: 768px）
  4. 用 DevTools 裝置模式檢查

• AI Prompt：

  這是我的 CSS。請指出在 320px 寬度時可能造成水平捲軸或文字重疊的規則，
  並解釋原因。不要重寫整份 CSS。
  <貼上 CSS>

• Expected Result：無水平捲軸，文字可讀

• Verification：320 / 768 / 1440 三種寬度截圖

• Extension：以 CSS Custom Properties 實作 Dark Mode

38.4 Lab 3 — JavaScript Application

• Goal：建立具 CRUD 與 localStorage 保存的待辦清單

• Prerequisite：JavaScript v9（DOM、事件、learn-localstorage-and-crud-operations-with-javascript）

• Steps：

  1. 設計資料結構 { id, title, done, createdAt }
  2. 實作新增、切換完成、刪除、篩選
  3. 將狀態保存到 localStorage
  4. 處理 localStorage 讀取失敗（例如 JSON 格式錯誤）

• AI Prompt：

  請扮演 Code Reviewer，審查我的 Todo App JavaScript：
  1. 潛在 bug（特別是事件處理與狀態同步）
  2. XSS 風險（是否有 innerHTML 使用者輸入）
  3. 錯誤處理（localStorage 資料損毀時）
  每個問題附上行號與原因。
  <貼上程式碼>

• Expected Result：功能完整；重新整理後資料仍在

• Verification：手動測試清單；在 DevTools 手動竄改 localStorage 為非法 JSON，App 不應崩潰

• Extension：改寫成 TypeScript；以 Vitest 為資料邏輯寫測試

38.5 Lab 4 — REST API

• Goal：以 Node.js 建立 Todo REST API（CRUD）

• Prerequisite：Back-End Development and APIs v9

• Steps：

  1. 以 AI Agent 依第 28 章範本產生 spec.md（端點、狀態碼、錯誤格式），人工修訂
  2. 選用框架（例如 Fastify，可參考 freeCodeCamp api/ 的 Schema 驗證做法）
  3. 為每個端點定義 Request / Response Schema
  4. 實作並撰寫測試

• AI Prompt：

  依據以下 spec.md 實作 Todo REST API（Fastify + TypeScript）。
  要求：
  - 每個 route 都要有 request/response JSON Schema 驗證
  - 錯誤回應格式統一為 { "error": { "code": string, "message": string } }
  - 每個 route 附一個 .test.ts（使用 fastify.inject）
  - 不要新增 spec 以外的端點
  先輸出檔案清單與實作計畫，等我確認後再寫程式碼。
  <貼上 spec.md>

• Expected Result：5 個端點（list / get / create / update / delete）與測試

• Verification：npm test 全數通過；手動送非法輸入（缺欄位、錯型別）得到 400

• Extension：加入分頁、OpenAPI 文件（Swagger UI）

38.6 Lab 5 — Database Application

• Goal：將 Lab 4 的儲存層改為 PostgreSQL，並正確處理 Transaction

• Prerequisite：Relational Databases v9、introduction-to-sql-and-postgresql

• Steps：

  1. 設計資料表與 Index
  2. 撰寫 migration（建表 SQL）
  3. 所有查詢使用 Parameterized Query
  4. 實作「批次完成」功能，需在單一 Transaction 內完成

• AI Prompt：

  請審查以下資料表設計與 SQL：
  1. 正規化是否合理
  2. 查詢是否需要 Index（依 WHERE / ORDER BY 分析）
  3. 是否有 SQL Injection 風險
  4. 批次更新的 Transaction 邊界是否正確、失敗時是否會 rollback
  <貼上 schema.sql 與查詢程式碼>

• Expected Result：正確的 Schema、Index 與 Transaction

• Verification：EXPLAIN 確認查詢使用 Index；模擬批次中途失敗，資料不應部分更新

• Extension：加入樂觀鎖（version 欄位）處理併發更新

38.7 Lab 6 — Full Stack Application

• Goal：以 SDD 流程完成「讀書會報名」系統（第 20.3 節 Case 2）
• Prerequisite：Lab 3–5
• Steps：
  1. Spec → Plan → Test → Code（每階段人工確認）
  2. 前端（React）呼叫後端 API
  3. 實作名額與重複報名檢查（資料庫層保證）
  4. 撰寫 1 個 Playwright E2E 測試（使用 getByRole）
• AI Prompt：使用第 20.3 節 Prompt
• Expected Result：可運作的前後端系統 + 測試
• Verification：所有 Acceptance Criteria 有對應測試；併發測試（同時 20 個請求搶 1 個名額）只有 1 個成功
• Extension：加入取消報名與候補功能，先更新 Spec

38.8 Lab 7 — Unit Test

• Goal：以 TDD 完成一個「密碼強度檢查」函式

• Prerequisite：第 29 章

• Steps：

  1. 列出規則（長度 ≥ 12、包含大小寫、數字、符號、不可包含帳號）
  2. 先寫測試（Red），請 AI 補充邊界案例
  3. 實作（Green）
  4. 重構（Refactor）

• AI Prompt：

  以下是密碼強度規則與我目前寫好的 Vitest 測試。
  請只補充「我遺漏的邊界案例」測試（例如空字串、Unicode、剛好 12 字元、帳號大小寫變化），
  不要寫實作程式碼。
  <貼上規則與測試>

• Expected Result：測試先於實作；邊界案例完整

• Verification：測試覆蓋率報告；故意改壞實作（例如把 >= 12 改成 > 12），至少一個測試失敗

• Extension：改用 property-based testing（例如 fast-check）

38.9 Lab 8 — Refactoring

• Goal：在測試保護下重構一段「義大利麵程式碼」
• Prerequisite：Lab 7；第 23 章
• Steps：
  1. 取得練習用程式碼（例如自己早期的 Lab 或團隊提供的範例）
  2. 補 Characterization Test 鎖定目前行為
  3. 請 AI 提出重構計畫（不改行為）
  4. 小步執行，每步跑測試
• AI Prompt：使用第 39 章 P06 Refactoring Prompt
• Expected Result：可讀性提升，行為不變
• Verification：重構前後測試完全相同且全部通過；測試檔在重構過程中沒有被修改
• Extension：以 ESLint complexity 規則量測重構前後的循環複雜度

38.10 Lab 9 — Reverse Engineering（使用 freeCodeCamp Repository）

• Goal：萃取 freeCodeCamp「Challenge 提交」流程的規格
• Prerequisite：完成第 7–10 章本機環境；第 21 章
• Steps：
  1. 完整 clone（非 --depth=1）freeCodeCamp
  2. 以 AI Agent 進行唯讀分析：client 如何送出完成紀錄 → API route → schema → 資料庫更新
  3. 產出 Sequence Diagram、API 規格、業務規則表（每條附檔案:行號）
  4. 對照 api/src/routes/protected/challenge.test.ts 驗證推論
  5. 在本機實際操作一次（完成一個 Challenge），用瀏覽器 DevTools Network 面板比對真實請求
• AI Prompt：使用第 39 章 P07 Reverse Engineering Prompt，Target 設為「Challenge 提交流程」
• Expected Result：一份附引用來源的規格文件
• Verification：規格中的每條規則都能在程式碼或測試中找到；Network 面板的實際請求與文件一致
• Extension：對規格中「沒有測試覆蓋」的規則，撰寫一個新的測試（僅在本機，不提交上游）

38.11 Lab 10 — Framework Upgrade

• Goal：為一個練習專案產出並執行主要框架升級
• Prerequisite：Lab 4 或 Lab 6 的專案；第 22、41 章
• Steps：
  1. 將練習專案刻意鎖定在較舊的主要版本（例如舊版 Fastify 或 React）
  2. 以 AI Agent 產出 Migration Plan（第 41 章流程）
  3. 人工核准後分階段升級
  4. 每階段執行 type-check / test
• AI Prompt：使用第 39 章 P11 Framework Upgrade Prompt
• Expected Result：升級完成、測試全過、有 Rollback Plan
• Verification：Plan 中每個 Breaking Change 都附官方來源連結；升級後測試全過
• Extension：設定 Renovate，讓專案持續小步升級

38.12 Lab 11 — Context Engineering

• Goal：為 freeCodeCamp 本機 Fork 撰寫 Agent 指引檔，並比較有無指引檔的差異

• Prerequisite：第 26 章

• Steps：

  1. 在沒有指引檔的情況下，請 Agent「新增一個 API route 的測試」，記錄結果
  2. 依第 26.3 節撰寫指引檔（加入 .git/info/exclude）
  3. 以相同 Prompt 再做一次
  4. 比較：Agent 是否使用正確的測試指令、是否遵守目錄慣例、是否讀取了 .env

• AI Prompt：

  請在 api/src/routes/public/status.test.ts 中新增一個測試案例，
  驗證 status 端點回應的 Content-Type 是 JSON。
  完成後執行相關測試並回報結果。

• Expected Result：有指引檔時，Agent 行為更一致、更少錯誤指令

• Verification：兩次執行的對照表（使用的指令、修改的檔案、測試結果）

• Extension：把指引檔中的「驗證步驟」包裝成團隊的 Agent Skill

38.13 Lab 12 — RAG Mini Knowledge Base

• Goal：以 freeCodeCamp 某一個 Block 建立小型、可引用的知識庫

• Prerequisite：第 27 章；learn-rag-mcp-fundamentals；法務對課程內容使用範圍的確認（或改用自己的學習筆記）

• Steps：

  1. 使用第 27.5 節腳本，只處理一個 Block（iter_chunks(block_filter=...)）
  2. 將 chunks 寫入本機向量資料庫（依公司核准的工具）
  3. 建立查詢介面，回答必須附 path 與 commit
  4. 設計 10 個測試問題，其中 2 個是知識庫中「沒有」的內容

• AI Prompt：

  你是學習助理。只能根據提供的檢索結果回答。
  規則：
  1. 每個論點都要附上來源 path。
  2. 檢索結果中沒有的資訊，回答「知識庫中沒有相關內容」。
  3. 不要提供 freeCodeCamp 題目的完整解答，只提供提示。
  檢索結果：
  <chunks>
  問題：<question>

• Expected Result：可引用來源的問答

• Verification：10 個問題中，8 個有正確引用；2 個「沒有」的問題未編造答案

• Extension：以 MCP Server 形式提供給 AI Agent 使用

38.14 實務注意事項

• 每個 Lab 都要保留：Prompt 紀錄、AI 原始輸出、人工修改、驗證結果。這四項是 Mentor 評估的依據，也是團隊 Prompt Library 的養分。

39. AI Agent Prompt Library

本章等同 Prompt Library 的 01-learning.md … 15-github-contribution.md，但依要求全部放在本檔案中。 每則 Prompt 的 <...> 需依實際情況替換。

39.1 Prompt 結構原則

39.2 Prompt 索引

39.3 Prompts

P01 — Learning Prompt

我正在學習 freeCodeCamp 的「<課程 / Module 名稱>」，主題是「<概念>」。
請扮演家教，不要直接給我任何 Lab 或認證專案的解答。
1. 用 3–5 句話解釋這個概念，並說明它解決什麼問題。
2. 提供 1 個與課程不同的簡短範例。
3. 說明初學者最常見的 2 個誤解。
4. 出 3 題由淺到深的練習題，等我作答後再批改。
5. 若你的說明涉及語言規格細節，請附上 MDN 或官方文件連結。

P02 — Explain Code Prompt

請解釋以下程式碼，對象是具備 <語言> 基礎的工程師。
不要修改程式碼。
1. 一句話說明這段程式碼的目的。
2. 逐段說明執行流程（標示行號）。
3. 列出輸入、輸出、副作用（I/O、全域狀態、網路、資料庫）。
4. 指出任何不明確、可能有 bug 或依賴隱含假設的地方。
5. 若需要其他檔案才能確認行為，列出需要的檔案。
<貼上程式碼，或指定檔案路徑>

P03 — Generate Code Prompt

你是 Senior <技術棧> Engineer。
任務：<功能描述>
Acceptance Criteria：
- <AC-1>
- <AC-2>
專案慣例：請先閱讀 <參考檔案 1>、<參考檔案 2>，並遵循相同的結構、命名與錯誤處理方式。

限制：
- 只修改 / 新增以下檔案：<檔案清單>
- 不新增相依套件（若必須新增，先說明理由並停下來等我確認）
- 所有輸入需驗證；所有資料存取需檢查授權
- 不可硬編碼任何機密

步驟：
1. 先輸出實作計畫（檔案、函式、測試案例），停下來等我確認。
2. 確認後先寫測試，再寫實作。
3. 執行 <lint 指令>、<test 指令>，回報結果。

P04 — Review Prompt

請以 Senior Reviewer 身分審查以下 PR diff。你只能提出意見，不可修改程式碼，也不可給出 Approve 結論。
審查面向（依序）：
1. Correctness：邏輯錯誤、邊界條件、錯誤處理
2. Security：輸入驗證、授權、Injection、機密、日誌中的個資
3. Performance：N+1、不必要的迴圈、大資料量下的複雜度
4. Maintainability：命名、重複、函式長度、與專案慣例的一致性
5. Tests：是否涵蓋新增行為；測試是否被修改來配合實作

輸出格式（依嚴重度排序）：
| 嚴重度 | 檔案:行號 | 問題 | 為什麼重要 | 建議 | 信心（高/中/低） |

最後列出「我無法判斷、需要人工確認」的項目。
<貼上 diff 或 PR 連結>

P05 — Debug Prompt

我遇到一個 bug，請協助系統化排查。先不要修改任何程式碼。
- 預期行為：<...>
- 實際行為：<...>
- 重現步驟：<...>
- 錯誤訊息 / Stack trace：<...>
- 環境：<OS、runtime 版本、相關套件版本>
- 最近的變更：<git log 或描述>

請：
1. 列出 3 個最可能的根因，依可能性排序，說明推理依據。
2. 每個根因提供一個「可以確認或排除它」的具體驗證步驟（加 log、寫最小重現測試、下中斷點）。
3. 等我回報驗證結果後，再提出修正方案。
4. 修正方案必須附一個「修正前失敗、修正後通過」的測試。

P06 — Refactoring Prompt

請重構 <檔案 / 函式>，目標：<可讀性 / 降低複雜度 / 消除重複 / ...>。
硬性規則：
- 不可改變外部行為（公開 API、回傳值、例外型別、副作用）
- 不可修改任何既有測試檔
- 每次只做一種重構手法（Extract Function、Rename、Replace Conditional with Polymorphism…）

步驟：
1. 先檢查目前的測試是否足以保護這段程式碼；不足時，列出需要補的 Characterization Test 並停下來。
2. 提出重構步驟清單（每步的手法與預期效果），等我確認。
3. 逐步執行，每一步後執行 <test 指令> 並回報。
4. 任何一步測試失敗，立即還原該步並報告原因。

P07 — Reverse Engineering Prompt

你是 Reverse Engineering 工程師。目標系統：<Repository / 路徑>。
這是唯讀任務：不可修改、新增或刪除任何檔案，不可執行會改變狀態的指令。

分析目標：<整個系統 / 特定流程，例如「訂單建立流程」>

請依序完成，每一項都要引用「檔案:行號」作為證據：
1. Static Analysis：技術棧、進入點、設定檔、建置方式
2. Dependency Analysis：外部套件（版本）、內部模組相依
3. Call Flow：從入口（UI / Route / Job）到資料存取的呼叫鏈，以 Mermaid sequenceDiagram 表示
4. Business Rules：所有條件判斷、計算公式、驗證規則，表格列出（規則 / 證據 / 是否有測試）
5. Data Model：實體、欄位、關聯，以 Mermaid erDiagram 表示
6. API：端點、Request / Response、錯誤碼
7. Architecture：模組邊界與分層，以 Mermaid flowchart 表示
8. Specification：以 Given-When-Then 撰寫可驗證的規格

最後列出：
- 「已由程式碼確認」vs「推論」的清單
- 無法從程式碼判斷、需要詢問業務或原開發者的問題
- 建議優先撰寫的 Characterization Test

P08 — Architecture Analysis（Code Understanding）Prompt

請先閱讀此 Repository。
不要修改任何程式碼。

請分析：
1. Application Architecture
2. Frontend Architecture
3. Backend Architecture
4. Database
5. API
6. Authentication
7. Build
8. Test
9. Deployment

每一項請：
- 說明使用的技術與版本（引用 package.json / pom.xml 等檔案）
- 說明主要目錄的角色
- 標示你的信心程度與依據

最後建立 Architecture Map（Mermaid flowchart），並列出你無法確認的部分。

P09 — API Analysis Prompt

請盤點 <Repository> 的所有 HTTP API。唯讀任務。
1. 找出路由定義的位置與框架慣例（例如 Fastify route、Express router、Spring @RequestMapping）。
2. 以表格列出：Method | Path | 需登入? | 授權規則 | Request Schema | Response | 錯誤碼 | 定義位置（檔案:行號） | 測試位置
3. 標出：沒有 Schema 驗證的端點、沒有授權檢查的端點、沒有測試的端點、看起來已棄用（deprecated）的端點。
4. 若專案已有 OpenAPI / Swagger，比對程式碼與文件是否一致。

以 freeCodeCamp 練習時，可對照 api/src/routes/public/ 與 protected/ 的分類，以及本機 http://localhost:3000/documentation 的 Swagger UI 驗證結果。

P10 — Database Analysis Prompt

請分析 <Repository> 的資料層。唯讀任務，不可連線到任何正式資料庫。
1. 資料庫種類與存取方式（ORM / Query Builder / 原生 SQL），引用設定檔。
2. 從 schema 檔（例如 schema.prisma、migration、Entity 類別）整理所有實體、欄位、型別、關聯、Index。
3. 以 Mermaid erDiagram 呈現。
4. 找出所有寫入操作，標示是否在 Transaction 內。
5. 找出潛在問題：N+1 查詢、缺少 Index 的查詢條件、字串串接 SQL、沒有 migration 的 schema 變更。
6. 列出含個資的欄位，供資料保護審查。

freeCodeCamp 練習：分析 api/prisma/schema.prisma（MongoDB provider）的 user 模型與相關查詢。

P11 — Framework Upgrade Prompt

你現在是 Senior Software Architect，負責 <Framework> 從 <目前版本> 升級到 <目標版本>。
完成 Plan 並取得人工確認前，不可修改任何程式碼。

請完成：
1. Dependency Inventory：runtime、框架、周邊套件的目前版本（引用 lockfile）
2. Compatibility Analysis：每個周邊套件是否支援目標版本（附官方來源；無法確認標示「需確認」）
3. Breaking Change Analysis：依官方 Release Notes / Migration Guide 逐項列出，並標示本專案是否受影響、受影響的檔案:行號
4. Deprecated API：程式碼中使用到的已棄用 API
5. Test Impact：受影響的測試；目前測試覆蓋是否足以保護升級
6. Security：升級是否修補已知漏洞
7. Migration Specification：分階段計畫（每階段：變更內容、驗證指令、完成條件、回滾方式）
8. Risk：高 / 中 / 低與理由

輸出後停下來，等待人工核准。核准後一次只執行一個階段，每階段結束回報 build / test 結果。

P12 — Test Generation Prompt

請為 <檔案 / 函式> 撰寫測試，使用 <測試框架>，遵循專案既有測試風格（參考 <既有測試檔>）。
目的：<鎖定目前行為（Characterization） / 驗證新需求>

要求：
1. 先列出測試案例清單（正常、邊界、錯誤、權限），停下來等我確認。
2. 斷言要具體（檢查實際值），不可只檢查「不是 undefined」。
3. 只 Mock 外部邊界（網路、時間、資料庫），不要 Mock 被測單元本身的邏輯。
4. 若為 Characterization Test：斷言必須反映「目前實際行為」，即使看起來是 bug；另外把疑似 bug 列成清單。
5. 執行測試並回報結果。
6. 說明如何驗證這些測試真的有效（例如哪一行改壞會讓哪個測試失敗）。

P13 — Security Review Prompt

請以 Application Security Engineer 身分審查以下程式碼 / diff，依據 OWASP Top 10:2025。
唯讀任務。
檢查項目：
- A01 Broken Access Control：每個資料存取是否檢查擁有者 / 角色
- A02 Security Misconfiguration：開發用設定、除錯開關、CORS、預設帳密
- A03 Software Supply Chain Failures：新增套件是否存在、是否可信、版本是否鎖定
- A04 Cryptographic Failures：雜湊、加密、隨機數
- A05 Injection：SQL / NoSQL / Command / HTML
- A07 Authentication Failures：Session、JWT、密碼處理
- A09 Security Logging and Alerting Failures：稽核日誌、日誌中的機密
- A10 Mishandling of Exceptional Conditions：錯誤訊息洩漏、吞掉例外
- Secrets：硬編碼的金鑰、Token、密碼

輸出：| 風險等級 | OWASP 類別 | 檔案:行號 | 問題 | 攻擊情境 | 修正建議 |
不要輸出可直接用於攻擊的 Exploit 程式碼。

P14 — Documentation Prompt

請為 <Repository> 撰寫開發者文件。只可新增 / 修改 docs/ 與 README.md，不可修改程式碼。
讀取時排除 .env 與任何含機密的檔案。

產出：
1. README.md：專案目的、技術棧、Quick Start（從 clone 到跑測試）
2. docs/architecture.md：架構圖（Mermaid）、模組職責
3. docs/local-development.md：環境需求（版本）、環境變數說明（只列名稱與用途，不列值）、常用指令
4. docs/troubleshooting.md：常見錯誤與處理

要求：
- 每個指令都必須來自專案實際的設定檔（package.json scripts、Makefile、CI workflow），並註明來源
- 無法確認的內容標示「TODO: 需確認」
- 文件開頭標示「最後驗證日期」與「適用版本」

P15 — GitHub Contribution Prompt

我想對 freeCodeCamp/freeCodeCamp 提交第一個 PR，Issue 是 <Issue 連結或內容>。
請協助我，但由我親自完成修改與提交。
1. 閱讀 Issue，說明問題與預期修改範圍（是否只涉及英文課程或程式碼）。
2. 指出需要修改的檔案，以及 contribute.freecodecamp.org 中相關的指南頁面。
3. 列出我需要在本機執行的驗證指令（lint、相關測試、課程內容測試請使用 FCC_BLOCK 等變數縮小範圍）。
4. 依 Conventional Commits 建議 PR 標題（type 限 fix / feat / refactor / docs，scope 例如 curriculum / client / api）。
5. 提醒我 PR Checklist 的重點：不在 main 開發、描述最後寫 "Closes #<issue>"、不要 @mention 維護者、UI 變更附截圖、行為變更附 Playwright 測試。
不要替我產生整個 PR 的程式碼。

39.4 AI Agent 工作安全規則

flowchart LR
    RO["READ ONLY<br/>Read / Analyze / Explain / Document"] --> CW["CONTROLLED WRITE<br/>指定檔案 / Test / Documentation"]
    CW --> HA["HUMAN APPROVAL<br/>高風險變更"]

READ ONLY

AI 只能：

• Read（讀取程式碼與文件，排除 .env 與機密）
• Analyze
• Explain
• Document（輸出在對話中，或寫入指定的報告檔）

適用：P01、P02、P04、P07–P10、P13；Reverse Engineering 初期；所有第一次接觸的 Repository。

CONTROLLED WRITE

AI 可以：

• 修改指定檔案
• 建立 Test
• 建立 Documentation

條件：在功能分支上、變更範圍事先列出、完成後執行 lint / test、由人 Review diff。

HUMAN APPROVAL

以下必須人工確認後才能執行：

39.5 實務注意事項

• Prompt Library 要版本化管理（放在 Git），並記錄每則 Prompt 的適用情境與已知限制。
• 當 Prompt 在實務中出錯時，修正 Prompt 並記錄原因，這是團隊 AI 能力成長的主要來源。

40. Reverse Engineering Playbook

40.1 核心原則

AI Agent 不應在不了解 Legacy System 的情況下直接修改程式碼。

Understand First → Specify → Test → Change → Verify

40.2 Legacy System Modernization 流程

flowchart TB
    LS[Legacy System] --> U["Understand<br/>P08 Architecture / P07 Reverse Engineering"]
    U --> D["Document<br/>架構、API、資料模型、業務規則"]
    D --> T["Test<br/>Characterization Test（P12）"]
    T --> R["Refactor<br/>測試保護下整理（P06）"]
    R --> M["Modernize<br/>替換技術元件（Strangler Fig）"]
    M --> UP["Upgrade<br/>Framework / Runtime（P11）"]

40.3 階段詳解

40.4 業務規則萃取表範本

40.5 以 freeCodeCamp 練習的建議題目

40.6 實務注意事項

• 業務規則的最終確認者是人。AI 可以找出程式碼中的條件判斷，但無法知道那是「刻意的業務規則」還是「多年前的 bug」。
• Legacy 系統常有「程式碼以外」的邏輯：資料庫 Trigger、Stored Procedure、排程腳本、設定檔、甚至人工作業。Reverse Engineering 範圍要明確包含或排除。

41. Framework Upgrade Playbook

41.1 核心原則

1. 先 Plan、後動手：Plan 未經核准，Agent 不可修改程式碼
2. 小步前進：一次一個主要框架、每步都可 build 與 test
3. 官方來源為準：Breaking Changes 以官方 Migration Guide 為準，不信任 AI 的記憶
4. 可回滾：每一步都有回滾方式

41.2 流程與關卡

flowchart TB
    A["1. Dependency Inventory"] --> B["2. Compatibility Analysis"]
    B --> C["3. Breaking Change Analysis<br/>附官方來源"]
    C --> D["4. Migration Specification<br/>分階段 + 回滾"]
    D --> G1{"Gate 1<br/>Architect 核准"}
    G1 -- 退回 --> D
    G1 -- 核准 --> E["5. Code Modification<br/>一次一階段"]
    E --> F["6. Compile / Type-check"]
    F --> H["7. Unit Test"]
    H --> I["8. Integration Test"]
    I --> J["9. Regression Test / E2E"]
    J --> G2{"Gate 2<br/>全部通過？"}
    G2 -- 否 --> E
    G2 -- 是 --> K{還有下一階段？}
    K -- 是 --> E
    K -- 否 --> L["10. Staging 驗證 + 效能比對"]
    L --> G3{"Gate 3<br/>上線核准"}

41.3 Migration Specification 範本

# Migration Spec：<Framework> <from> → <to>

## 1. 範圍
- 包含：<套件清單>
- 不包含：<套件清單>

## 2. 目前狀態（Inventory）
| 套件 | 目前版本 | 目標版本 | 官方 Release Notes |
|------|---------|---------|------------------|

## 3. Breaking Changes 影響分析
| # | Breaking Change | 官方來源 | 受影響檔案 | 處理方式 |
|---|----------------|---------|-----------|---------|

## 4. 分階段計畫
| 階段 | 變更 | 驗證指令 | 完成條件 | 回滾方式 |
|------|------|---------|---------|---------|
| 1 | 升級 runtime | `node -v && npm test` | 測試全過 | 還原 .nvmrc |
| 2 | 升級核心框架 | `npm run type-check && npm test` | 測試全過 | revert PR |

## 5. 風險
| 風險 | 可能性 | 影響 | 因應 |
|------|-------|------|------|

## 6. 驗收
- [ ] Type-check 無錯誤
- [ ] 單元 / 整合 / E2E 測試全過
- [ ] 效能基準不退步超過 <X>%
- [ ] Staging 驗證 <N> 天無新增錯誤

41.4 freeCodeCamp 參考點

41.5 實務注意事項

• freeCodeCamp 不是 Migration 工具：它提供的是理解框架所需的基礎能力，以及一個可觀察的升級實踐案例。
• AI Agent 常見錯誤：用過時的 API 知識「修正」程式碼、為了讓測試通過而修改測試、一次升級太多套件。Gate 設計就是為了攔截這些問題。

42. Enterprise SDLC Integration

42.1 三者分工

freeCodeCamp 負責「能力培養」，AI Agent 負責「工程協作」，企業 SDLC 負責「治理與交付」。三者不可混為一談。

flowchart TB
    subgraph L["能力培養：freeCodeCamp"]
        L1[Web / Programming / CS / SQL / Git 基礎]
    end
    subgraph A["工程協作：AI Agent"]
        A1[理解 / 規劃 / 實作 / 測試 / 文件]
    end
    subgraph S["治理與交付：Enterprise SDLC"]
        S1[需求 → 分析 → 架構 → 設計 → 開發 → 測試 → 安全 → 部署 → 維運]
    end
    L -->|工程師具備判斷力| A
    A -->|在規範與關卡內運作| S
    S -->|回饋能力缺口| L

42.2 SDLC 各階段對照

42.3 AI 產出的品質關卡

AI 產出
  ↓ 自動：lint / type-check / unit test / SAST / 秘密掃描
  ↓ 人工：Code Review（至少 1 位非作者）
  ↓ 自動：integration / E2E / SCA（相依套件漏洞）
  ↓ 人工：高風險變更 Human Approval（第 39.4 節）
  ↓ 部署：Staging → Production（變更管理）

42.4 實務注意事項

• AI 產出的程式碼在 SDLC 中與人寫的程式碼適用完全相同的關卡，不因為「是 AI 寫的」而放寬，也不因此額外豁免責任：提交者對內容負全責。
• 建議在 PR 範本加入「本 PR 是否使用 AI Agent 協助？使用範圍？」欄位，便於追蹤與改進。

43. PM / SA / Architect / Developer 使用指南

43.1 PM

43.2 SA

43.3 Developer

43.4 Architect

43.5 實務注意事項

• 各角色都應至少完成一次「用 AI Agent 分析 freeCodeCamp Repository」的練習（Lab 9 簡化版），建立對 AI 能力與限制的共同認知。

44. 常見錯誤

44.1 Do Not Misuse

錯誤 1

❌ 學完 freeCodeCamp 就能直接成為 Senior Engineer。

✅ 正確：freeCodeCamp 是重要學習資源，但 Senior Engineer 還需要：

• Project Experience
• Architecture
• Design
• Testing
• Security
• Production Experience
• Team Collaboration

錯誤 2

❌ 用 AI 快速完成 freeCodeCamp 認證，可以節省訓練時間。

✅ 正確：違反 Academic Honesty Policy，認證可能被撤銷；而且跳過了真正要培養的能力。AI 用在「理解」與「延伸練習」。

錯誤 3

❌ freeCodeCamp 的程式碼範例可以直接用在公司正式系統。

✅ 正確：教學範例為了聚焦概念，常省略錯誤處理、安全、日誌、效能考量。只能當作學習參考。

錯誤 4

❌ freeCodeCamp 用 Gatsby / Fastify / MongoDB，所以公司也應該用。

✅ 正確：技術選型取決於自身需求與限制，必須經過評估並寫成 ADR。

錯誤 5

❌ 有了 AI Agent，工程師不需要學基礎。

✅ 正確：AI Agent 讓「產生程式碼」變便宜，但讓「判斷程式碼是否正確」變得更重要。基礎能力是判斷力的來源。

錯誤 6

❌ 把整個 Repository 丟給 AI，它就會懂。

✅ 正確：需要 Context Engineering（第 26 章）：精選相關內容、提供可執行的指令與明確規則。

錯誤 7

❌ AI 說測試都通過了，所以功能正確。

✅ 正確：要檢查測試本身是否正確、是否被修改來配合實作、斷言是否夠強。

錯誤 8

❌ freeCodeCamp 是 Framework Migration 工具。

✅ 正確：它是基礎能力來源，並提供可觀察的升級實踐案例；實際遷移要依第 41 章 Playbook 與官方 Migration Guide。

44.2 實務注意事項

• 把本章內容放進新人訓練的第一堂課，比事後糾正更有效。

45. 限制與風險

46. FAQ

46.1 學習與認證

Q1：freeCodeCamp 真的完全免費嗎？

課程與認證免費。組織由捐款支持（官方 README）。

Q2：公司是 Java 技術棧，還值得用 freeCodeCamp 嗎？

值得。HTML / CSS / JavaScript（前端）、SQL、HTTP / REST、Git、演算法都是跨語言的基礎能力；框架部分由內部課程補足。

Q3：可以用 AI 寫 freeCodeCamp 的認證專案嗎？

不可以。官方 Academic Honesty Policy 規定除非課程明確允許，否則不得使用 AI 產生解答。

Q4：舊版（Legacy）認證還有效嗎？要重考嗎？

官方表示 Legacy 認證至少有效到 2028 年，之後可能延長；想升級的人可以完成新版專案並通過新考試。舊課程已移到 /learn/archive/（詳見 13.4 節）。

Q5：新制認證考試怎麼考？公司電腦可以考嗎？

完成 5 個必要專案後，下載官方開源的 Exam Environment 桌面 App 應考，約 50 題，不需要到考場（13.3 節）。公司電腦若禁止安裝軟體，請先向 IT 申請白名單，或改用個人電腦。

Q6：平台內建的 Socrates AI 提示，算不算違反 Academic Honesty？

不算。Socrates 是平台提供的功能，設計上只用提問引導，不給答案。違反政策的是用外部 AI 產生認證專案的解答（13.5 節）。

Q7：每張認證要花多少時間？

官方公告每張 Checkpoint Certification 約 300 小時。以每週 8–12 小時計算，大約需要 6–9 個月（37.7 節）。

Q8：Front End Libraries、Back End 新認證上線了嗎？

官方預定 2026 年上線。請以 freecodecamp.org/learn 實際顯示為準，本手冊標為 ⚠️ 需確認目前版本。

Q9：freeCodeCamp 的課程多久更新一次？

Repository 幾乎每天都有 commit。重要課程變動請關注官方 News 與 Forum 公告。

46.2 環境與開發

Q10：本機一定要用 WSL2 嗎？

Windows 使用者依官方文件必須使用 WSL2。無法安裝時可改用 GitHub Codespaces。

Q11：為什麼 pnpm install 失敗？

最常見原因是版本不符（需 Node 24、pnpm 10）或網路限制。詳見第 34 章。

Q12：Codespaces 中 API 全部失敗？

.env 的 HOME_LOCATION / API_LOCATION 仍指向 localhost。執行 .devcontainer/codespace-env.sh 並重啟 client。

Q13：第一次貢獻開源該選什麼 Issue？

文件錯字、課程文字修正、小型測試補強等範圍小、容易驗證的 Issue。先確認無人處理，並閱讀 contribute 文件。

46.3 AI 與企業治理

Q14：用 freeCodeCamp 課程建立內部 RAG 可以嗎？

技術上可行（第 27 章），但 /curriculum 內容有版權聲明，須先經法務確認。未確認前，只索引自己的筆記與課程連結。

Q15：AI Agent 分析 freeCodeCamp Repository 會有機密外洩風險嗎？

freeCodeCamp 是公開專案，程式碼本身沒有機密；但請排除自己的 .env。這也是本手冊建議先在公開 Repository 練習的原因。

Q16：我們應該用哪一個 AI Coding 工具？

本手冊不做工具評比。請依公司核准清單與資安政策選用；第 19.5 節僅提供建議用途。

46.4 手冊維護

Q17：本手冊多久更新一次？

建議每季依官方 Repository 重新查證第 4–10、12–13、30–34 章，並更新 Documentation Status 與修訂紀錄。

47. Checklist

47.1 新進成員 Quick Start Checklist

47.1.1 第 1 週：環境與認識

• 閱讀本手冊的執行摘要、第 0–3 章與第 44 章（常見錯誤）
• 了解並同意 Academic Honesty Policy（認證專案不使用 AI 產生解答）
• 建立 freecodecamp.org 帳號並登錄 Profile 連結
• 建立 / 確認 GitHub 帳號，啟用 2FA
• Windows：安裝 WSL2、Windows Terminal、Docker Desktop（啟用 WSL Integration）
• 安裝 Node 24（node -v）、pnpm 10（pnpm -v）、Docker Compose 2.x
• Fork 並 clone freeCodeCamp（WSL 使用者放在 ~/projects）
• 設定 upstream remote，git remote -v 確認
• git submodule update --init
• cp sample.env .env
• pnpm install
• docker compose -f docker/docker-compose.yml -f docker/docker-compose.ports.yml up -d
• pnpm run seed
• pnpm run develop，開啟 http://localhost:8000 與 http://localhost:3000/documentation
• pnpm run test-api 通過

47.1.2 第 2–4 週：學習與練習

• 依職級完成第 37 章 Roadmap 的 30 天目標
• 與主管確認第一張目標認證與預計完成時間（37.7 節），並確認該認證已開放考試
• 完成 Lab 1–3
• 以 P01 Learning Prompt 學習至少 3 個概念，保留紀錄
• 用 AI Agent 產出 freeCodeCamp Repository Map，並人工驗證（第 6.4 節）
• 完成一次 Fork → Branch → Commit → PR 練習（Conventional Commits）

47.1.3 持續遵守

• 不把 .env、金鑰、公司程式碼、客戶資料放進 Prompt 或開源專案
• AI 產出的程式碼一律經人工 Review 與測試
• 破壞性指令與高風險變更經人工核准（第 39.4 節）
• 新增相依套件前確認存在、來源、授權與漏洞

47.2 AI Agent 任務前 Checklist

• 任務目標與 Acceptance Criteria 已明確
• 已決定權限等級（READ ONLY / CONTROLLED WRITE / HUMAN APPROVAL）
• 已提供 Repository Context（指引檔 / 相關檔案），已排除機密
• 已指定驗證指令（lint / test）
• 已設定 Stop Point（何時停下等確認）

47.3 AI 產出 Review Checklist

• 我能解釋每一行變更
• 行為符合 Spec / Acceptance Criteria
• 測試涵蓋新增行為，且測試未被改來配合實作
• 輸入驗證、授權檢查、錯誤處理完整
• 無硬編碼機密；日誌無個資
• 無未經核准的新相依套件
• 符合專案慣例（命名、結構、Commit 格式）
• lint / type-check / test 全部通過

47.4 手冊品質關卡（Quality Gate）

47.4.1 Research

• 已研究官方 GitHub（Repository 結構、package.json、workspace、workflows、LICENSE）
• 已研究官方網站 / README（認證、Academic Honesty Policy）
• 已研究 Repository 文件（contribute.freecodecamp.org）
• 已確認主要技術架構（Gatsby / React / Redux、Fastify / TypeBox / Prisma / MongoDB、pnpm / Turborepo）
• 已確認目前版本資訊（2026-09-29）
• 已區分舊版與現況（v9 課程 vs Legacy 認證與 Archive；已封存的 Repository）
• 已查證新制認證（Checkpoint Certification、Capstone、Exam Environment App）與 2026 路線圖（v1.1）
• 已查證相關 Repository（exam-env、socrates）與 root scripts／sample.env 完整清單（v1.1）

47.4.2 Architecture

• System Architecture（第 5 章）
• Repository Architecture（第 4、6 章）
• Frontend / Backend Architecture（第 5.1、5.2 節）
• Data Flow / Learning Flow（第 11 章）
• Certification Flow（第 13.2 節）/ Contributor Flow（第 18.2 節）

47.4.3 Development

• Installation / Configuration / Local Development（第 7–10 章）
• Testing / Build（第 10.4、24 章）
• Troubleshooting（第 34 章）

47.4.4 AI

• AI Agent / Coding / Reverse Engineering / Framework Upgrade / Refactoring / Testing / Documentation（第 19–25 章）
• AI 功能架構案例（Socrates，第 19.4 節）與 LLM Application Security（第 30.5 節）
• Context Engineering / RAG / SDD（第 26–28 章）

47.4.5 Enterprise

• SDLC / Security / OSS Governance（第 30、31、42 章）
• Developer Training / Skill Matrix / Roadmap / Governance（第 35–37 章）

47.4.6 Practical

• Hands-on Labs × 12（第 38 章）
• Prompt Library × 15（第 39 章）
• Real-world Cases × 8（第 19.7、20.3、21.4、20.4、22.4、24.3、23.3、25.3 節）
• Checklists / FAQ（第 46、47 章）
• 執行摘要、兩層目錄（章＋節）且所有錨點可連結（v1.1）

48. References

所有連結均於 2026-09-29 查證可存取。內容可能變動，請以官方最新版本為準。

48.1 freeCodeCamp Official

48.2 freeCodeCamp 官方公告（課程與認證）