AI Agent Literacy 學習分析工具・NTNU・Week 1 – 16 作品集

WEEK 07

像工程師一樣開發：規劃與測試

這週先看軟體工程：瀑布式開發（Waterfall Model）一階一階往下流，錯在需求就得逆流回到最上面；測試驅動開發（TDD）把它切成很多小步，先寫測試、再寫程式，其實就是我們一直在用的 VERIFY.md。接著是 PLANS.md：大任務先規劃，由 Codex 起草、你審方向。補充教材再把自己的網站拆開來看：HTML、CSS、JS 和素材各管什麼，瀏覽器怎麼把它們組起來；以及 Git 的版本管理怎麼成為用 AI 開發時的安全網：先看 AI 改了什麼，改壞了就回到上一個存檔點，測試全綠才 commit。作業：玩老師做的「空中之島」，照真正的開發方式分批做：第 1 批「挖 → 掉 → 撿 → 放」用老師想的測試，第 2 批是你自己的點子、測試自己想，再讓 Codex 照 PLANS.md 一步一步做出來。

影片 01軟體工程與測試驅動開發（TDD）

  1. AI 寫程式這麼快，為什麼還要軟體工程？軟體工程是一群人在有限的時間裡，做出可靠、以後還改得動的軟體的方法。AI 讓寫程式變快了，難的變成「知道要做什麼」和「確定做對了」，所以軟體工程反而更重要。

  2. 瀑布式開發（Waterfall Model）：一階一階往下流。需求 → 設計 → 實作 → 測試 → 維護。其實你已經跑過一次小瀑布了：BRIEF.md、PLANS.md、Codex 寫程式、VERIFY.md、AGENTS.md。

  3. 問題是測試排在最後。如果錯在需求，就得逆流回到最上面，中間做的全部要重來。最常被引用的瀑布論文（Royce，1970）其實在提醒：只跑一趟「risky and invites failure」。所以業界採用瀑布式開發的，通常是流程很熟、做過很多次、有過去經驗的專案。

  4. 測試驅動開發（Test-Driven Development，TDD）：把一趟大瀑布，切成很多小瀑布。每一小步都是：紅，先寫一個會失敗的測試；綠，寫剛好讓它通過的程式；重構（refactor），把程式整理乾淨，燈要一直是綠的。

  5. 寫測試，就是先寫下「給什麼輸入，應該得到什麼」。一條就是一個測試案例（test case），寫成程式，一個指令全部跑完。是不是很熟悉？這就是我們一直在用的 VERIFY.md。從 Single-turn Prompting 到 VERIFY.md，我們一直強調：先想清楚，結果才有確定性。

  6. 為什麼特別適合 AI：AI 很會說「做好了」，測試不會被說服。回歸（regression）是改了 A，壞了 B：新加「補考」的規則後，原本會過的「請假」測試變紅了；測試每次都全部重跑，B 一壞馬上被抓到。小心 AI 為了通過去改測試，在 AGENTS.md 寫上「不要為了通過而修改測試；覺得測試錯了，先問我」。影片裡的山谷、Codex 畫面和成績都是示意。

影片 02大任務，先規劃：PLANS.md

  1. PLANS.md 回答「怎麼走到那裡」。AGENTS.md 是怎麼做事，BRIEF.md 是做什麼，VERIFY.md 是怎樣算做好（你寫、你維護）；PLANS.md 寫分幾步、先做什麼、每一步要通過哪幾條測試，交給 AI 寫，你審方向。這些檔案都存在你的資料夾裡：AI Agent 是透過本地文件和你對話，和傳統線上 chat 聊過就散掉不一樣。檔名全大寫是大家約好的名字，看到就知道用途；小寫是你自己取的。

  2. 哪句是 BRIEF、哪句是 PLANS？誰來做都一樣的（目的、限制，例如世界大小固定）寫在 BRIEF，很少改；換個人可能不同的（順序、做法、檔案怎麼放）寫在 PLANS，由 AI 邊做邊調整。

  3. 請 Codex 起草之前，先說清楚範圍和驗收。有不清楚的先問你；VERIFY.md 每一條都要排進某一步，每一步寫出要通過哪幾條；不做 BRIEF 沒要的，不違反限制。怎麼做、分幾步，讓 AI 決定。這就是你控制規劃方向的方法。

  4. Plan mode 和 PLANS.md。Codex 的 Plan mode 讓你先看計畫、再放行寫程式；但計畫只在對話裡，開新對話或被壓縮就不見了。寫成 PLANS.md 存在資料夾，換對話也還在。

  5. 你審方向，不用自己改寫。AI 的第一版另存成 PLANS.v1.md 對照用，再問三件事：VERIFY 每一條都排進去了嗎？每一步都對到測試嗎？有沒有偷加 BRIEF 沒要的？不對就請 AI 改。VERIFY.md 是你的，PLANS.md 是 AI 的。

  6. 用 AGENTS.md 守住方向。VERIFY.md 不要改，那是我的；PLANS.md 你可以自己調整，回報時說改了什麼；一次只做一步：先寫測試、確認失敗，再寫程式（影片 01 的 TDD）；不要為了通過而修改測試。之後每一輪只要說「做 PLANS.md 的下一步」；發現 bug 或想到新點子，你先寫進 VERIFY.md。

