Python AI Agent × VS Code × Codex × OpenSpec SDLC 30 小時實戰課程

這是整門課的標題頁，先看四個角落的方塊，代表四個核心角色，各自負責什麼、彼此怎麼連。

• 左上是 Python Runtime（Python 執行環境）——整個網站用 Python 語言寫成；
• 右上是 IDE Platform，也就是 VS Code，是寫程式跟下指令的介面；
• 左下是 AI Agent，也就是 Codex，是一個會主動讀規格、寫程式、跑測試的 AI 助手，不只是回答問題的聊天機器人；
• 右下是 Version Control（版本控制），也就是 Git，記錄每一次修改的歷史。

四個方塊之間用線連起來，代表它們要協同運作，不是各自獨立作業。下方四個標籤 Python 3.12、Flask MVC、Codex Agent、OpenSpec 是課程會用到的具體技術，其中 Flask 是 Python 的網站框架，OpenSpec 是一套先把需求寫成規格文件、再讓 AI 依規格實作的工作方法。

副標「從需求到部署，30 小時打造具備 AI 客服的網路書店」，就是整門課的終點目標。

這張是一張左右對照表，把「傳統模式」跟「新範式」放在一起比，由上往下比四件事。

• 開發起點——傳統是拿到題目就直接寫程式，新範式先寫系統願景、User Story（使用者故事，一句話描述某種使用者想達成什麼目的的最小需求單位）與驗收條件；
• AI 的角色——傳統不用 AI 或只是零散問問題，新範式讓 Codex 參與需求分析、實作、測試、除錯與 Review（程式碼審查）；
• 專案規則——傳統靠口頭約定、各寫各的，新範式把規則寫進一份叫 AGENTS.md 的文件，人與 AI 都照這份文件做事；
• 完成的判斷——傳統是「畫面看起來可以」就算過，新範式要求驗收條件逐條對照，而且 pytest（一種 Python 測試工具）要全數通過才算完成。

下方那句「你不是寫程式的機器，你是會下指令、會審查的 AI 指揮官」點出這門課真正要練的是「指揮」跟「驗證」的能力，不是打字速度。

這張投影片用三張示意畫面預覽最終成果：左邊是手機版首頁、中間是電腦版首頁、右邊是書籍列表頁。

• 三個標籤點出三個重點：①MVC（Model-View-Controller，一種把「資料」「畫面」「處理邏輯」分開管理的架構方式）與 RESTful API（API 全名 Application Programming Interface，應用程式介面，是不同程式之間互相要資料、下指令的窗口；
• RESTful 是其中一種常見的設計風格）架構——畫面上 Vue 3（一套用來做互動網頁的前端工具）透過呼叫 GET /api/v1/books 這支 API 取得書籍資料，不是把資料寫死在網頁裡；
• ②具備 Tool Calling（工具呼叫，AI 自己判斷該呼叫哪一支程式或 API 來完成任務的能力）的 AI Agent——之後上線的書店客服可以用自然語言幫使用者找書；
• ③RWD（Responsive Web Design，響應式網頁設計，同一個網站的版面會依螢幕大小自動調整）——手機上看到的是漢堡選單（右上角那個三條線的圖示，點開才會展開選單）跟單欄排列的書籍卡片，跟電腦版的多欄排列不一樣，但背後是同一套程式碼。

下面三張圖是範例網站實際跑起來的畫面：首頁的 Hero 區（網頁最上方那塊搶眼的大標題與行動按鈕區域）、書籍目錄頁，以及手機版的三種畫面。

• 這張用四張並排的卡片列出這門課的四大知識支柱，由左到右分別是：規格驅動（SDLC，Software Development Life Cycle，軟體開發生命週期）——學怎麼把需求拆成 Epic（大範疇的專案目標）、Feature（功能項目）、User Story（最小的使用者需求描述），並精通 OpenSpec 這套規格驅動工作流程；
• AI Agent 協同——學怎麼設計專案規則（就是前一張提到的 AGENTS.md）與 Agent Skill（AI 客服具備的技能模組，例如「找書」「查訂單」各是一個 Skill），並掌握跟 Codex 協作、下指令（Prompt）的技巧；
• Flask Web & API——學怎麼用 Flask 建 MVC 網站，用 SQLAlchemy（Python 常用的 ORM 工具，ORM 全名 Object-Relational Mapping，物件關聯對應，讓你用寫程式的方式操作資料庫，不用直接寫 SQL 語法）接資料庫，並做出登入、購物車、後臺這些商業邏輯；
• 品質與交付——學怎麼用 pytest 確保程式碼品質，並用 Git 快照與 Docker（把程式跟它的執行環境打包成一個可攜帶容器的工具）進行 CI/CD（Continuous Integration/Continuous Deployment，持續整合／持續部署，一種自動化測試跟上線的流程）部署。

這四張卡片其實就是後面十五堂課的四條主軸，彼此穿插進行，不是分開四段各上各的。

這張用一個循環圖說明六個核心工具怎麼互相搭配。

• 從上面看起：OpenSpec 提供 Proposal（提案）、Design（設計）、Tasks（任務清單）三份文件，驅動下面的實作；
• 中間是 VS Code，這是學員下指令、審查、驗證的地方，雙向箭頭連到右邊的 Codex Agent（以 CLI 擴充套件的形式存在，而且會遵守 AGENTS.md 訂的專案規則）；
• VS Code 往下連到 Python/Flask，實際的程式碼跑在虛擬環境 .venv（一個獨立乾淨、不會跟電腦上其他 Python 專案互相污染的執行環境）裡，並集中放在 app/ 這個套件目錄下；
• 最後左邊的 Git 負責把每一步的成果存成 Commit（提交紀錄）快照與 Tag（標籤，方便之後直接跳回某一堂課的進度）。

底部那句「核心運作法則」把整張圖濃縮成一句話：從 OpenSpec 輸入規格，Codex 執行實作，測試通過後才用 Git 提交——這個順序是固定的，不會跳過規格直接叫 AI 寫程式。

這張是一個由上而下的五層堆疊圖，說明使用者的一個操作（例如點「加入購物車」）在程式裡要經過哪幾層才會真正碰到資料庫。

• 最上面是 View（視圖層），就是使用者看到的畫面，用 Jinja2（Flask 內建的樣板語言）或 Vue 3 頁面呈現；
• 往下是 Controller（控制層），分成 app/controllers/（給一般網頁用）跟 app/api/controllers/（給 API 用），負責接收請求、做路由驗證，右邊特別標出 AI 客服 Agent 也是透過 Tool Calling 從這一層接進系統，跟一般使用者走同一道門；
• 再往下是 Service（服務層），放商業規則跟交易管理的邏輯，例如「庫存夠不夠」這種判斷；
• 再往下是 Repository（資料存取層），專門負責用 ORM 查詢資料；
• 最底層是 Model（資料模型層），定義資料表長什麼樣子，底層資料庫可以是 SQLite（開發階段用的輕量資料庫）或 SQL Server。

右上角的警示標語是這張圖的重點：「嚴禁越級打怪」，意思是相依方向只能由上往下——舉例來說 Controller 絕對不能跳過 Service 直接查資料庫，每一層只能呼叫自己正下方那一層，不能跳關，也不能反過來被下層呼叫。

這張流程圖把 15 堂課依序拆成五個里程碑，由左到右、由上到下走。

• M1 需求與規格（Session 01–02）對應 SDLC 裡的「需求分析」階段，產出願景文件、OpenSpec 規格、驗收條件；
• 接著分岔成三塊同時進行、但都屬於 SDLC 的「系統設計、開發與整合」階段——M2 系統骨架（Session 03–06）做 Flask MVC、資料庫、書籍 API；
• M3 會員與 Agent（Session 07–09）做登入權限、Agent Skill、客服 Agent；
• M4 商業功能（Session 10–12）做搜尋推薦、購物車訂單、後臺管理；
• 最後匯流到 M5 品質與交付（Session 13–15），對應 SDLC 的「測試、部署與驗收」階段，做測試、部署、成果驗收。

整張圖其實就是把軟體工程教科書上的 SDLC 五階段，對照到這門課實際的堂數安排。

這張用節點跟箭頭畫出 15 堂課之間誰要先完成、誰才能開始的關係。

