開發教學：從零到開出第一個 PR

這頁給想幫課程網站加功能的同學。你會用 ChatGPT 或 Claude，但沒碰過 git、GitHub、終端機也沒關係。

怎麼讀這頁：照順序做。

• 設定篇做一次就好，大約 60～90 分鐘，分兩段：
  • 步驟 1～6 設定自己的電腦，不需要 repo 權限，什麼時候做都可以。
  • 步驟 7～9 要先被 repo owner 加進 repo。
• 開發篇：之後每次開發只看這篇。

為什麼每一步都附一段 prompt：文字說明只講「要做到什麼、怎麼確認做到了」。真的卡住的時候（看不懂錯誤訊息、mac 和 Windows 的指令不一樣），讓 AI 陪你一步一步做會比看文件快。每段 prompt 都要求 AI 做到三件事：

1. 先問你用什麼作業系統。
2. 一次只給一步。
3. 等你回報結果、確認成功了才往下。

有了這三條，AI 就不會一口氣丟出 20 行指令，害你貼到一半就壞掉。

指令要貼在哪裡：

• 標「mac」的指令：貼在「終端機（Terminal）」。
• 標「Windows」的指令：貼在 PowerShell（開始選單搜尋 PowerShell）。
• Linux：照 mac 的做，套件管理改用你的發行版（apt / dnf）。

每個區塊右上角都有「複製」按鈕，複製時會自動拿掉說明用的註解。

設定篇（做一次就好）

第一段：設定自己的電腦（步驟 1～6）：只需要你自己的 GitHub 帳號，不需要 repo 權限。

步驟 1：建立 GitHub 帳號、開 2FA

目標：有一個 GitHub 帳號，而且開好兩步驟驗證。

你會得到什麼：一個之後所有設定都會用到的 GitHub 帳號。這一步還不用加進課程 repo，那是步驟 7 的事。你可以先把步驟 1～6 都做完，再去找 repo owner。

預估時間：15 分鐘。

手動步驟（mac / Windows 相同，全在瀏覽器）：

1. 到 https://github.com/signup 註冊。username 用好認的英文，例如 chen-md、lin-mba，大家在 PR 上看到的就是這個名字。
2. 開兩步驟驗證（2FA）：右上角頭像 → Settings → Password and authentication → Enable two-factor authentication。
   • 選 Authenticator app（Google Authenticator、Microsoft Authenticator、1Password 都可以），或直接用 Passkey。
   • 一定要下載 recovery codes，存進密碼管理器或印出來。換了手機又沒有 recovery codes，帳號基本上救不回來。

貼給 AI 的 prompt：

我是 GitHub 新手，要準備一個 GitHub 帳號參與開發。請帶我完成：
1. 註冊 GitHub 帳號（幫我想一個好認的 username）
2. 開啟兩步驟驗證（2FA），並提醒我保存 recovery codes

規則：
- 先問我用的是電腦還是手機、哪個瀏覽器、手機是 iPhone 還是 Android（決定 authenticator app 怎麼裝）。
- 一次只給我一步，等我回報「完成」或貼畫面上的文字，你確認沒問題才給下一步。
- GitHub 介面的按鈕名稱請保留英文原文（例如 Settings、Password and authentication），我才找得到。
- 不要叫我把密碼、recovery codes 或 2FA 驗證碼貼給你。

怎麼確認成功：登入狀態下打開 https://github.com/settings/security，Two-factor authentication 那一區顯示已啟用（Enabled）。

常見問題：

• 收不到 2FA 簡訊：改用 authenticator app 或 passkey。台灣門號收 GitHub 簡訊偶爾不穩定。

步驟 2：安裝 git，設定名字和 email

目標：電腦上有 git 指令，而且設定好每個 commit 上要顯示的名字和 email。

你會得到什麼：之後每個 commit 都會標上你的名字和 email，在 GitHub 上連到你的帳號（頭像、個人頁）。

預估時間：10 分鐘。

手動步驟：

安裝 git（mac 會跳出視窗問要不要安裝 Command Line Tools，按「安裝」；已經有 Homebrew 的話，也可以用 brew install git）：

# mac
xcode-select --install

# Windows（PowerShell）。裝完把 PowerShell 整個關掉重開，才找得到 git 指令
winget install --id Git.Git -e --source winget

沒有 winget 的 Windows：到 https://git-scm.com/download/win 下載安裝檔，選項全部用預設值。

設定名字和 email（mac / Windows 指令相同，名字和 email 換成你自己的）：

git config --global user.name "陳小明"
git config --global user.email "chen.md@example.com"
git config --global init.defaultBranch main

email 用你自己的：填你自己常用、收得到信的 email，而且要是註冊 GitHub 的那個，或已經加進 GitHub 帳號並驗證過的。這樣 commit 才會連到你的 GitHub 帳號，其他協作者也知道怎麼聯絡你。