影片 03作業：規劃並做出「空中之島」

這週的作業：玩一玩老師做的「空中之島」，然後自己規劃、自己做出一個。這次照真正的開發方式分批做：把功能分成一批一批，每一批先想好測試，做完、測試全部通過，再做下一批，不會一下子什麼都想做、亂寫一通。第 1 批的測試老師已經想好了；第 2 批是你自己的點子，測試由你來想。

素材：下載 sky-island-assets.zip（範例用到的方塊材質、圖示和挖方塊的裂痕，16×16 像素，附放大版和說明）。範例可以直接在上面玩，也可以開新分頁全螢幕玩。

限制（每個人都一樣，貼進 BRIEF.md）：靜態網站（HTML、CSS、JavaScript），用 three.js 畫 3D，不用伺服器、帳號或遊戲引擎；學校的舊電腦（內顯，或只用 CPU）全螢幕也要每秒 30 格以上；世界大小固定，32 × 32 × 32 格以內，不做無限世界、不做多人；材質只用上面的素材包（挖方塊的裂痕也在裡面）。

  1. 先玩，再自己寫 BRIEF.md。把範例玩一遍：WASD 走、空白鍵跳，按住左鍵挖（會先裂開）、走過去把掉出來的小方塊撿起來、右鍵放回去。用你自己的話寫：要做什麼、不做什麼、一個你自己的點子（例如會下雨、可以種花），最後貼上上面的限制。這一份不要請 AI 寫。

  2. 第 1 批「挖 → 掉 → 撿 → 放」：用老師想的測試。這四件事是一整串，少一個就玩不起來，所以算同一批，分成 STEP 1～4。這一批的測試老師已經想好了，把下面這份抄進 VERIFY.md，不用改。每一條都是「我做了什麼 → 應該看到什麼」，每個 STEP 都有一條「不可以發生」的事；你寫第 2 批時照這個寫法。

    VERIFY.md：照抄這一份
    # VERIFY.md

## STEP 0 小島
（請 Codex 照 BRIEF 和限制補上，每條標「AI 補充」，你看過再留）

## 第 1 批：挖 → 掉 → 撿 → 放（老師想的測試）

### STEP 1 挖方塊
- [ ] 按住左鍵對著泥土 → 出現裂痕、越裂越大，不到 1 秒那一格不見
- [ ] 只點一下左鍵 → 方塊還在（不可以發生：一點就不見）
- [ ] 挖到一半放開左鍵 → 裂痕不見，再挖要從頭開始
- [ ] 挖石頭 → 比泥土久，大約 2 秒

### STEP 2 掉出來
- [ ] 方塊不見時 → 原地彈出一個同種類的小方塊，慢慢轉
- [ ] 小方塊落到地上停住（不可以發生：浮在空中、穿過地面）

### STEP 3 撿起來
- [ ] 走到小方塊旁邊 → 它飛到身上，方塊欄那一格的數字 +1
- [ ] 站在 3 格外 → 不會被撿起來（不可以發生）

### STEP 4 放回去
- [ ] 選有數字的那一格，對地面按右鍵 → 放出一格，數字 −1
- [ ] 那一格的數字是 0 → 按右鍵放不出來（不可以發生）
- [ ] 整串走一遍：挖一塊 → 撿起來 → 放回去 → 數字回到原本

## 第 2 批：我的點子（自己想的測試）