• 最左邊 S01（專案導入）到 S06（RESTful API）是一條必經的主線，一路往右，每一堂都要接在前一堂的成果上；
• 走到 S06 之後，圖形分成上下兩條支線同時進行——上面是「AI Agent」支線：S08（Agent Skill）→S09（Agent 整合）→S10（搜尋推薦）；
• 下面是「會員與交易」支線：S07（登入權限）→S11（購物車訂單）→S12（後臺管理）。

兩條支線互不相依，可以並行，但兩條都做完之後才會匯流到最右邊的 S13（測試）→S14（部署）→S15（期末整合）。右下角那句提示很實用：「進度落後免擔心！切換至對應堂數的 Git Tag 快照，一秒同步環境，直接接續實作」——也就是說如果卡在某一堂沒做完，不必從頭重做，直接載入上一堂課結束時的快照就能接著做下一堂的任務。

這張甜甜圈圖把每一堂課固定的 2 小時拆成六個階段，圖上的弧形大小就是時間長短的比例。

• 最先是回顧與任務說明（15 分鐘），確認上一堂的專案還能正常啟動、說明這堂的驗收條件；
• 接著是概念講解與架構示範（25 分鐘），用圖表講解這堂要修改哪幾層；
• 佔比最大的一塊是講師示範與 Codex 協同開發（50 分鐘），講師實際下 Prompt 指揮 Codex 分階段完成實作並通過測試；
• 然後是學員實作與問題排除（25 分鐘），換學員自己動手做、講師巡堂協助；
• 最後兩塊各只有 5 分鐘，分別是成果檢查與提交（執行 Pytest、Git commit）和任務交代與文件更新（交代作業、把文件跟程式對齊）。

六個階段合起來剛好是「回顧 → 理解 → 看示範 → 自己做 → 檢查 → 交代」的完整循環，每一堂課都用同一套節奏跑一次。

這張用四個方塊由左到右畫出 OpenSpec 的標準流程。

• 第一步是提案 Propose，用指令 $openspec-propose 產生 tasks.md（任務清單）與 design.md（設計文件）兩份文件，這個階段明確標示「不可修改程式碼」，只能寫規格；
• 第二步是驗證 Validate，用 openspec validate 做嚴格的規格格式檢查，這一步是道閘門，格式沒過就不能往下走；
• 第三步是實作 Apply，用 $openspec-apply-change 依 tasks.md 上的任務清單一項一項小步開發，不是一次全部生完；
• 第四步是歸檔 Archive，用 $openspec-archive-change 把這次的變更合併成正式規格，並且 commit 進 Git。

圖的上方有一條紅色回頭箭頭，標著「pytest 或人工驗證未通過 ⇒ 退回審查與實作」——意思是如果測試沒過或人工檢查發現問題，流程會被打回第二、三步重做，不會硬著頭皮往下走。每個方塊角落還畫了一個鎖頭圖示，暗示這是一套有紀律、一步一步鎖住的流程，不能跳步驟。

這張投影片列出跟 Codex 協作時，一個好的 Prompt（下給 AI 的指令）要包含的三個要素，由上到下排列。

• 第一是 Context（情境）——先給 AI 需要的先備知識，例如告訴它「請閱讀 AGENTS.md 與 specs/02-book-catalog.md 的 F-02.1」，讓它知道要參考哪些檔案裡的哪個段落；
• 第二是 Constraint（限制）——畫出界線，講清楚什麼不能做，例如「只修改 templates 與 custom.css，不可使用 CDN（內容分發網路，這裡指不能從外部網址載入套件）」；
• 第三是 Expected Output（預期產出）——定義完成的標準跟怎麼驗證，例如「列出修改檔案，執行 pytest 並貼上結果」。

每一要素旁邊都用不同顏色的方框裝著一句範例句，方便直接照著套用。下方那句結語「AI 產碼極快，但『規格清晰度』決定了程式碼品質」呼應第一張投影片的結尾——講清楚要什麼，比會不會打字更重要。

這張是一張左右對照表，中間欄是抽象的架構概念，左右兩欄是網路書店（預設專案）跟咖啡店（彈性替換專案）各自的具體做法，由上到下比四件事。

• Model（資料）這一列——書店是 Book（書籍，含 ISBN 書號、庫存），咖啡店對應 Menu Item（菜單項目，含冷熱、甜度冰塊選項、每日供應量）；
• Workflow（流程）這一列——書店是「購物車 → 宅配訂單」，咖啡店是「點餐車 → 外帶訂單」或「內用時段訂位」；
• AI Agent Intent（AI 客服要判斷的使用者意圖）這一列——書店的客服要聽懂「找書、查訂單、推薦初學者書籍」，咖啡店的客服要聽懂「推薦飲品、依預算點餐、查訂位狀態」；
• Agent Skill 這一列——書店有 book-search、order-query 這些技能，咖啡店對應 menu-search、reservation。

下方提示「底層架構不變！先改 vision.md（願景文件）與 Specs，再讓 AI 依規格調整程式」點出這張圖真正的重點：換專案主題不代表要重寫整套系統，只要規格文件寫清楚，分層架構、API 規範跟測試方法都能直接沿用。

這張投影片上半部是一條時間軸，由左到右排出 s01 到 s07 七個節點，每個節點就是一個 Git Tag，代表課程進行到那一堂結束時的狀態；下方括號註明這些是「無 .git 的獨立資料夾純淨快照」——意思是每個快照資料夾本身不含版本歷史，只是那一刻的程式碼原貌，要看完整歷史得回到主要的 Git 儲存庫。

• 下半部是「啟動四部曲」，列出重新啟動任何一份快照該依序執行的四個步驟：第一步檢查環境，跑 python tools/check_env.py 確認電腦裝好該裝的工具；
• 第二步隔離環境，跑 python -m venv .venv 再 pip install -r requirements.txt 安裝套件，而且每次切換到不同快照都要重新建立，不能共用；
• 第三步資料庫就緒（Session 05 起才適用），跑 flask db upgrade 建資料表結構，再 flask seed 灌入範例資料；
• 第四步啟動與測試，跑 flask --app run.py run 開網站，再跑 python -m pytest 確認測試全數通過。

這張用三欄表格列出期末驗收的 12 個檢核點，分成三大類。

• 左欄是基礎系統（Infrastructure）6 項：正常啟動（首頁與 /api/health 健康檢查 API 都要能正常回應）、前後端 API 正常通訊、會員註冊登入與權限控管、關鍵字與分類書籍搜尋、購物車與訂單建立、管理員後臺維護；
• 中欄是 AI 協同（AI Integration）3 項：準確判斷搜尋／推薦／查詢意圖、正確呼叫 API 與 Tool Calling、安全處理錯誤輸入與例外（例如有人故意問客服洩漏系統提示詞，也要能安全擋下）；
• 右欄是工程品質（Engineering Quality）3 項：OpenSpec 規格與驗收條件完整、Pytest 測試案例全數通過、Git 歷程完整與 Docker 部署文件。

三欄前面都打了綠色勾勾，代表這是範例專案 bookstore-agent 實際做到的完成狀態，同時也是學員自己專案最後要對照檢查的清單。

這張是模擬終端機（命令列視窗）畫面的結語。

• 第一行問「準備好啟動你的專案了嗎？」；
• 第二行示範打入指令 python tools/check_env.py，就是前一張投影片啟動四部曲的第一步，用來檢查開發環境是否就緒；
• 第三行是這支指令跑完的輸出 [System Check] ... All systems GO.（系統檢查……一切就緒），代表環境檢查通過；
• 接著兩行文字慢慢浮現：「從今天起，你不再只是寫程式的人，而是主導產品與 AI 協同開發的架構師」；
• 最後一行是「Let's Code!」，搭配一個還在閃爍的游標，像是在邀請學員現在就動手開始這趟 30 小時的旅程。

這張畫面呼應開場第一、第二張投影片提到的典範轉移——整門課想傳達的角色轉變，從頭到尾說的是同一件事。

海報用樂高積木比喻這堂課：一個學員和一個 AI 機器人角色，一起把導引專案 bookstore-agent（網路書店）打好地基，分成開發工具與專案基礎兩疊積木。