1. GitHub → Settings → Emails：確認你要用的 email 在清單裡，而且是已驗證（Verified）。
2. 同一頁的 Block command line pushes that expose my email 要保持沒勾。勾了的話，用你自己 email 的 commit 在 push 時會被 GitHub 擋下來。

commit 裡的 email 會永久留在 git 歷史裡。repo 是 private，只有協作者看得到。

貼給 AI 的 prompt：

我要在電腦上安裝 git 並設定 user.name 和 user.email，我沒用過終端機。

規則：
- 先問我用 mac、Windows 還是 Linux；Windows 的話請給 PowerShell 指令，並先確認我有沒有 winget。
- 一次只給一條指令，請我貼回輸出結果，你確認成功才給下一條。
- email 用我自己的 email（註冊 GitHub 的那個）；請引導我到 GitHub Settings → Emails 確認這個 email 已驗證，並確認「Block command line pushes that expose my email」沒有勾。
- 最後請我執行 git config --global --list，你幫我檢查 user.name 和 user.email 是否正確。

怎麼確認成功：

git --version  # 看到 git version 2.x.x
git config --global --list  # 看到 user.name=... 和 user.email=你自己的 email

常見問題：

• Windows 說找不到 git：裝完沒有重開 PowerShell。關掉再開；還是不行就重開機。
• mac 跳出 xcode-select: note: install requested 之後就沒反應：找找看安裝視窗是不是被擋在其他視窗後面。裝完大約要 5～10 分鐘。
• email 設錯，而且已經 commit 了：
  • 還沒 push：問 AI「幫我修改最後一個 commit 的作者 email」。
  • 已經 push：先不要動，找 superadmin。

步驟 3：安裝 GitHub CLI（gh）

目標：電腦上有 gh 指令。這一步一定要做。

你會得到什麼：一個指令就能登入 GitHub、clone repo、開 PR。AI 工具幫你開 PR 時也是用它。

預估時間：5 分鐘。

為什麼一定要裝：

1. 它順便處理 git 的登入：下一步的 gh auth login 會幫 git 設好 HTTPS 認證，不用產 SSH key，也不用貼 token。在 Windows 上這是最不容易出錯的方式。
2. AI 開 PR 要靠它：Claude Code、Codex 等 AI 工具開 PR 的標準做法是 gh pr create。沒有 gh，AI 只能叫你自己去網頁上點，新手很容易選錯 base branch，或漏寫 description。
3. review 流程要靠它：repo 內建的 /branch-review 用 gh pr comment 把 review 結果貼到 PR 上。

手動步驟：

# mac（需要 Homebrew；沒有的話先照 https://brew.sh 首頁那一行指令安裝）
brew install gh

# Windows（PowerShell）。裝完關掉 PowerShell 重開
winget install --id GitHub.cli -e

沒有 Homebrew 也沒有 winget：到 https://cli.github.com 下載安裝檔。Linux 照 https://github.com/cli/cli#installation 加官方套件來源。

貼給 AI 的 prompt：

我要安裝 GitHub CLI（gh 指令）。

規則：
- 先問我用 mac、Windows 還是 Linux。
- mac：先檢查我有沒有 Homebrew（請我跑 brew --version），沒有的話先帶我裝 Homebrew。
- Windows：用 winget，給 PowerShell 指令，並提醒我裝完要重開 PowerShell。
- 一次只給一條指令，等我貼回輸出確認成功才往下。
- 最後請我跑 gh --version 確認。這一步只安裝，先不要登入。

怎麼確認成功：

gh --version  # 看到 gh version 2.x.x

常見問題：

• mac 說 brew: command not found：Homebrew 裝完最後會印出兩行 echo ... >> ~/.zprofile 的指令，要照著貼，然後重開終端機。
• Windows 說 winget 不是可辨識的命令：到 Microsoft Store 更新「應用程式安裝程式（App Installer）」，或直接到 https://cli.github.com 下載 .msi。
• 公司電腦不能裝軟體：找 IT，或改用自己的電腦。這一步沒辦法跳過。

步驟 4：連接 GitHub（gh auth login）

目標：讓電腦上的 git 跟 gh 都用你的 GitHub 身分登入。

你會得到什麼：之後 git push、gh pr create 都不會再問帳號密碼。

預估時間：5 分鐘。

手動步驟（mac / Windows 相同）：

gh auth login

它會問你幾題，照下表選（用方向鍵移動、Enter 確認）：

接著畫面會印出一組 8 碼的 one-time code。按 Enter 打開瀏覽器，貼上 code → Authorize。回到終端機看到 Logged in as <你的 username> 就完成了。

貼給 AI 的 prompt：

我已經裝好 git 和 gh，現在要用 gh auth login 把電腦連上 GitHub（用 HTTPS，不要用 SSH）。

規則：
- 先問我用 mac、Windows 還是 Linux。
- gh auth login 會問好幾題，請一題一題告訴我該選哪個選項，並解釋為什麼。
- 每一步都請我貼回終端機畫面，你確認後再往下。
- 完成後請我執行 gh auth status 和 gh api user --jq .login，幫我判斷是否成功（第二條會印出我的 username）。
- 我可能還沒被加進任何 repo，這是正常的，這一步只確認登入。
- 不要叫我把 token 貼給你。