### STEP 5 （寫你的點子）
- [ ]

  3. 第 2 批：你的點子，自己想測試。BRIEF 裡你的點子就是第 2 批，從 STEP 5 開始（點子比較大，就拆成 STEP 5、6）。照第 1 批的寫法寫在 VERIFY.md 的「第 2 批」，至少 3 條，其中一條是「不可以發生」的事。要具體到看得出對錯：「下雨要正常」太模糊，「按 R → 開始下雨，看得到雨滴往下掉」才看得出來。這一批不要請 AI 想，寫完先 commit。

  4. 請 Codex 挑毛病、補漏掉的，你決定留哪些。請它檢查整份 VERIFY.md：哪幾條太模糊、測不出來（它提建議，你同意才改）；漏掉的請它補在對應的 STEP 下面，每條後面標「（AI 補充）」，不用另外編號；島、走路和上面的限制，請它寫在最前面的 STEP 0「小島」。你看過才留下，BRIEF 沒要的就劃掉。

  5. 請 Codex 起草 PLANS.md，你來審方向。先不要寫程式。PLANS.md 是 AI 的：每一步怎麼做、要不要再拆小，讓它決定。你只跟它說清楚：照 STEP 0、1、2… 的順序一批一批做，一步一個 STEP，每一步寫出要通過 VERIFY.md 哪個 STEP 的測試；有不清楚的先問你；不做 BRIEF 沒要的，不違反限制。AI 的第一版存成 PLANS.v1.md 對照用。你審三件事：每一條測試都排進去了嗎？每一步都對到測試嗎？有沒有偷加 BRIEF 沒要的東西？不對就請它改，你不用自己改寫。

  6. 用 AGENTS.md 把規則講好。至少寫進這幾條：不要讀取或複製範例網站的原始碼；VERIFY.md 不要改，那是我的；PLANS.md 你可以自己調整，回報時說改了什麼，但不能做 BRIEF 沒要的；一次只做一步，做完停下來回報；每一步用 TDD：先把這一步的測試寫好、跑一次確認失敗、commit，再寫程式，全部測試通過才 commit，並在 PLANS.md 勾掉這一步；不要為了通過而修改測試。

  7. 一步一步做，一批做完再做下一批。每一輪只要說「做 PLANS.md 的下一步」。做完看三件事：回報裡新測試是不是先失敗、最後全部通過；寫程式的那次有沒有改到測試檔（用「檢視變更」看）；自己玩一下，把 VERIFY.md 裡這個 STEP 的幾條打勾。一批做完（例如 STEP 4 做好），自己把整串從頭玩一遍，都對了再開始下一批。玩的時候發現 bug 或想到新點子，你自己先把它寫進 VERIFY.md（新點子就是新的一批），再請 Codex 寫成測試、確認失敗，然後修好或做出來。

  8. 交作業。把你的 GitHub repo 連結交給老師，裡面要有 BRIEF.md、VERIFY.md、PLANS.v1.md、PLANS.md、AGENTS.md、測試和程式。評分最看重你自己想的部分：BRIEF、你的第 2 批測試（要比 PLANS.v1.md 先 commit）、你怎麼維護 VERIFY.md（後來加的、AI 補的你留下或劃掉的），再加上 git 看得出每一步都先寫測試、再寫程式。第 2 批做到哪裡都可以，但做了的每一步都要有測試通過。

補充 1網站是怎麼組成的

  1. 網站像一棟房子。HTML 是隔間：網站的結構和內容（index.html）；CSS 是裝潢：顏色、排版，還有手機版怎麼排（style.css）；JS 是水電和開關：按了會怎樣、地圖、讀資料（app.js），會動、按了有反應，就是 JS 的強項；再加上素材：圖片，還有 CSV、JSON 這些資料。

  2. 拆開自己的網站，就知道每一塊管什麼。拿掉 CSS，內容都還在，只剩瀏覽器預設的樣子，一排一排的字；拿掉 JS，地圖不見了，按鈕按了也沒反應；兩塊都拿掉，剩下的就是 HTML 的隔間和內容。

  3. 網站就是一個資料夾。入口預設叫 index.html：瀏覽器先拿到它，它再把 CSS、JS、圖片、資料一起拉進來。上線，就是把這個資料夾放到網路上。

  4. 瀏覽器就是網頁的「編譯器」。第一堂課裝 Python，是為了讓電腦有能執行 Python 的「編譯器」，把程式碼翻譯給電腦執行（嚴格說，Python 用的是「直譯器」）。做網站不用另外裝：瀏覽器讀 HTML、CSS，執行 JS，裡面是排版引擎和 JS 引擎，有瀏覽器就看得到結果。

  5. 靜態像印好的菜單，動態像現點現做。靜態網站也能互動。Week 6 的考試是靜態網站：進度存在你的瀏覽器裡，換一台電腦就不見了；要跨裝置同步，才需要伺服器和資料庫。

  6. 懂了網站的組成，才控制得住 AI。指令會更準，例如「只改 style.css，不要動 HTML 結構」；出問題時知道是哪一塊（跑版找 CSS、內容寫錯找 HTML 或資料、按了沒反應找 JS）；也知道登入、全班共享資料這些事，需要伺服器。影片裡的示範網站和 Codex 畫面是示意。