• 開發工具疊：Python 3.12（程式語言）、VS Code（編輯器）、Codex Agent（AI 協同開發代理）、Git（版本控制）、虛擬環境（隔離套件用，Session 03 才會建立）。
• 專案基礎疊：README.md、AGENTS.md、系統願景文件、Git 儲存庫、環境檢查表，這五樣才是這堂課真正要產出的成果，不是網站程式。

另一張標題投影片把四個角色畫成圓角方塊：Python 寫程式、VS Code 當工作台、Codex 是會主動動手做事的 AI 隊友、OpenSpec（規格驅動開發工具）先寫規格再實作。

這張左右對照表，把「傳統開發」跟「AI 協同開發」放在一起比，由上往下比四件事，看開發者的角色怎麼從實作者變成架構師。

• 開發者角色——傳統是逐行撰寫程式、速度受限個人；AI 協同開發把開發者變成需求定義者、規則制定者與審查者。
• 撰寫程式——傳統靠自己一行一行打；AI 協同讓 Codex（AI Coding Agent）依 Prompt（提示詞指令）產生初稿，人類專注設計與審查。
• 專案規則——傳統靠團隊口頭約定或 Code Review（程式碼審查）時提醒；AI 協同寫進 AGENTS.md，讓 Agent 每次工作前都強制讀取。
• 驗證方式——傳統依賴個人經驗與手動測試；AI 協同必須以明確的驗收條件與測試判斷，不可盲信 AI 產出的內容。

一般聊天式 AI 只會回答問題；AI Agent（AI 代理）會為了完成任務自己決定下一步、呼叫工具，並依工具回傳結果調整做法，這張圖畫出它的六個階段。

• 理解任務——讀取 Prompt 裡的【Context】背景與【Constraint】限制，Prompt 越具體，Agent 越不需要猜測。
• 規劃——列出要改的檔案與步驟，例如先確認專案目前的檔案結構，再依需求撰寫 README.md，人類可在此時中止或修正方向。
• 使用工具——讀檔、執行指令、編輯檔案，畫面上會顯示 Explored（List .）、Ran（git status）、Edited README.md 這類紀錄。
• 觀察結果——工具的回傳結果會改變 Agent 的決策，例如發現專案目前尚無程式碼，就調整接下來的做法。
• 修正與回報／人類審查——沒達成目標就調整計畫或內容再跑一輪；達成目標就摘要成果，回報給人類審查，而不是自己就算數。

這張圖由上往下畫出協作關係：開發者站在最上層，底下依序是規格與規則、Codex Agent，最下層是三支實際做事的基礎建設。

• 開發者（定義需求、審查與驗收）——透過 OpenSpec 提供上下文（規格與驗收條件），並用 AGENTS.md 約束 Codex 的行為，這條線是雙向的。
• OpenSpec（規格與驗收條件）與 AGENTS.md（專案規則）——兩者都交給下層的 Codex Agent 讀取，一個管「要做什麼」，一個管「不能做什麼」。
• Codex Agent（CLI 或 IDE 擴充套件）——讀寫檔案、執行指令，同時也會把差異攤開來讓開發者檢視，不是關起門來自己動手。
• VS Code（工作區）、Python + Flask（網站與 API 程式碼）、Git Repository（版本紀錄）——這三塊是 Codex 實際動手的地方，最後審查通過才提交進 Git。

在寫任何程式之前，這門課先用一份系統願景文件回答三個問題：為什麼要做、為誰而做、這一期做到哪裡，答案取自範例專案的 docs/vision.md。

• 本期範圍（In Scope）五項：會員與權限、書籍分類與搜尋、購物車與訂單、後臺管理、AI 書店客服 Agent，這些是這 30 小時要做完的東西。
• 暫不處理（Out of Scope）三項：線上金流（改用模擬付款代替）、物流串接、多語系與多幣別，這些明確排除在外，不會出現在最終網站裡。

為什麼要特別寫「暫不處理」清單？因為把界線寫清楚，Codex 在後續實作時才不會自作主張加上金流或多語系功能，Session 02 拆解需求時也會拿它排除不需要的需求。

兩份文件都放在專案根目錄，但讀者完全不同：README.md 是給人看的專案說明，AGENTS.md 是給 AI Agent 看的工作規則。

• 目標受眾——README.md 給開發者、老師、使用者看；AGENTS.md 給 Codex 等 AI Coding Agent 看，兩邊要的資訊不一樣。
• 目的——README.md 讓人快速了解專案是什麼、怎麼開始；AGENTS.md 讓 Agent 每次工作都遵守相同的架構限制與規則。
• 寫作風格——README.md 走介紹性、友善易讀；AGENTS.md 要命令式、具體、可被嚴格檢查，例如明講「Service 禁止使用 request」。

AI 的行為準則必須被「硬編碼」（hardcoded，寫死在檔案裡）在工作區中，不要寫空泛口號，要寫可以驗證的規則。

終端機示範執行 python tools/check_env.py（範例專案內建的環境檢查程式），一次列出各工具版本；畫面上的版本號只是示範截圖，不是硬性規定。

• 步驟 1 安裝與檢查環境——必要工具（Python 3.11 以上、pip、Git、VS Code、Node.js、Codex CLI、OpenSpec）全部顯示勾號，Docker 與虛擬環境可以是三角形。
• 步驟 2 建立專案與 Git——執行 git init -b main 初始化倉庫，並建立 .gitignore 排除 .venv/、*.db、.env 這類不該進版本控制的檔案。
• 步驟 3 VS Code 建議套件——建立 .vscode/extensions.json 與 settings.json，讓全班用同一套擴充套件與工作區設定，減少「我的電腦跟別人不一樣」的問題。

extensions.json 裡的 openai.chatgpt 套件，就是在 VS Code 裡直接使用 Codex Agent 的入口；settings.json 則預先綁定 UTF-8 編碼，避免中文註解變亂碼。

課程規定跟 Codex 對話要用三段式 Prompt：【Context】背景、【Constraint】限制、【Expected Output】預期產出，把 AI 當成執行特定邏輯的編譯器，而不是用聊的碰運氣。

• Context（背景）——告訴 Agent 專案是什麼、目前在哪個階段，例如「使用 Python 3.12、Flask 3、OpenSpec 規格驅動開發」。
• Constraint（限制）——劃定 Agent 不可以做的事，這堂課最重要的一條是「目前尚未有程式碼，不要虛構已完成的功能或指令」。
• Expected Output（預期產出）——說清楚要交付什麼、交付後要做什麼，例如「產生根目錄的 README.md，完成後列出檔案大綱讓我確認」。

右邊的終端機示範畫面裡，Codex 先執行 ls -a 跟 git status 確認專案是空的，再打開 README.md 開始編輯，正好對應理解任務、規劃、使用工具三個階段。

產生 AGENTS.md 前的 Prompt 要求說明分層架構、規定工作流程（先讀規格、先說計畫、小步提交、驗證結果），並包含命名規範、常用指令、安全規範與完成定義。

• 人工審查重點一：內容是否虛構了不存在的功能、指令或檔案，這是三項檢查裡最容易踩的雷。
• 人工審查重點二：範圍（In Scope／Out of Scope）是否與課程規劃一致，避免 AI 自己加了暫不處理的功能。
• 人工審查重點三：AGENTS.md 的規則是否具體、可被檢查，而不是「請寫出高品質的程式碼」這類空泛口號。

接著以 README.md 為基礎，產出這堂課真正的正式產出 docs/vision.md（系統願景文件），內容包含問題與機會、目標使用者、本期範圍與里程碑，作為 Session 02 拆解需求規格的依據。

最後一步把工作目錄裡的檔案，經過 git add . 送進暫存區，再用 git commit 提交進本機儲存庫，畫面上示範的提交訊息是 chore: 專案初始化。

• 提交前先跑 git status --short 看看 Codex 到底改了哪些檔案，養成這個習慣才能在問題進版本紀錄前先發現。
• 不要讓 Agent 連續修改大量檔案後才一次檢查：每完成一個小任務就 Review（審查）並 Commit（提交）一次，這就是「小步提交」。
• 提交後執行 git log --oneline --decorate 確認出現一筆提交紀錄，再跑一次 git status --short 應該完全沒有輸出。