怎麼確認成功：

gh auth status  # 看到 ✓ Logged in to github.com account <username>，以及 Git operations protocol: https
gh api user --jq .login  # 印出你的 GitHub username

常見問題：

• 之後還要一直登入嗎：不用。gh 把登入憑證存在系統的密碼庫（mac 是鑰匙圈、Windows 是認證管理員），git push、gh pr create 都會自動帶上。只有下面幾種情況要再跑一次 gh auth login：

  • 換電腦或重灌。
  • 你自己到 GitHub → Settings → Applications 撤銷了 GitHub CLI。
  • 超過一年沒用，GitHub 自動撤銷。

  不確定的時候就跑 gh auth status。

• Windows 跳出 Git Credential Manager 的登入視窗：照著用瀏覽器登入就好，結果一樣；之後 gh auth status 正常就沒問題。

• 電腦上有好幾個 GitHub 帳號：用 gh auth status 看目前是哪一個，用 gh auth switch 切換。

ssh-keygen -t ed25519 -C "chen.md@example.com"

# mac
pbcopy < ~/.ssh/id_ed25519.pub

# Windows（PowerShell）
Get-Content $env:USERPROFILE\.ssh\id_ed25519.pub | Set-Clipboard

ssh -T git@github.com  # 看到 Hi <username>! You've successfully authenticated

我想用 SSH key 連 GitHub（不用 HTTPS）。請先問我作業系統，然後一步一步帶我：
產生 ed25519 key → 複製 public key → 上傳到 GitHub Settings → SSH and GPG keys → 用 ssh -T git@github.com 驗證。
每步等我貼回結果再往下。提醒我只上傳 .pub 檔，私鑰不能給任何人，也不要貼給你。

步驟 5：安裝 Node.js 22.12 以上

目標：電腦上有 Node.js 22.12 以上，網站的 build 工具需要它。

你會得到什麼：node 和 npm 兩個指令，步驟 8 跑網站時會用到。

預估時間：10 分鐘。

手動步驟：

mac 推薦用 nvm，之後換版本最方便。先裝 nvm（版本號以 https://github.com/nvm-sh/nvm#installing-and-updating 為準）：

curl -o- https://raw.githubusercontent.com/nvm-sh/nvm/v0.40.8/install.sh | bash

關掉終端機重開，再裝 Node 22：

nvm install 22
nvm alias default 22

不想用 nvm 的話，也可以用 Homebrew 裝最新版（一樣符合 22.12 以上）：

brew install node

Windows 推薦用官方 LTS 安裝檔，最不容易出錯：

winget install --id OpenJS.NodeJS.LTS -e

貼給 AI 的 prompt：

我要在電腦上安裝 Node.js，版本要 22.12 以上。

規則：
- 先問我用 mac、Windows 還是 Linux。mac 建議 nvm，Windows 建議官方 LTS 安裝檔（winget install --id OpenJS.NodeJS.LTS -e）。
- 先請我跑 node -v，已經有 22.12 以上就不用裝。
- 一次只給一條指令，等我貼回輸出你確認成功才往下。
- 最後請我跑 node -v 和 npm -v 確認。

怎麼確認成功：

node -v  # v22.12.0 以上（v24 也可以）
npm -v  # 有印出版本號就好

常見問題：

• 裝完 node -v 還是舊版本，或找不到：關掉終端機 / PowerShell 重開。用 nvm 的話，再跑一次 nvm use 22。
• Windows PowerShell 說「npm.ps1 無法載入，因為這個系統上已停用指令碼執行」：執行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned，選 Y，重開 PowerShell。

步驟 6：安裝 AI 工具

目標：電腦上有一個能在終端機裡改程式的 AI 工具。

你會得到什麼：步驟 8 clone 完 repo 之後，在 repo 資料夾裡啟動它，它就會自動讀到專案規則（步驟 9）。

預估時間：10 分鐘。

三個裡面選一個就好。安裝指令常常改，所以這裡只放官方網站，照官方的步驟裝，或請 AI 帶你：

貼給 AI 的 prompt（貼給網頁版的 ChatGPT / Claude）：

我想在電腦上安裝一個可以在終端機裡改程式的 AI 工具（Claude Code、Codex CLI 或 Antigravity CLI 其中一個）。
請先問我：用 mac 還是 Windows、我有哪個付費方案（Claude Pro/Max、ChatGPT Plus、Google 帳號），再推薦一個並帶我安裝。
一次只給一步，等我貼回結果確認成功再往下。請以官方文件的安裝方式為準，如果你不確定最新指令，請叫我去官方文件頁確認。
最後請我在終端機啟動它一次、完成登入，確認可以正常對話就好（還不用打開任何專案）。

怎麼確認成功：在終端機打 claude（或 codex、agy），能登入，而且它會回你話。