補充 2Git：版本管理，也是你的安全網

  1. Git 最重要的是版本管理。沒有版本管理的時候，檔案只能存成「報告_final_v2_真的最終.docx」，哪一份是最新的、改了什麼，都很難說。用 Git，每次 commit 就是一個存檔點：可以看歷史、比較差異，回到任何一版。GitHub 只是把這些版本放到雲端。

  2. AI 一次會改好幾個檔案，先看它改了什麼。影片裡三張描圖紙就是網站的三個檔案（index.html、style.css、app.js），疊起來就是網站；AI 一次在三張上都改了。Codex app 的「檢視變更」會列出這一輪改了哪些檔案：紅色是刪掉的，綠色是加上的；選「最近一輪」，就只看 AI 這一次改的。專案要是 Git 倉庫，才看得到。

  3. 改壞了很正常，回到上一個存檔點就好。直接跟 AI 說：「剛剛這一輪把地圖弄壞了，請還原這一輪的修改，回到上一個 commit。」三個檔案的改動會一起擦掉，網站回到上一個存檔點。

  4. 測試全綠就 commit，說明要寫清楚。跑測試有紅燈，就請 AI 修，再跑一次；全部通過再 commit。說明寫做了什麼、結果怎樣，例如「地圖加上散步路線規劃，測試全部通過」，而不是「update」，之後看歷史、要回去的時候，才找得到這一版。

  5. 影片裡的畫面是示意。示範用的是補充 1 的銀杏散步地圖；「檢視變更」面板照 Codex app 官方文件畫成示意，commit 編號、Codex 對話和測試案例也是示意。

練習 1進入遠端電腦

這不是影片，而是一台在瀏覽器裡開啟的「遠端電腦」，和前幾週是同一台，換成這週的任務，有 Mac 和 Windows 兩種，選你平常用的那一種。這週練的是作業的流程：先寫 BRIEF.md 和 VERIFY.md，再起草、審 PLANS.md，然後一步一步做、跑測試。要寫的字都可以複製貼上，目的是把流程練到手很熟；同一個動作第二次出現時會標「自己來」，不再指位置。專案是你自己的「空中之島」，做到第幾步，就玩得到第幾步。連線後先選一個任務，照著任務卡做；要離開時，按畫面上方中間的「中斷連線」。每次進入都是一台全新的電腦；重新整理或離開後，這次的進度不會留下。

練習環境的畫面是繁體中文；需要用滑鼠和鍵盤操作，建議用電腦的瀏覽器開啟，手機的螢幕太小。

  1. 先想清楚，再讓 AI 做。用 VS Code 打開專案，貼上 BRIEF.md 和 VERIFY.md（第 1 批老師想的測試、第 2 批你的點子），先 commit；請 Codex 挑毛病，它補的放進對應的 STEP，你決定留哪些；請它起草 PLANS.md，留一份 PLANS.v1.md，審三件事，請它改。

  2. 一步一步：先紅、再綠、再 commit。把 TDD 的規則寫進 AGENTS.md，每一輪只說「做 PLANS.md 的下一步」，自己跑 npm test、看 git log --oneline，打開遊戲玩一下，在 VERIFY.md 打勾、commit。同一個迴圈做兩輪，第二輪自己來。

  3. 一批做完：整串玩一遍，bug 先寫進 VERIFY。把第 1 批做完，自己把「挖 → 掉 → 撿 → 放」整串從頭玩一遍；連續挖兩格，第二個撿不起來：先寫進 VERIFY.md，再請 Codex 寫成測試、確認失敗、修好。練習裡的 Codex 不會真的寫程式，真正的作業請在你自己的電腦上做。卡住時按任務卡上的「提示」。