完成這堂課後達成三項產出：開發環境驗證、專案規則確立、系統願景鎖定，下一堂 Session 02 會把願景拆解成 Epic、Feature、User Story 與可測試的驗收條件。

這堂課的講師示範共 7 個步驟，範例路徑是 C:\course\bookstore-agent；macOS／Linux 的建立資料夾指令略有不同，內容以下方各步驟為準。

1. 步驟 1 安裝與檢查開發環境：Python、VS Code、Git、Node.js 各自下載安裝，Codex CLI 與 OpenSpec 用 npm install -g @openai/codex 與 npm install -g @fission-ai/openspec 安裝，登入後跑 python tools/check_env.py 檢查全部工具。
2. 步驟 2 建立專案資料夾與 Git Repository：建立 bookstore-agent 資料夾後執行 git init -b main，第一次用 Git 的電腦要先 git config user.name "你的名字"，再建立 .gitignore。
3. 步驟 3 以 VS Code 開啟並安裝建議擴充套件：建立 .vscode/extensions.json 與 settings.json，執行 code . 開啟資料夾，依提示安裝八個建議擴充套件。
4. 步驟 4 使用 Codex 產生 README.md：在整合式終端機啟動 Codex CLI，依三段式 Prompt（Context、Constraint、Expected Output）請它產生 README.md 並列出檔案大綱確認。
5. 步驟 5 產生 AGENTS.md 並人工審查：請 Codex 讀 README.md 後產生 AGENTS.md，再依三項人工檢查重點（有沒有虛構、範圍是否一致、規則是否可檢查）逐項審查。
6. 步驟 6 撰寫系統願景文件：依 README.md 請 Codex 產生 docs/vision.md，內容涵蓋願景陳述、問題與機會、Persona、範圍、成功指標、限制與假設、里程碑。
7. 步驟 7 第一次 Git 提交：先跑 git status --short 看清楚有哪些檔案，再執行 git add . && git commit -m "chore: 專案初始化"，最後用 git log --oneline --decorate 確認。

動手做之前先看完成標準：以下是課堂會實際檢查的 4 項任務（進階挑戰為第 5 項），以及本堂全部產出的檢核清單。

• 實作 1 完成開發環境檢查：安裝好本堂所需工具、執行 codex login 登入，跑 python tools/check_env.py，必要工具全部顯示勾號。
• 實作 2 建立專案資料夾與 Git Repository：建立自己的 bookstore-agent 專案，VS Code 左下角要顯示 main 分支，建議擴充套件全部安裝好。
• 實作 3 以 Codex 產生 README.md 與 AGENTS.md：README.md 的快速開始不能有不存在的指令，AGENTS.md 要包含分層架構表、工作流程與完成定義。
• 實作 4 撰寫系統願景文件並完成第一次提交：docs/vision.md 包含願景、Persona、範圍、里程碑，執行 git add 與 git commit 後，git status --short 沒有任何輸出。
• 實作 5（進階挑戰）改寫為咖啡店管理系統：自行撰寫三段式 Prompt，讓 Codex 產生咖啡店版本的 docs/vision.md，並比較兩個系統在 Persona 與資料模型上的差異。

產出檢核表共 8 個項目，全部打勾才算這堂課真正做完：

• ☐ Git Repository：.git 資料夾存在、狀態列顯示 main，git log --oneline --decorate 有提交紀錄。
• ☐ 版本控制排除清單：.gitignore 包含 .venv/、*.db、.env。
• ☐ VS Code 工作區：.vscode/ 兩個設定檔存在，開啟專案會跳出建議擴充套件提示。
• ☐ 專案說明 README.md：含功能範圍表（Session 01–15）、技術選型、快速開始、文件索引，沒有虛構指令。
• ☐ Agent 規則 AGENTS.md：含工作流程、分層架構表、命名規範、常用指令、安全規範、完成定義。
• ☐ 系統願景文件 docs/vision.md：含 In Scope／Out of Scope 與里程碑，範圍與課程大綱一致。
• ☐ 開發環境檢查表與 tools/check_env.py：執行後必要工具全部通過。
• ☐ 第一次提交：git status --short 無輸出，提交內容包含上述檔案。

海報用樂高場景把整堂課畫成一條生產線。左上角的人腦子裡一團亂線：想做線上書店、加上 AI 客服、可以推薦書籍嗎、還要會員與訂單。右邊的機器人拿著規格在寫程式。中間那句話就是本堂主軸——先寫清楚，再開始開發。

• 三個橫幅是這堂課的三個階段：需求拆解（釐清想法、化為結構）、規格驅動（文件先行、AI 理解、團隊對齊）、驗收導向（可測試、可驗收、交付有保障）。
• 中段那排彩色積木是需求的流動方向：需求 → 願景 Vision → Epic → Feature → User Story → Task → 設計 → 實作 → 驗收。
• 底下四塊是這堂課會實際產出的四份文件：proposal.md（專案願景、目標與價值、成功指標）、spec.md（需求規格、功能描述、驗收條件）、design.md（系統設計、架構圖、技術方案）、tasks.md（任務拆解、實作清單、優先順序）。
• 右下角的範例專案是 bookstore-agent（書香書店），整個課程都用它當導引專案，這堂課還不會寫網站程式。

標題頁下方掛著三個標籤：Session 02、Spec-Driven Development（規格驅動開發）、SDLC（軟體開發生命週期）。副標是「Python AI Agent × VS Code × Codex 的精準協同作戰」。

依教案第一章，這堂課在整個課程裡的位置是把上一堂的系統願景變成可以驗收的需求，再用 OpenSpec 把下一步要做的事寫成 Codex 能執行、人能審查的變更提案。授課時數 2 小時（課程第 3–4 小時），先備知識是 Session 01 的專案初始化與 AGENTS.md。

這張圖左右對照。左邊是一支手機，上面只有一則訊息：「幫我做購物車」。右邊是一張爆炸開來的網狀圖，代表 AI 收到這句話之後在腦內展開的所有可能性，其中三個節點被特別拉出來標成問題：

• 未登入能加入嗎？
• 數量上限多少？
• 庫存不足回傳什麼 HTTP 狀態碼？

教案 5.1 節把這件事講得更直白：Codex 一定會產生程式碼，但必須自己猜，每個猜測都可能與你的想法不同，而且很難在大量程式碼裡發現。圖下方那句結論是：只給一句話，它不會做出你要的系統。

這是一張三欄對照表，左欄是比較面向，右邊三欄分別是傳統開發（灰）、純 Prompt 開發（橘）、OpenSpec 規格驅動（綠）。四個面向由上往下：

• 需求來源——傳統是散落的會議紀錄與口頭溝通；純 Prompt 是一次性的對話內容；規格驅動是正式的 specs/ 與變更提案。
• AI 工作範圍——傳統沒有 AI；純 Prompt 由 AI 自行推測（投影片直接標成高風險）；規格驅動由 Proposal 與 Tasks 嚴格界定。
• 完成判斷標準——傳統靠開發者主觀判斷；純 Prompt 是「看起來能動」；規格驅動要全數通過驗收條件與 Scenario 測試。
• 變更追蹤——傳統散落於信件與訊息；純 Prompt 對話結束即遺失；規格驅動以「變更（Change）」為單位進 Git 歸檔。

教案同一張表還多一列「主要風險」：傳統是溝通落差、純 Prompt 是幻覺與範圍失控、規格驅動則是規格品質不佳時會照錯的合約施工。

圖的正中央是兩個咬合的齒輪，左右各一疊資料夾，代表同一份需求的兩種寫法。