常見問題：

• 只想用網頁版 ChatGPT 或 Claude Desktop：也可以，只是它讀不到你電腦上的檔案。步驟 9 會教你怎麼把規則貼給它。

第二段：加入課程 repo（步驟 7～9）：要先被 repo owner 加進 repo 才能做。順序可以自己選：做完步驟 1～6 再去找 owner；或者一註冊好 GitHub 就先請 owner 邀請，只要在 7 天內接受邀請就好。

repo 已改名：2026-10-24 從 2026-1142-ETEPM 改名成 evolving-intelligence（網址 https://github.com/tingwei161803/evolving-intelligence）。舊網址 GitHub 會自動轉到新網址，改名前就 clone 的人不會壞掉，照步驟 8 常見問題的「改名前就 clone 過的人」更新一次 remote 就好。

步驟 7：請 repo owner 邀請你、接受邀請

目標：你的 GitHub 帳號被加進課程 repo（private）。

你會得到什麼：在瀏覽器打開 https://github.com/tingwei161803/evolving-intelligence 看得到程式碼。還沒被邀請的話，只會看到 404。

預估時間：5 分鐘（等 owner 邀請的時間另計）。

手動步驟（瀏覽器）：

1. 在課程群組貼你的 GitHub username（不是 email），請 repo owner 邀請你。
2. 接受邀請：GitHub 會寄信給你，點 View invitation → Accept invitation。收不到信就直接打開 https://github.com/tingwei161803/evolving-intelligence/invitations。邀請 7 天後會失效，過期了請 owner 重發。

貼給 AI 的 prompt：

我已經有 GitHub 帳號，現在要加入一個 private repo（tingwei161803/evolving-intelligence）。
請告訴我要把什麼資訊給 repo owner，以及收到邀請後怎麼接受。
接受之後，請我在終端機跑 git ls-remote https://github.com/tingwei161803/evolving-intelligence.git，幫我判斷是否成功。
一次只給一步；GitHub 介面的按鈕名稱請保留英文原文。

怎麼確認成功：

• 瀏覽器：登入狀態下打開 https://github.com/tingwei161803/evolving-intelligence，看到檔案列表（astro/、docs/、AGENTS.md…），不是 404。
• 終端機（步驟 4 做完才能用）：

git ls-remote https://github.com/tingwei161803/evolving-intelligence.git  # 印出一堆 hash 和 refs/heads/main 就成功了

常見問題：

• 看到 404 或 Repository not found：還沒接受邀請，或者你登入的是另一個帳號（用 gh auth status 看是哪一個）。先打開上面的 invitations 網址。
• 收不到邀請信：看看垃圾信件匣，或直接打開 invitations 網址，邀請一定在那裡。

步驟 8：clone repo、第一次跑起來

目標：在自己的電腦上把網站跑起來。

你會得到什麼：瀏覽器打開 http://localhost:4321 看得到課程網站，改了檔案存檔後，畫面會自動更新。

預估時間：10 分鐘（npm install 看網速，大約 2～5 分鐘）。

8-1 clone repo、安裝套件、啟動：

# mac
cd ~/Documents
gh repo clone tingwei161803/evolving-intelligence
cd evolving-intelligence/astro
npm install
npm run dev

# Windows（PowerShell）
cd $HOME\Documents
gh repo clone tingwei161803/evolving-intelligence
cd evolving-intelligence\astro
npm install
npm run dev

看到 Local http://localhost:4321/ 就打開它。要停掉 dev server，按 Ctrl + C。

8-2 本機不用登入：npm run dev 時網站會自動跳過登入，打開就是首頁（ADR 0013）。

• 測試中的頁面也看得到：本機會把你當成 admin，/etepm/lab、/aixgs/lab 會列出還在測試（testing）的頁面，方便你看自己做的新頁面。
• 只在你自己的電腦上有效：正式站照樣要登入。

8-3（選做）連 API 一起跑：要測留言、互動牆這類會存資料的功能時才需要。只做頁面的同學可以跳過，也可以請 superadmin 帶你做。

npm run dev 本身就有 API 和本機資料庫，但本機資料庫一開始是空的，存資料又要先登入，所以要先建表、設一組自己用的關鍵字。下面在 astro/ 底下執行；我的本機關鍵字 換成你自己取的字，它只存在你電腦上的本機資料庫：

先建好本機資料庫的表。它會列出要套用的 migration，問 continue?，輸入 y 再按 Enter：

npm run db:migrate:local

設一組本機關鍵字：

node ../scripts/set-keyword.mjs normal_keyword_hash 我的本機關鍵字 --local

啟動（已經開著的話不用重開）：

npm run dev

打開 http://localhost:4321/login，用任意名字加上你剛剛設的關鍵字登入。本機雖然會自動跳過登入，但不登入就拿不到存資料用的通行證，留言、發卡片會失敗。

想看跟正式站一模一樣的 build（例如測 _redirects、404 頁）時，改跑 npm run cf:dev，打開 http://localhost:8787。

• 一定要帶 --local：不帶的話會改到正式站的資料庫，只有 superadmin 可以這樣做。
• 一定要在 astro/ 底下跑：在 repo 根目錄跑 npx wrangler，會另外下載一個不同版本的 wrangler，本機資料庫被它改過之後，astro/ 裡的版本可能就打不開了。

貼給 AI 的 prompt：

我要在自己電腦上把一個 Astro 網站跑起來。repo 是 tingwei161803/evolving-intelligence（private，我已經被加進 repo，也用 gh auth login 登入了）。
網站原始碼在 astro/ 子資料夾，我已經裝好 Node 22.12 以上。

請帶我完成：
1. 用 gh repo clone 把 repo 抓到我的「文件」資料夾
2. cd 進 astro/，跑 npm install
3. 跑 npm run dev，用瀏覽器打開 http://localhost:4321

規則：
- 先問我用 mac、Windows 還是 Linux。
- 一次只給一條指令，等我貼回輸出你確認成功才往下。npm install 會印很多 warning，請幫我判斷哪些可以忽略。
- 如果 Windows PowerShell 出現「因為這個系統上已停用指令碼執行」，請解釋原因並教我用最小權限的方式解決。
- 打開網頁應該直接看到首頁（npm run dev 會自動跳過登入）。如果被導到登入頁，代表我的 repo 不是最新的，請帶我 git pull 再試。
- 最後請我截圖首頁給你看，確認跑起來了。

怎麼確認成功：瀏覽器打開 http://localhost:4321，看到課程首頁的卡片區。

常見問題：

• 改名前就 clone 過的人（資料夾叫 2026-1142-ETEPM）：在 repo 根目錄跑 git remote set-url origin https://github.com/tingwei161803/evolving-intelligence.git，再用 git remote -v 確認網址變了。本機資料夾名稱（2026-1142-ETEPM）不用改。想改也可以，但改完要從新的資料夾啟動 AI 工具。
• gh repo clone 說 Could not resolve to a Repository：還沒接受 repo 邀請，回到步驟 7。
• Windows PowerShell 說「npm.ps1 無法載入」：執行 Set-ExecutionPolicy -Scope CurrentUser RemoteSigned，選 Y，重開 PowerShell。
• npm install 出現 EACCES 權限錯誤（mac）：通常是以前用 sudo npm 裝過東西。不要用 sudo npm install，把整段錯誤訊息貼給 AI 處理。
• npm run dev 說 port 4321 被占用：你可能已經在別的視窗開了一個 dev server。把它關掉，或改用畫面上它自動換的 port。

步驟 9：讓 AI 讀到專案規範

目標：AI 工具開在 repo 資料夾時，會自動讀到專案規則（走 PR、不刪檔、commit 寫繁中…）。

你會得到什麼：AI 幫你改程式時會自己遵守規則，不會直接 push 到 main，也不會亂刪檔案。

預估時間：5 分鐘。

手動步驟：cd 到 repo 根目錄（文件/evolving-intelligence，不是 astro/），啟動步驟 6 裝好的 AI 工具（claude、codex 或 agy）。

各工具讀哪個檔：

第一次在 repo 裡開 AI 時要貼的 prompt（之後每次開新 session 也建議貼）：

請先完整讀過這個 repo 根目錄的 AGENTS.md（規則正本；CLAUDE.md 只是引用它。如果你沒有自動讀到，請直接打開那個檔案讀）。
讀完後用三句話跟我複述最重要的規則，至少要涵蓋：
1. 改東西要怎麼提交（branch / PR / 誰能 merge）
2. 不能刪檔時要怎麼做
3. commit message 和 changes/ 小檔（CHANGELOG）的規定

我是 git 新手，之後每個 git 指令請先跟我說它會做什麼、再執行。
不要直接 push 到 main、不要 force push。
merge PR 可以由你來做，但每次都要我開口叫你 merge，而且 merge 前你要先確認三件事，有一件不成立就停下來告訴我：
- 有別人（不是我）按了 approve，或 PR 上有一則留言明確同意 merge（人或 AI 寫的都算，例如 /branch-review 的「✅ 可以 Merge」）：gh pr view <PR 編號> --json reviews,comments
- CI 全部是綠的：gh pr checks <PR 編號>
- PR 有改到 migrations/、wrangler.toml、.github/、astro/src/server/auth/、astro/src/middleware.ts、AGENTS.md、CLAUDE.md 的話，approve 或同意留言要來自張庭維
確認完用 gh pr merge <PR 編號> --merge（一律 merge commit，不要 squash、不要 rebase）。
commit 和 PR 裡不要加任何 AI 工具署名（例如 Co-Authored-By 或 Generated with ...）。

怎麼確認成功：AI 複述的三句話裡要有這三件事，少一項就請它重讀：