• 左：specs/*.md（人類與產品視角）——對象是 PM、QA、開發者；內容是產品需求全貌、Epic、User Story、驗收條件；意義是系統目前「已實作」的全貌。
• 右：openspec/changes/<變更名稱>/（AI 與執行視角）——對象是 Codex（Agent）與程式碼審查者；內容是針對「本次變更」的提案、規格差異、技術決策、任務拆解；意義是精確界定 AI 這次「只能」做什麼。

教案補充 OpenSpec 的資料夾慣例還有第三塊：openspec/specs/ 放已歸檔的正式規格，變更做完之後會歸檔進去。

這張圖畫成五個由大到小、一層包一層的方塊，右邊各給一個購物車的實際編號當範例：

• Epic（史詩）——大型商業目標，跨多個 Session。範例 EP-03 購物車。
• Feature（功能）——可獨立交付的能力。範例 F-03.1 加入購物車。
• User Story（用戶故事）——「身為…我想要…以便…」，1 個 Session 內可完成。範例 US-03.1.1 加入書籍到購物車。
• Acceptance Criteria（驗收條件）——Given／When／Then，可寫成單一自動化測試。範例 AC-3 庫存不足回應 409。
• Task（開發任務）——開發者或 AI 的工作單元，0.5～2 小時。範例 T-03.1.2 CartService。

圖最下方那句是這一頁的重點，也是最容易搞混的地方：Task 是「怎麼做」（可變），User Story 是「做到什麼」（驗收合約，不可變）。

畫面是 VS Code 開著 specs/03-shopping-cart.md，左側檔案樹列出 00-project-overview 到 05-admin-management 六份規格檔，加上 AGENTS.md 與 README.md。右側用三個編號氣泡標出一條驗收條件的三段：

• 1 Given（Arrange 準備）：已登入，書籍上架且庫存為 10。
• 2 When（Act 動作）：呼叫 POST /api/v1/cart/items 數量 2。
• 3 Then（Assert 斷言）：回應 201，購物車含該書 2 本。

下方黃黑警示條是這一頁真正的重點——只寫成功路徑是無效規格，錯誤情境也要寫進去，投影片列了四個常用狀態碼：

• 401（未登入）、404（資源已下架）
• 409（庫存不足／資料衝突）、422（數量超出邊界）

六個拼圖塊圍成一個六角形，每一塊是一個自我檢查的問題：

• I — Independent（獨立）：能單獨開發與交付嗎？
• N — Negotiable（可協商）：保留空間，沒把實作細節寫死？
• V — Valuable（有價值）：「以便…」有寫出用戶真實好處？
• E — Estimable（可估算）：沒有待確認的模糊地帶？
• S — Small（夠小）：一次 Session 能做完？
• T — Testable（可測試）：能否轉換為明確的自動化測試？

教案把這六問放進學員實作 2「以 QA 角度互評驗收條件」：跟隔壁組交換規格，扮演 QA 審查對方的驗收條件，每份規格至少要收到 3 項具體意見，不可以只寫「很好」或「不夠清楚」。

四個方塊由左到右串成一條流水線，顏色本身就是分工說明：青色（Cyan）＝ AI 執行，綠色（Emerald）＝ 人類介入。上方還有一條橘色回頭箭頭，寫著「格式錯誤則退回重議」。

• 1. Propose（提案）— AI 執行：跑 $openspec-propose，產生 4 份規劃文件。
• 2. Validate（驗證）— 人類介入：人類審查加上 CLI 嚴格驗證 openspec validate --strict。
• 3. Apply（實作）— AI 執行：AI 依 tasks.md 撰寫並測試程式碼（$openspec-apply-change）。
• 4. Archive（歸檔）：將本次規格正式併入系統總藍圖。

本堂課只做到第 1、2 階段——Apply 是下一堂 Session 03 的事。

四宮格，每一格是一份文件加上它負責的問題：

• proposal.md（What & Why）——改了哪些能力（Capabilities）？影響範圍（Impact）為何？新增了什麼套件？
• spec.md（Delta ／ 系統行為）——本次變更的 Requirement（SHALL／MUST）；明確的 WHEN／THEN 情境（Scenario）。投影片特別註明：行為合約，不涉實作。
• design.md（How ／ 技術決策）——採用哪些框架？放棄哪些替代方案（Trade-offs）？
• tasks.md（Step-by-step）——按架構分層排列的工作清單；每一條都必須包含明確的「驗證方式」。

畫面中央是一段 YAML 設定，左右兩個氣泡各解釋一半：

• context（全域背景）——AI 產出每一份文件時都會參考，確保技術棧不跑偏。範例內容：Language: zh-TW、Tech stack: Flask 3 / Vue 3, MVC、API conventions: prefix /api/v1。
• rules（專屬規則）——強制規定 AI 產生特定文件時的邏輯順序與格式。範例：proposal: 必須引用需求編號、tasks: 必須依照分層排序。

教案提醒一個實務坑：初始化時若沒有加 --language zh-TW，Codex 產生的 OpenSpec 文件會是英文，要回到 context 補設定。

中間是一段 delta spec 的實際內容，三個箭頭各指出一個重點：

• 絕對守則——避免使用 may／should，強制約束行為。範例：系統 SHALL 提供 GET /api/health…。教案補充：若描述寫成「系統提供…」而缺少 SHALL／MUST，--strict 會回 WARNING 並驗證失敗。
• 必須剛好四個井字號——#### Scenario: 名稱。投影片直接標明這是本課程最易踩坑的驗證錯誤點；只寫三個 ### 會得到「must include at least one scenario」。
• 安全邊界——必須規定異常行為與例外處理。範例：THEN 系統回應 503… 且回應 MUST NOT 包含例外細節。

圖用一條被扯斷的鎖鏈把兩件事隔開，外面纏著黃黑警示膠帶：

• 左邊：Propose 階段（$openspec-propose）。
• 右邊：程式碼實作（app/、requirements.txt）。
• 中間紅色叉叉＋警示條：只產出規劃文件，絕對不可修改程式碼！

下方還有一個處理方式：如果發現提案階段 AI 動到了 Code，立即 Git 捨棄變更，修正 Prompt 重新提案——不是手動把它改回來，是整個丟掉重來。

教案把這條線寫成可機檢的驗收：提案完成後跑 git status --short，只准列出 specs/、openspec/、.agents/、docs/ 底下的異動。

左邊是終端機畫面，三個氣泡標出三個步驟：

• 1 觀測變更全局：openspec list。
• 2 確認 4/4 份文件齊全：openspec status --change add-flask-skeleton。
• 3 嚴格檢查格式合法性：openspec validate add-flask-skeleton --strict。

右邊是一顆發光的腦，標題「最後一哩路（人類 QA）」，列出三件指令做不到的事：

• 指令只檢查「格式」，不管「邏輯」。
• 審查 Impact 影響範圍是否正確？
• Tasks 的執行順序是否符合 config.yaml 的分層預期？

五條打勾清單，全部通過才蓋下右下角那枚印章「git commit — 合約鎖定，準備實作！」：

• 需求已精準拆分為獨立的 Epic → Task。
• 每一條 User Story 皆包含正向與異常／邊界的 Given／When／Then。
• config.yaml 已注入專案架構與技術棧。
• $openspec-propose 產生了 4 份規劃文件且絕對未動到程式碼。
• openspec validate --strict 綠燈通過，並通過人類邏輯審查。

這堂課分五組，分別負責 specs/01～specs/05。四項任務如下：

• 實作 1 撰寫自己負責的 Feature 規格：依編號規則把 Epic 拆到 User Story 與驗收條件，每個 US 至少 2 條 Given／When／Then。
• 實作 2 以 QA 角度互評驗收條件：與相鄰組別交換規格審查。先請 Codex 列出「模糊、無法寫成自動化測試」的條件與缺少的邊界情境，但不要直接修改檔案；審查者再自行判斷 Codex 的建議是否合理。以「原條文／問題／建議改寫」三欄整理至少 3 項意見交回原組。完成標準包含：原組要能說明哪些建議不採納及原因。
• 實作 3 建立並驗證一個變更提案：執行 openspec init --tools codex --language zh-TW .，補上 config.yaml 的 context 與 rules，用 Prompt 4 建立 add-flask-skeleton 提案。完成標準：status 顯示 4/4 artifacts complete、validate --strict 回報 valid、delta spec 至少包含一個錯誤情境 Scenario、以一個 commit 提交。
• 實作 4（進階挑戰）讓驗證失敗，再讓提案符合合約：故意把 #### Scenario: 改成 ### Scenario:、故意刪掉一個 SHALL，記錄兩種錯誤各自的訊息等級（ERROR 或 WARNING）與修正方式後還原。

本堂共 10 個產出項目，全部打勾才算做完：

• ☐ 產品需求文件 specs/00-project-overview.md：含 Epic 清單、編號規則、INVEST、NFR、API 共通規範。
• ☐ User Story：specs/01～05 各 Feature 下的 US 皆為「身為…我想要…以便…」格式，編號符合規則。
• ☐ Feature Specification：含商業規則、資料模型、API 規格、mermaid 流程圖、Task 表。
• ☐ 驗收條件：每個 US 至少 2 條 Given／When／Then，錯誤情境完整，並通過 QA 互評。
• ☐ OpenSpec 設定：openspec/config.yaml 的 context 含技術棧與架構、rules 含 proposal 與 tasks 規則，六個 skill 存在。
• ☐ OpenSpec 變更提案：openspec/changes/add-flask-skeleton/ 四份文件齊全。
• ☐ 規格驗證結果：openspec status 為 4/4、openspec validate --strict 回報 valid。
• ☐ Codex Prompt 紀錄：docs/prompts/s02-spec-prompts.md 保留本堂 Prompt 與人工審查清單。
• ☐ 專案規則更新：AGENTS.md 與 README.md 新增 OpenSpec 規格驅動流程表與常用指令。
• ☐ Git 提交：git status --short 工作區乾淨，提交訊息說明本堂產出。

評分規準分三個面向：驗收條件（25 分）——優良是全部可寫成自動化測試、錯誤情境與邊界值完整並附狀態碼與訊息，待加強是條件模糊（「正常」「快速」）或只有成功路徑；OpenSpec 變更提案（25 分）——待加強包含「提案階段修改了程式碼」；審查與提交（10 分）——優良是互評意見具體且被採納、Prompt 紀錄完整。

• 終端機顯示找不到 openspec 命令——未安裝或 npm 全域路徑尚未載入。執行 npm install -g @fission-ai/openspec，關閉並重新開啟終端機，以 openspec --version 確認。
• Codex 不認得 $openspec-propose——未以 --tools codex 初始化，或 Codex 在 init 之前就已開啟。確認 .agents/skills/openspec-propose/SKILL.md 存在，於專案根目錄重新開啟 Codex 工作階段。
• validate 回報「must include at least one scenario」——Scenario 標題只寫三個井字號。改為剛好四個的 #### Scenario: 名稱，每個 Requirement 至少一個。
• validate 出現 WARNING「should contain SHALL or MUST」——Requirement 描述寫成「系統提供…」。在描述中加入 SHALL 或 MUST（保持英文）。
• validate 回報「Change must have at least one delta」——變更資料夾中沒有 specs/能力名稱/spec.md，或沒有使用 ## ADDED Requirements 等標題。依 proposal 的 Capabilities 補上 delta spec；只有純文件或重構、沒有行為變更時，才在 .openspec.yaml 設定 skip_specs: true。

標題頁背景是一組互鎖的深藍立方積木，彼此卡合、找不到一條直通的縫——用來比喻這堂課要蓋的嚴格分層架構：每一層都卡進上下層，不能單獨抽掉。下方副標寫「打造具備高測試性、AI Agent 準備就緒的 Flask 企業級基礎」，四個標籤 [Flask 3.1]、[App Factory]、[MVC]、[Pytest] 就是本堂的四個關鍵字。

🔍 點圖放大

補充海報把同一件事畫成一疊樂高積木，由上到下正好是 View → MVC Controller → Service → Repository → Model → Database 六層，中間特別標註「商業邏輯集中 Service 層：讓業務邏輯保持純粹、可測試、可擴充、可維護」。海報右側是實際畫面：一個 bookstore-agent 書店首頁，以及一段 GET /api/health 回傳 {"status": "ok", ...} 的終端機截圖。

圖中是一疊由下往上堆的方塊，四道防線由下到上分別是：

• 隔離環境：.venv 虛擬環境，阻絕外部干擾。
• 嚴謹紀律：5 層 MVC 架構，單向相依，職責分明。
• 彈性核心：App Factory 與 Blueprints，延遲綁定與模組化。
• 自動驗證：Health API 與 Pytest 測試，確保系統健康與規格相符。

這四道防線正好對應接下來 5.1 到 5.7 節要講的內容：虛擬環境（5.1）、App Factory（5.2）與 Blueprint（5.3）合起來是彈性核心、MVC 分層（5.4）是嚴謹紀律、健康檢查與回應格式（5.6、5.7）是自動驗證。

左邊一團纏繞的紅線代表「全域環境」，右邊整齊的藍色積木代表「專屬虛擬環境 (.venv)」，中間對照表：

• 套件位置：全域是所有專案共用；.venv 是專案內專屬。
• 版本衝突：全域互相覆蓋極易崩潰；.venv 各專案獨立、互不干涉。
• 重建方式：全域難以追蹤依賴；.venv 憑 requirements.txt 一鍵還原。

下方 AI 協作守則氣泡：「明確的虛擬環境與 tools/check_env.py 腳本，能確保 AI Agent 執行指令時，絕對不會用錯直譯器。」教案補充 tools/check_env.py 的最後一列會檢查虛擬環境：未啟用時顯示「尚未啟用（Session 03 建立）」，啟用後顯示「使用中」，可以請學員啟用前後各跑一次直接看差異。

右下角終端機截圖顯示實際指令：python -m venv .venv、.venv\Scripts\activate、pip install -r requirements.txt，最後一行 Successfully installed Flask-3.1.0 Flask-Migrate-4.0.7 Flask-SQLAlchemy-3.1.1 …。macOS／Linux 的啟用指令則是 source .venv/bin/activate。

圖中畫成一條「Assembly Pipeline（組裝生產線）」：左邊 Dev／Test／Prod 三個輸入方塊，匯入中間的 create_app() 方塊，內部依序是「1. 載入設定 → 2. 設定 JSON 格式」與「3. init_extensions（延遲綁定資料庫）→ 4. register_blueprints」兩條並行的步驟，最後輸出一個「客製化 App 實體」。

下方對照表：單一全域 App 是「測試時與開發環境共用同一個實體資料庫，易互相污染」；App Factory 是「呼叫才建立，測試時可隨洗隨用獨立的記憶體資料庫 sqlite:///:memory:」。教案補充這個決策記錄在變更提案 design.md（D1）；run.py 與測試用的 tests/conftest.py 都透過同一個 create_app() 取得 app，差別只在傳入的設定名稱。

圖中央是一個菱形「Blueprint 路由器」，三條路徑往下分流：

• /（無前綴）→ main_bp → 導向首頁 HTML 視圖。
• /api（URL 前綴）→ health_api_bp → 導向 JSON 格式的後端 API。
• /static（內建）→ 導向前端離線資源（CSS／JS）。

教案補充完整對照：main_bp 變數對應名稱 main、檔案 app/controllers/main_controller.py，路由 GET / → endpoint main.index；health_api_bp 變數對應名稱 health_api、檔案 app/api/controllers/health_api.py、url_prefix="/api"，路由 GET /api/health → endpoint health_api.health。變數命名遵守 AGENTS.md 的「模組名_bp」規範。下方實務守則：「樣板中的連結一律使用 url_for('blueprint_name.endpoint')。未來若需修改路由前綴，系統將自動適應，全身而退。」

五層堆疊由上到下：

• View（Templates／Static）——負責畫面呈現。
• Controller（Page & API）——接收輸入、調度 Service；禁止在此撰寫商業邏輯或直查資料庫。
• Service（商業邏輯）——處理商業規則、例外轉換與交易管理；禁止使用 Flask 的 request 網路物件。
• Repository（資料存取）——封裝 ORM 與資料庫指令；禁止在此做任何商業邏輯判斷。
• Model／DB——定義資料表與欄位。

教案對照表把每一層落到本堂實例：app/controllers/（main_controller.py）、app/api/controllers/（health_api.py）、app/services/（health_service.py）、app/repositories/（health_repository.py），Model 這一層本堂尚未建立，要等 Session 05 才會放入資料模型。design.md 的 Risks 已預期「骨架目錄在初期看起來過度設計」，先把位置訂好，是為了讓 Codex 在後續課程產生程式時不會各自決定放置位置。

左邊是繼承關係圖：base.html（定義骨架與 block 區塊）被 index.html（繼承並填入專屬內容）以 extends 繼承，另外 partials/navbar.html（共用元件）以 {% include %} 引入到 base.html。右邊是 app/static/ 資料夾，裡面放了四個離線函式庫：Bootstrap 5、Vue 3、Axios、SweetAlert2。下方寫著：「為何不依賴 CDN？確保網路不穩時前端依然可用，且版本絕對固定不變。」

投影片沒有畫出設定檔管理的部分，以下依教案 5.5 節文字補充：設定集中在 app/config.py，以三個繼承 Config 的類別區分環境——DevelopmentConfig（DEBUG = True，本機開發預設值）、TestingConfig（TESTING = True，資料庫改為 sqlite:///:memory:，由 conftest.py 指定）、ProductionConfig（DEBUG = False）。敏感設定（SECRET_KEY、DATABASE_URL）一律從環境變數讀取，開發時可寫在不提交 Git 的 .env。

GET /api/health 進來後依序經過 API → Service check() → Repo ping()，最後對資料庫執行真實的 SELECT 1。

• 正常路徑（綠色實線）：資料庫查詢成功、沒有例外 → 組成 status ok／database ok → 回 HTTP 200（success_response），服務正常。
• 失敗路徑（橘色虛線）：資料庫拋出 SQLAlchemyError → Service 攔截例外並用 logger.exception 寫入 Server Log → 組成 status degraded／database error → 回 HTTP 503（error_response），資料庫無法連線。

下方安全規範：「失敗時，API 回應絕不拋出給前端，嚴禁洩漏資料庫連線字串或例外詳細訊息！」這條對應 design.md D4 與 AGENTS.md 第 6 節安全規範。

JSON 範例與五個欄位的說明各自用箭頭標出：

• code——HTTP 狀態碼，與標頭一致。
• success——布林值，提供最直覺的成功／失敗判斷依據。
• message——繁體中文，給人類開發者與 UI 顯示的摘要。
• data——實際資料載體，包含 app、version、status、database、time 等系統狀態與時間戳。
• errors（選用）——表單驗證失敗時的詳細明細，只有傳入時才出現。

教案附上實作：app/api/response.py 的 success_response(data=None, message="成功", code=200) 與 error_response(message, code=400, errors=None, data=None) 兩個函式，統一用 jsonify() 包裝。講師提示：大綱 Session 12 列出的統一回應格式是 code、message、data 三個欄位，本專案依 openspec/config.yaml 的 API 慣例多加 success 欄位，屬於相容的擴充。

步驟 1（開始實作）：Prompt 給 Codex——$openspec-apply-change add-flask-skeleton，請它依 tasks.md 的順序一次完成一組任務（先做「1. 開發環境」與「2. App Factory 與設定」），每完成一項就勾選 tasks.md，並回報驗證指令與結果，遵守 AGENTS.md 的分層規範。本變更共 5 組 9 項任務：開發環境、App Factory 與設定、首頁 Blueprint 與版型、健康檢查 API、整合驗證。

步驟 2（虛擬環境與套件，任務 1.1、1.2）：指令（PowerShell）依序是 python -m venv .venv、.venv\Scripts\activate、pip install -r requirements.txt（macOS／Linux 用 source .venv/bin/activate）。requirements.txt 固定版本：Flask==3.1.0、Werkzeug==3.1.3、Flask-SQLAlchemy==3.1.1、SQLAlchemy==2.0.49、Flask-Migrate==4.0.7、marshmallow==3.21.3、PyJWT==2.8.0、python-dotenv==1.0.1、pytest==8.2.0；任務 1.2 把常用指令補進 AGENTS.md 第 5 節。

步驟 3（設定檔與擴充套件，任務 2.1）：app/config.py 用三個繼承 Config 的類別區分環境，敏感設定一律從環境變數讀取；app/extensions.py 集中建立 db = SQLAlchemy() 與 migrate = Migrate()，用 init_extensions(app) 以 init_app 模式延遲綁定，避免循環匯入。db 物件在模組層級建立但尚未綁定任何 app，因此 Repository 可以安全地 from app.extensions import db，不必匯入 app 本身。

步驟 4（create_app() 與 run.py，任務 2.2）：create_app(config_name) 依設定名稱建立 Flask app，設定 app.json.ensure_ascii = False 與 app.json.sort_keys = False 讓 JSON 回應保留中文且欄位順序固定為 code、success、message、data，接著呼叫 init_extensions(app) 與 register_blueprints(app)。register_blueprints() 在函式內才匯入 Blueprint，避免 app 套件與 Controller 互相匯入。

步驟 5（首頁與版型，任務 3.1、3.2）：main_controller.py 建立 main_bp = Blueprint("main", __name__)，定義 LAYERS 清單（Controller／Service／Repository／Model 四層各自的名稱、圖示、路徑與職責），index() 函式用 render_template("main/index.html", layers=LAYERS)。base.html 定義共用版型並離線引入 Bootstrap 5、Bootstrap Icons 與自訂 CSS，用 {% include %} 帶入 partials/navbar.html 與 footer.html；index.html extends base.html，用 {% for layer in layers %} 迴圈產生四張分層卡片，不必為每一層重複寫一次 HTML。導覽列用 url_for('main.index') 與 url_for('health_api.health') 產生連結。驗證方式：任務 3.2 用瀏覽器開啟 / 看到網站名稱驗證；任務 3.1 用開發者工具 Network 分頁確認沒有外部網路請求。

步驟 6（分層實作健康檢查 API，任務 4.1、4.2）：依 Repository → Service → API Controller 的順序實作 GET /api/health。health_repository.py 的 HealthRepository.ping() 只執行 db.session.execute(text("SELECT 1"))，不判斷結果代表什麼。health_service.py 的 HealthService.check() 呼叫 repo.ping()，成功則 database = "ok"，遇到 SQLAlchemyError 就 logger.exception 記錄並把 database 設為 "error"，回傳 status、database、time 三個欄位。health_api.py 的 health() 呼叫 _health_svc.check()，資料庫正常回 success_response(data, "服務正常")，否則回 error_response("資料庫無法連線", 503, data=data)。Prompt 給 Codex 的三個 Constraint：①依分層實作；② API Controller 不可直接使用 db，資料庫錯誤只寫 Log、不可回傳例外細節；③回應一律使用 app/api/response.py 的 success_response／error_response。

左邊「真實環境」畫 App 直接連 Database；右邊「測試沙盒（Test Sandbox）」畫 create_app('testing') 指向記憶體資料庫 sqlite:///:memory:，下方一個 Mock 叉叉圖示旁寫著：「強制替換 HealthRepository.ping，主動拋出假例外（OperationalError），精準驗證 Service 是否如預期攔截並回傳 503。」右下角終端機截圖是 pytest -v 的實際執行結果，4 個測試全部 PASSED：test_home_page_shows_site_name、test_home_page_uses_local_static_assets、test_health_returns_unified_response、test_health_reports_database_error_without_details，最後一行 4 passed in 0.05s。

教案補充：tests/conftest.py 的 app fixture 用 create_app("testing") 建立 app，並在 app_context() 內 db.create_all()／結束後 db.drop_all()。Mock 的原理是用 unittest.mock.patch 把 HealthRepository.ping 換成「一呼叫就拋出 OperationalError」的假方法，OperationalError 是 SQLAlchemyError 的子類別，所以會被 Service 捕捉。注意事項：若直接執行 pytest 出現 ModuleNotFoundError: No module named 'app'，代表 pytest 找不到專案根目錄的 app 套件，要改用 python -m pytest -v -p no:cacheprovider，或使用 VS Code 的測試面板。

圓形圖分四個階段，順時針走一圈：

• 1. 實作（Apply）——讓 Agent 讀取 tasks.md 小步實作，指令 $openspec-apply-change。
• 2. 驗證（Verify）——執行 pytest 與瀏覽器雙重確認，指令 flask routes。
• 3. 歸檔（Archive）——將變更升級為正式系統規格 spec.md，指令 openspec archive。
• 4. 提交（Commit）——提交這份穩固的地基，指令 git commit。

教案把這四格展開成實際步驟：步驟 8（驗證）執行 flask --app run.py routes 列出 health_api.health（/api/health）、main.index（/）與內建的 static，再用瀏覽器開啟首頁與 /api/health 確認結果。步驟 9（歸檔）對 Codex 下 Prompt：「請執行 pytest 與 flask --app run.py routes，確認所有 Scenario 都有對應測試，全部通過後勾選 tasks.md 剩餘項目並執行 $openspec-archive-change add-flask-skeleton」；歸檔會把變更中 ADDED Requirements 的 2 個 Requirement 寫入 openspec/specs/system-health/spec.md，再把整個變更資料夾移到 openspec/changes/archive/2026-09-14-add-flask-skeleton/。步驟 10（提交）依序執行 git status --short（清單中不應出現 .venv/、instance/ 或 __pycache__/）、git add .、git commit -m "feat(s03): Flask App Factory、MVC 分層骨架與健康檢查 API"、git log --oneline --decorate。

學員實作 1：建立虛擬環境並啟動 Flask 骨架——任務：在自己的 bookstore-agent 專案中建立虛擬環境與 App Factory，並以 Blueprint 顯示首頁。完成標準：flask --app run.py routes 列出 main.index 與 static；瀏覽器開啟 http://127.0.0.1:5000/ 可看到網站名稱、導覽列與頁尾，且 Network 分頁沒有外部請求。

學員實作 2：自行完成健康檢查 API 並通過測試——任務：依分層實作 GET /api/health，並撰寫 tests/test_health.py 驗證 4 個 Scenario。步驟提示：先寫 HealthRepository.ping()，再寫 HealthService.check()，最後寫 health_api，每層只做自己的事；資料庫失敗情境以 unittest.mock.patch 替換 HealthRepository.ping，讓它拋出 OperationalError。完成標準：pytest 結果為 4 passed；/api/health 回傳 200，欄位順序為 code、success、message、data，中文正常顯示；API Controller 中沒有出現 db；失敗時回應 503 且不含例外訊息；勾選 tasks.md 並完成 openspec archive，最後 commit。

進階挑戰（二選一）：選項 A 新增 GET /api/version，回傳 data 包含 app 與 version（取自 current_app.config），使用 success_response()；選項 B 在首頁 LAYERS 加入一筆新資料（例如 API Controller 或 View），選用一個 Bootstrap Icons 圖示，確認卡片在寬螢幕仍排列整齊。完成標準：新增至少 1 個測試，pytest 全數通過。

本堂共 8 個產出項目，全部打勾才算做完：虛擬環境與套件（.venv/、requirements.txt，提示字元出現 (.venv)、安裝結果為 Successfully installed）、App Factory 與設定（app/__init__.py、config.py、extensions.py、run.py，測試以 create_app("testing") 建立 app 並使用記憶體 SQLite）、Blueprint 首頁與版型（瀏覽器開啟 / 顯示網站名稱與分層卡片）、離線靜態檔（樣板沒有 CDN 網址，Network 分頁沒有外部請求）、健康檢查 API（/api/health 回傳 200 與統一回應格式）、測試（pytest 結果 4 passed）、文件更新（AGENTS.md、README.md 含建立虛擬環境、啟動網站、執行測試指令）、OpenSpec 歸檔與 Git 提交（openspec list --specs 顯示 system-health，git log 可看到 commit）。

評量方式：本堂對應大綱評量比例——Session 實作任務 30%（學員實作 1、2 與產出檢核表）、OpenSpec 需求與設計文件 15%（tasks.md 勾選正確、變更已歸檔並產生正式規格）、Flask 網站功能 25%（首頁與 /api/health 可正常運作）、AI Agent 與 Skill 15%（本堂僅觀察 openspec-apply-change／openspec-archive-change 的使用過程，不單獨計分）、測試與部署 10%（pytest 4 個測試通過，含 mock 失敗情境）。

評分規準（滿分 100 分）五個項目：虛擬環境與啟動（15 分，優良是 .venv 正確建立且未提交、能說明為何需要虛擬環境，待加強是使用全域套件或 .venv 被提交到 Git）、App Factory 與設定（20 分，優良是能以 create_app("testing") 切換設定並說明 init_app 用途）、分層與 Blueprint（20 分，優良是各層職責正確、Controller 不碰 db、連結全部使用 url_for()，待加強是在 Controller 直接查資料庫或撰寫商業判斷）、健康檢查 API（20 分，優良是正常與失敗兩種回應都符合規格、失敗時不洩漏例外細節）、測試（15 分，優良是 4 個 Scenario 皆有測試、含 mock 失敗情境並能解釋原理）、OpenSpec 與 Git（10 分，待加強是未歸檔或未提交）。

• 執行 flask 出現「無法辨識」，或 ModuleNotFoundError: No module named 'flask'——虛擬環境未啟用，或 VS Code 使用全域直譯器。解法：執行 .venv\Scripts\activate；在 VS Code 選擇 .venv 的直譯器後開啟新的終端機。
• 執行 .venv\Scripts\activate 時出現「因為這個系統上已停用指令碼執行」——PowerShell 執行原則禁止執行 .ps1 腳本。解法：在 VS Code 選擇 .venv 直譯器後開新終端機（settings.json 已設定自動啟用），或改用命令提示字元；仍無法解決時請講師協助。
• 直接執行 pytest 出現 ImportError while loading conftest 與 No module named 'app'——pytest 主控台程式不會把專案根目錄加入匯入路徑，pytest.ini 未設定。解法：在專案根目錄改用 python -m pytest -v -p no:cacheprovider，或使用 VS Code 測試面板。
• Error: Could not import 'run'——終端機目前不在專案根目錄，找不到 run.py。解法：切換到 run.py 所在的專案根目錄再執行。
• BuildError: Could not build url for endpoint 'index'——url_for() 少了 Blueprint 名稱前綴。解法：改為 url_for('main.index')；可用 flask --app run.py routes 查 endpoint 名稱。
• jinja2.exceptions.TemplateNotFound: index.html——樣板路徑少了子資料夾，或樣板不在 app/templates/。解法：改為 render_template("main/index.html")，確認檔案位於 app/templates/main/。
• KeyError: 'staging'——環境變數 FLASK_CONFIG 的值不在 config_by_name 中。解法：只能使用 development、testing、production。
• JSON 中文顯示為 \u服務...，欄位順序變成 code、data、message、success——create_app() 缺少 app.json.ensure_ascii = False 與 app.json.sort_keys = False。解法：補上兩行設定後重新啟動。
• /api/health 回應 503「資料庫無法連線」——.env 中的 DATABASE_URL 錯誤，或資料庫檔案位置無法寫入。解法：查看伺服器終端機 Log 中「資料庫健康檢查失敗」後的例外內容，修正連線設定。
• 首頁沒有樣式或圖示變成方框——app/static/ 檔案缺漏，例如沒有複製 fonts/。解法：開發者工具 Network 分頁找出 404 的檔案並補齊。

五個綠色打勾項目：乾淨絕對隔離的 .venv 虛擬環境、具備動態靈活切換能力的 App Factory、職責分明嚴格限制相依的 5 層 MVC 結構、真實資料庫 Ping 與統一 JSON 格式的 Health API、100% 覆蓋核心情境的 Pytest 自動化測試。右下角是 bookstore-agent 網頁截圖，顯示分層架構的四張卡片（Controller／Service／Repository／Model）。投影片下方寫著「Next Step：迎接 AI Agent 協同開發與完整的電子書目錄功能！」

教案第十一章課後作業：①完成學員實作 1、2 與進階挑戰（二選一），commit 並附上 pytest 結果與瀏覽器畫面截圖；②在 tests/test_health.py 新增一個測試——資料庫失敗時 data.status 應為 degraded，並思考這個行為是否該補進 system-health 規格；③閱讀 specs/02-book-catalog.md，列出「書籍目錄」功能在 Controller、Service、Repository、Model 各層可能出現的類別與方法名稱（各至少 1 個），作為 Session 04、05 的準備。

第十二章下次課程預告：Session 04｜Codex Agent 協同開發方法——學習以 Context、Constraint、Expected Output 三要素撰寫 Prompt，分階段要求 Codex 產生程式碼並進行 AI 程式碼審查與人工驗證；實作任務是在本堂骨架上建立首頁版型（導覽列與 Hero 區域、書籍展示卡片、RWD 基礎設計），起點是講師事先建立並審查通過的 OpenSpec 變更 add-homepage-layout（capability：homepage）。