1. 開 feature branch 和 PR；要有人 approve 或留言同意 merge，CI 也要是綠的，才能 merge。
2. 要拿掉的檔案用 git mv 搬到 archive/，不要刪除。
3. commit 用繁體中文，加 feat:、fix: 這類前綴；每個 PR 新增一個 changes/<branch>.md。

常見問題：

• AI 說找不到 AGENTS.md 或 CLAUDE.md：你啟動 AI 的位置不在 repo 根目錄。先 cd 到 evolving-intelligence（不是 astro/），再啟動。
• 用網頁版 ChatGPT / Claude Desktop：它讀不到你的硬碟，請把 AGENTS.md 全文複製貼給它，或上傳這個檔案。不要貼 CLAUDE.md，它只有一行 @AGENTS.md，貼了沒用。
• AI 還是想直接 push 到 main：叫它停下來，再貼一次上面的 prompt。這個 repo 設不了 branch protection，所以沒有技術上的防線。真的 push 上去的話，guard-main 會自動開一個 issue 通知 superadmin；請主動在群組說一聲，不要用 --force 去蓋掉。

開發篇（每次開發都看這裡）

每次開發的共同流程

同步 main → 開 branch → 改檔案 → npm run dev 本機看 → commit → push → gh pr create → 貼 PR 連結到群組 → 等 review → 照意見修改 → 有人 approve 或留言同意後 merge

下面的指令都在 repo 根目錄執行（mac / Windows 相同）。<你的功能名> 換成全小寫英文加連字號，例如 ward-checklist。

git switch main
git pull
git switch -c feat-<你的功能名>

改完檔案、在本機確認過之後：

git add <改過的檔案>
git commit -m "feat: 新增查房清單頁（testing）"
git push -u origin feat-<你的功能名>
gh pr create --base main --assignee @me --fill-first

--fill-first 會先拿 commit message 當 PR 的說明，這樣還不夠。PR 開好之後，到 GitHub 上的 PR 頁面按 Edit，照 template 的六段補完說明：為什麼要改、改了什麼、必要 / 可選、已知遺留問題、Test plan、相關 issue。請 AI 開 PR 的話，叫它照 .github/pull_request_template.md 寫好再開。只有一行說明的 PR，review 會被擋下來。

規則速記（完整規則在 AGENTS.md）：

• merge 的條件（ADR 0020）：有人按 approve，或 PR 上有一則同意 merge 的留言（人或 AI 寫的都算），而且 CI 是綠的，你就可以自己 merge。
  • PR 改到 migrations/、wrangler.toml、.github/、astro/src/server/auth/、astro/src/middleware.ts、AGENTS.md、CLAUDE.md 時，approve 或同意留言要來自張庭維。
  • CI 會在每個 PR 自動 build 網站、掃描有沒有不小心放進 secrets、檢查型別，再把網站跑起來確認每一頁都打得開。PR 頁面下方出現綠色勾勾才算過；紅色叉叉的話，點進去看是哪一步失敗，把錯誤訊息貼給 AI。
• 每個 PR 都要新增 changes/<branch>.md：不要改 CHANGELOG.md，發版時才會彙整。
• 不要刪檔：要拿掉的檔案用 git mv 搬到 archive/。
• commit 和 PR 不加 AI 署名。

要 merge 時：可以自己按 GitHub 上的 Merge 按鈕（選 Create a merge commit），也可以請 AI 做，把這段貼給它：

請幫我 merge PR <PR 編號>。merge 前先確認三件事，有一件不成立就停下來告訴我，不要 merge：
1. 有別人（不是我）approve，或 PR 上有一則留言明確同意 merge（人或 AI 寫的都算）：gh pr view <PR 編號> --json reviews,comments
2. CI 全部是綠的：gh pr checks <PR 編號>
3. 如果改到 migrations/、wrangler.toml、.github/、astro/src/server/auth/、astro/src/middleware.ts、AGENTS.md、CLAUDE.md，approve 或同意留言要來自張庭維
都確認了才用 gh pr merge <PR 編號> --merge（不要 squash、不要 rebase），merge 完把 merge commit 的連結給我。

A. 我已經有做好的 HTML 或原型

適用：用 ChatGPT / Claude 做好的單頁 HTML，或是已經做好的小工具。

1. 開 branch：git switch main、git pull、git switch -c feat-<slug>。<slug> 就是網址名，全小寫英文加連字號，例如 ward-checklist。

2. 決定這頁屬於哪門課：檔案放哪裡、網址是什麼，都看這頁屬於哪門課（ADR 0001）。不確定的話就問 owner。

3. 把 HTML 放進頁面：Astro 頁面就是 HTML 最上面多一段用 --- 包起來的設定。外框由 BaseLayout 負責，包括 <html>、<head>、登入檢查和右下角的回饋按鈕；你只要放頁面本身的內容。

下面以 pages/aixgs/ 底下的頁面為例；放在根層的頁面，要把 ../../ 改成 ../：

---
import BaseLayout from '../../layouts/BaseLayout.astro';
---
<BaseLayout title="查房清單" description="一句話描述" baseStyles={false}>
  <Fragment slot="head">
    <style is:global>
      /* 原本 <head> 裡的 CSS 原封不動貼進來 */
    </style>
  </Fragment>

  <!-- 原本 <body> 裡的 HTML -->

  <script is:inline>
    // 原本的 JS 原封不動貼進來
  </script>
</BaseLayout>

要注意的地方：

• baseStyles={false}：不套全站的樣式，你的原型才會跟原本長得一樣。
• CSS 用 <style is:global>：沒寫 is:global 的話，Astro 會把樣式限縮在這個檔案裡，JS 產生的元素就套不到樣式。
• <script> 一律加 is:inline：Astro 才不會改寫你的 JS。不加的話，Astro 會把它當成模組打包，原型裡的全域變數、onclick="..." 可能會失效。
• 外框不要自己做：不要自己寫 <html> / <head>，也不要 import GateRedirect，登入檢查已經在 BaseLayout 裡了。
• innerHTML 的插值要 escape：寫成 innerHTML = `...${變數}...` 的地方，變數都要包 escapeHtml()（實作在 AGENTS.md §6）。這是 repo 的安全規定。
• 外部的 <script src> 和 fetch 會被擋：正式站的安全設定（astro/public/_headers 的 CSP）只允許本站的 script，fetch 也只能打本站；Google Fonts 例外，可以用。
  • 原型用到 Chart.js、Tailwind CDN 這類東西：請 AI 改成 npm install 後 import，或在 PR 裡提出要改 CSP。
  • 本機看不出來：npm run dev 不套用這個設定，本機正常、上線才壞，所以要主動檢查。

4. 登記到註冊表：在 astro/src/data/registry.ts 的 registry 陣列加一筆。新功能的 status 一律先設 testing：

{ slug: 'ward-checklist', course: 'aixgs', status: 'testing', kind: 'astro', href: '/aixgs/ward-checklist', title: '查房清單', description: '一句話描述', icon: '📋', owner: '你的 GitHub 帳號' },

5. 在本機確認：cd astro && npm run dev，打開你的網址（例如 http://localhost:4321/aixgs/ward-checklist），檢查：

• 畫面正常。
• Console 沒有紅字。
• 手機寬度不跑版（用 DevTools 的手機模式看）。

6. 寫變更小檔：新增 changes/feat-<slug>.md，內容是 ### 新增，下面一行寫改了什麼、為什麼。不用寫 PR 編號，也不要改 CHANGELOG.md。

7. commit → push → 開 PR：PR 要 assign 給自己（--assignee @me），description 寫為什麼做、改了哪些檔、怎麼測的。

8. 把 PR 連結貼到群組，並標記 owner。

原型有自己的後端怎麼辦（例如原型的留言板會存資料）：這次只搬前端，存資料的部分先用假資料或 localStorage 代替。在 PR description 加一段「後端需求：需要 superadmin 協助（D1 / Cloudflare）」，寫清楚要存什麼欄位、誰能讀寫。不要自己改 astro/src/pages/api/ 或 migrations/。

貼給 AI 的 prompt：

這是我做好的一個單頁 HTML（貼在最下面）。請照這個 repo 的 AGENTS.md 規則，幫我把它放進 repo 成為一個子頁面。

基本資料：
- 網址名（slug）：___（例如 ward-checklist）
- 放在哪個課程：___（四選一：etepm 專屬 / aixgs 專屬 / shared 兩門課共用 / site 全站、跟課程無關）
- 如果選 shared：資料要不要分課程？___（要 → 同一頁掛在 /etepm/<slug> 和 /aixgs/<slug>；不要 → 放根層 /<slug>）
- 卡片標題：___；一句話描述：___
- 狀態先設 testing

請依序做，每做完一步跟我說做了什麼、等我說 OK 再下一步：
1. 先讀 AGENTS.md（規則正本；CLAUDE.md 只是引用它），確認目前在 main 且是最新（git switch main、git pull），然後開新 branch feat-<slug>。
2. 依課程決定檔案位置：etepm → astro/src/pages/etepm/<slug>.astro；aixgs → astro/src/pages/aixgs/<slug>.astro；
   shared 且資料分課程 → 內容寫成元件，etepm/ 和 aixgs/ 各放一個頁面 import 它；shared 且資料不分、或 site → astro/src/pages/<slug>.astro。
   參考 astro/src/pages/etepm/quotes.astro 的外框寫法：用 <BaseLayout baseStyles={false}> 包住內容，原本 <head> 裡的東西放進 <Fragment slot="head">；
   不要自己寫 <html>/<head>，不要 import GateRedirect；CSS 一律放 <style is:global>（不然 JS 產生的元素套不到樣式）；所有 <script> 加 is:inline；CSS/JS 盡量原封不動。
3. 檢查所有 innerHTML 插值，有變數的都包 escapeHtml()（用 AGENTS.md §6 那份實作）。
4. 在 astro/src/data/registry.ts 加一筆，course（shared 要加 sharedScope）、status 照上面填，kind 填 astro，href 是上面決定的網址。
5. 新增 changes/feat-<slug>.md：標題 ### 新增，下面一行寫改了什麼、為什麼（一到三句，不寫 PR 編號）。不要改 CHANGELOG.md。
6. 跑 cd astro && npm run build，確認沒有錯誤，再跑 npm run check（型別檢查）和 npm run precommit。
7. 請我跑 npm run dev，開 http://localhost:4321 加上這頁的網址，給我一份驗證清單逐項確認：
   □ 畫面跟原本的 HTML 一樣
   □ 按鈕、互動都能用
   □ F12 Console 沒有紅色錯誤
   □ DevTools 手機模式（iPhone 寬度）不跑版
   □ 沒有引用外部 CDN 的 <script src> 或 fetch 外部網址（正式站 CSP 會擋，本機 dev 看不出來）
8. 驗證都過了再 commit（繁中、feat: 前綴，不要加任何 AI 署名），push，
   用 gh pr create --base main --assignee @me 開 PR，description 照 .github/pull_request_template.md 寫，test plan 寫上我們驗過什麼。
9. 給我 PR 連結。先不要 merge：等有人 approve 或有同意 merge 的留言（可以請 AI 跑 /branch-review 留言）、CI 變綠，我會再叫你 merge。

如果原本的 HTML 有存資料到後端（fetch 到某個 API、留言板等），這次只搬前端，存資料先用假資料，
並在 PR description 加一段「後端需求：需要 superadmin 協助（D1 / Cloudflare）」寫清楚需要什麼。

--- 以下是我的 HTML ---
（貼在這裡）

B. 我只有想法，還沒開發

1. 先登記，避免跟別人撞題：協作者到 Google Sheet「AIXGS 網站開發進度表」登記標題、你的名字和一句話描述。
   • Sheet 在哪裡：連結在 repo 的 links.md，被加進 repo 才打得開。
   • 先搜一下：有人登記過類似的，就直接加入對方。
   • 還不是協作者的同學：在群組說，或用每頁右下角的「💬 回饋」提。
2. 用 AI 做最小可驗證原型：單一頁面、假資料、不接後端。目標是「讓別人點得到、能給意見」，不是做出完整的產品。
3. 照 A 的流程放上去，狀態設 testing。
4. 收回饋：在群組請 2～3 個人試用，回饋可以留在 PR、Sheet，或用頁面右下角的「💬 回饋」。
5. 轉成 live：符合下面 C 的條件後，開一個小 PR 把 status 改成 live。

貼給 AI 的 prompt：

我想在課程網站上做一個新功能，但還沒開始寫。網站是 Astro 專案，頁面依課程放在 astro/src/pages/etepm/、astro/src/pages/aixgs/ 或根層（規則見 docs/decisions/0001），規範在 AGENTS.md。

我的想法：___（一兩句話描述）

請不要馬上寫程式。先問我 3 個問題，一次問一個：
1. 這個功能給誰用？（學生 / 助教 / 老師，在什麼情境下用）
2. 最小可以驗證價值的功能是什麼？（只留一個核心動作，其他都砍）
3. 資料從哪裡來？（寫死的假資料 / 使用者輸入只存在瀏覽器 / 需要後端存起來）

我回答完後，請：
- 用 5 行以內總結你要做的東西，等我確認。
- 做成單一 .astro 頁面（用 BaseLayout 包住，先問我屬於哪門課再決定放哪）、假資料、不碰 astro/src/pages/api/ 和 migrations/。如果需要後端，在 PR description 標「需要 superadmin 協助」。
- 照 AGENTS.md 開 branch、在 registry.ts 登記一筆（status: testing）、新增 changes/<branch>.md、escapeHtml 處理 innerHTML。
- 請我跑 npm run dev，並請我截圖桌機和手機寬度的畫面給你看，你確認沒問題才 commit。
- commit / PR 不加 AI 署名，PR assign 給我自己。先不要 merge：等有人 approve 或有同意 merge 的留言（可以請 AI 跑 /branch-review 留言）、CI 變綠，我會再叫你 merge。

C. 什麼時候從「測試中」改成「上線」

新功能一律先設 testing。要改成 live，下面每一項都要打勾：

卡住了怎麼辦

這些事一定要找 superadmin（不要自己動，也不要叫 AI 動）：

• 資料庫：新增或修改 migrations/，或任何需要存資料的功能。
• Cloudflare 設定：Pages 專案設定、wrangler.toml、部署失敗。
• 網域 / DNS：網址、子網域、轉址。
• secrets：登入關鍵字、API key、任何 wrangler secret。這些不能出現在 commit、PR、群組訊息或 AI 對話裡。
• 帳號權限：要變成 admin、要邀請新同學、改 repo 設定。

求助時在群組貼這四樣：

1. 你在做什麼（附 PR 連結）。
2. 卡在哪一步。
3. 錯誤訊息全文（截圖也可以）。
4. 你已經試過什麼。