臺北市政府 AI 開發規範包

請 AI 幫您寫程式時，搭配這份規範包，做出來的網頁會符合臺北市政府的版面風格，也會遵守 AI 使用的相關規定。

---

這是什麼？

現在很多 AI 工具（例如 Claude Code、OpenAI Codex、Gemini CLI、Google Antigravity、GitHub Copilot）都可以幫忙寫程式。您只要用中文說「幫我做一個活動報名網頁」，它就會寫出來。

不過，AI 每次做出來的樣子都不一樣，常常是藍紫色漸層加上許多表情符號，看起來不像政府網站；它也不知道政府機關有哪些規定要遵守。

這個規範包就是一份「給 AI 看的工作守則」。把它放進您的資料夾，AI 開工前會先讀過，做出來的網頁可以做到：

• 長得像臺北市政府的網站，有您機關的 Logo，有完整的頁尾資訊
• 用公務機關平常講話的方式寫文字
• 符合無障礙規範，長輩和視障朋友也能使用
• 保護民眾個資，不蒐集不必要的資料
• 遵守《人工智慧基本法》和行政院、臺北市政府的 AI 使用規定

裡面有哪些檔案？

檔案	用途	白話說明
soul.md	AI 的基本立場與法規紅線	告訴 AI「你在替市政府做事，哪些事絕對不能做」
SKILL.md	開發規範與網頁範本	告訴 AI「網頁要做成什麼樣子、文字怎麼寫、程式怎麼寫」
README.md	安裝說明	就是您現在在看的這份

您不需要看懂 soul.md 和 SKILL.md 的內容，那是寫給 AI 看的。有興趣的話，也可以打開來看。

---

開始之前，您需要準備

1. 一部電腦（Windows 或 Mac 都可以）
2. 一個 AI 開發工具，而且已經安裝好、可以使用，例如 Claude Code、OpenAI Codex、Gemini CLI、Google Antigravity、VS Code 加上 GitHub Copilot、Cursor。

請注意：瀏覽器裡的 ChatGPT、Gemini、Claude 聊天網頁，沒辦法在您的電腦上建立檔案，不適用這份說明。一定要用上面這類會在您電腦資料夾裡工作的「開發工具」。

還沒有 AI 開發工具的話，請先洽詢機關資訊單位，確認機關允許使用哪一種、要用哪個帳號申請。依臺北市政府的規定，外部 AI 服務的帳號應該用市府公務信箱申請。

---

安裝步驟

第一步：下載規範包

1. 打開這個網址：https://github.com/taipei-doit/TP_AI_Agent_soul_skill （不用登入）
2. 找到綠色的「Code」按鈕，按下去
3. 選最下面的「Download ZIP」
4. 下載完成後，到「下載」資料夾找到 TP_AI_Agent_soul_skill-main。Windows 通常不會顯示後面的 .zip，圖示是一個有拉鍊的資料夾。
5. 在檔案上按滑鼠右鍵，選「解壓縮全部」（Windows）或直接雙擊（Mac）

解壓縮後會出現一個資料夾。打開後如果裡面還有一層同名資料夾，就再點進去，可以看到 soul.md、SKILL.md、README.md 三個檔案。Windows 可能只顯示 soul、SKILL、README，沒有後面的 .md，這是正常的。

第二步：建立您的工作資料夾

每做一個新的網頁或系統，就開一個新的資料夾。

1. 在桌面（或您習慣的位置）按滑鼠右鍵，選「新增」→「資料夾」（Mac 是「新增檔案夾」）
2. 取一個看得懂的名字，例如 講座報名網頁
3. 把剛剛下載的 soul.md 和 SKILL.md 複製到這個資料夾裡

現在您的資料夾裡有這兩個檔案：

講座報名網頁
  soul.md
  SKILL.md

第三步：讓 AI 工具在這個資料夾裡工作

AI 開發工具要「進到」您的資料夾，才能讀到規範、在裡面建立檔案。依您用的工具，照下表操作：

AI 工具	操作方式
Claude Code（桌面程式）	打開程式，在開新對話的地方選擇資料夾，選「講座報名網頁」
VS Code ＋ GitHub Copilot	打開 VS Code，點上方「檔案」→「開啟資料夾」，選「講座報名網頁」。再打開 Copilot 對話視窗，在輸入框下方的模式選單把「Ask」改成「Agent」（Agent 模式才能幫您建立檔案）
Cursor	打開 Cursor，點「Open Folder」，選「講座報名網頁」
Google Antigravity	打開 Antigravity，點「Open Folder」（開啟資料夾），選「講座報名網頁」
Claude Code、Codex、Gemini CLI（終端機版）	見下方說明

終端機版的操作方式

「終端機」是一個黑色或白色的文字視窗，用打字的方式操作電腦。

• Windows：按開始選單，搜尋「PowerShell」並打開。
• Mac：打開「應用程式」→「工具程式」→「終端機」。

打開後：

1. 輸入 cd，按一下空白鍵。
2. 用滑鼠把「講座報名網頁」資料夾拖進這個視窗，畫面上會自動出現資料夾的位置。按 Enter。
3. 依您用的工具，輸入 claude、codex 或 gemini，按 Enter。

（如果您用的是 Windows 的「命令提示字元」而不是 PowerShell，而且資料夾不在 C 槽，第 1 步請改輸入 cd /d。）

第四步：請 AI 幫您完成設定

接下來還要建立幾個設定檔，讓不同的 AI 工具都能找到這兩個檔案。這些設定檔有的放在隱藏資料夾裡，自己動手容易出錯，直接請 AI 幫您做就好。

1. 把下面框框裡的文字整段複製（在 GitHub 網頁上看的話，框框右上角有複製按鈕），貼給 AI，按 Enter 送出：

請幫我在這個資料夾完成「臺北市政府 AI 開發規範包」的設定，照下面步驟做，不要做其他修改。

步驟一：建立資料夾 .claude/skills/taipei-gov-dev/，把 SKILL.md 移進去（檔名維持 SKILL.md）。

步驟二：soul.md 留在原位，不要移動。

步驟三：建立 AGENTS.md，內容是下面「===開始===」和「===結束===」之間的文字，不含這兩行：
===開始===
# 專案規範

本專案由臺北市政府同仁使用。開始任何工作前，必須先完整閱讀下列兩個檔案，並在整個工作過程中遵守：

- soul.md：AI 協助公務的基本立場與法規紅線，優先於其他所有規定
- .claude/skills/taipei-gov-dev/SKILL.md：臺北市政府網頁開發規範與範本

你所使用的工具即使不支援 Skill 功能，也請直接開啟上述 SKILL.md 檔案閱讀。
若無法讀取這兩個檔案，請先告知使用者，不要直接開始開發。
===結束===

步驟四：建立 CLAUDE.md，內容是下面「===開始===」和「===結束===」之間的兩行，不含標記：
===開始===
@AGENTS.md
@soul.md
===結束===

步驟五：建立 GEMINI.md，內容和 CLAUDE.md 完全相同。

步驟六：建立 .github/copilot-instructions.md，內容和 AGENTS.md 完全相同。

步驟七：建立 .agents/rules/taipei-gov.md，內容是下面「===開始===」和「===結束===」之間的文字，不含標記：
===開始===
---
trigger: always_on
description: 臺北市政府 AI 開發規範
---
@[soul.md](../../soul.md)

開發任何網頁或程式前，必須先完整閱讀 @../../.claude/skills/taipei-gov-dev/SKILL.md ，並依照其中的規定進行。
===結束===

完成後，請逐行列出這個資料夾裡所有檔案的路徑（包含隱藏檔），讓我確認。

2. AI 動手前可能會用英文詢問您是否允許，例如「Do you want to create AGENTS.md?」，請選第一個「Yes」。如果您選了「Yes, and don't ask again」，.claude 資料夾裡可能會多出一個 settings.local.json，這也是正常的。
3. 完成後，AI 會列出檔案清單。顯示方式可能和下面不太一樣（例如前面多了 ./），只要下面這 7 個都有出現就對了：

soul.md
AGENTS.md
CLAUDE.md
GEMINI.md
.claude/skills/taipei-gov-dev/SKILL.md
.github/copilot-instructions.md
.agents/rules/taipei-gov.md

名稱開頭是「.」的資料夾是隱藏資料夾，在檔案總管或 Finder 裡預設看不到，這是正常的，不是 AI 沒有做。想看的話：Windows 在檔案總管上方點「檢視」→「顯示」→ 勾選「隱藏的項目」；Mac 在 Finder 裡按 Command＋Shift＋句點。

第五步：確認 AI 有讀到規範

請先關掉 AI 工具再重新打開，讓它重新讀取設定：

• 桌面程式：直接關閉程式再打開，並選同一個資料夾。
• 終端機版：輸入 /exit 按 Enter（或直接關掉視窗），再照第三步重新進入資料夾、啟動 AI。

然後問它：

請用三點說明，你在這個專案裡開發程式時要遵守哪些規定？

如果 AI 的回答提到「臺北市政府」「個資」「無障礙」「機密文書」「局處 Logo」這類內容，就代表設定成功了。

如果 AI 回答得很籠統，或完全沒提到臺北市政府，請看下面的「常見問題」。

---

開始請 AI 開發

設定完成後，就可以直接用中文告訴 AI 您要什麼。說得越具體，做出來越接近您要的。

範例一：活動報名

我是臺北市政府社會局的承辦人，要做一個「長青學苑秋季班」的線上報名網頁。
民眾要填姓名、手機、想上的課程（書法、太極拳、手機入門三選一）。
報名資料只用來通知上課，活動結束後 3 個月刪除。

範例二：查詢服務

我是臺北市政府環境保護局的承辦人，想做一個網頁讓民眾輸入地址，查詢那一區的垃圾車時間。
資料我有一份 Excel 檔，我等一下放進資料夾。

範例三：內部小工具

我是臺北市政府文化局的承辦人，想做一個內部用的小工具，
把每個月的活動清單（Excel）轉成可以直接貼到官網的表格格式。
只有我們科裡的同仁會用。

AI 開工前可能會問您幾個問題，例如「這個網頁給誰用」「會不會蒐集個資」「要做到哪個無障礙等級」，照實回答就好。不知道的可以直接說不知道，AI 會先用預設值處理，再請您確認。

做完之後，AI 會附上一份「交付說明」，告訴您做了什麼、怎麼打開來看、哪些地方需要您確認或補上。請一定要看完這份說明，特別是「需要您補上或確認的地方」。

---

進階：讓每個新資料夾都自動套用

如果您經常開新專案，不想每次都重做第二步到第四步，可以把規範裝到您電腦的「全域設定」，以後在任何資料夾都會套用。

這個做法目前只確定 Claude Code 適用。請在 Claude Code 裡貼上：

請幫我把這個資料夾裡的 SKILL.md 和 soul.md 安裝到我電腦的全域設定：
1. 把 SKILL.md 複製到 ~/.claude/skills/taipei-gov-dev/SKILL.md
2. 把 soul.md 複製到 ~/.claude/taipei-gov-soul.md
3. 在 ~/.claude/CLAUDE.md 的最後加上一行：@~/.claude/taipei-gov-soul.md
   （如果 ~/.claude/CLAUDE.md 不存在，就新建一個）
完成後告訴我各檔案的完整路徑。

其他 AI 工具，建議還是每個資料夾各自設定一次，比較穩當。

---

常見問題

問：AI 好像沒有照規範做，做出來還是藍紫色的。

答：請依序試試看：

1. 關掉 AI 工具再重新打開。
2. 直接跟它說：「請先閱讀 soul.md 和 .claude/skills/taipei-gov-dev/SKILL.md，然後依照裡面的規定重新做。」
3. 確認第四步的檔案都有建立（請 AI 列出所有檔案，包含隱藏檔）。
4. 使用 Claude Code 的話，請確認已更新到最新版本。

問：我用的 AI 工具不在上面的清單裡，可以用嗎？

答：多半可以。大部分 AI 開發工具都會自動讀取 AGENTS.md。如果設定完成後，它答不出第五步的確認問題，請在每次開新對話時，先貼上這句話：「請先閱讀 AGENTS.md，並依照其中指示閱讀 soul.md 與 SKILL.md。」

問：AI 說它找不到我們機關的 Logo。

答：AI 會先到機關官網找。找不到時，它會先用機關名稱的文字代替。您可以從機關官網的頁首另存 Logo 圖片，放進資料夾，告訴 AI：「Logo 檔案是 logo.png，請換上去。」

問：AI 拒絕做我要的功能，說違反規定。

答：這表示規範有發揮作用。AI 會說明理由，多半也會提出替代做法。常見的例子：

• 要它處理標示機密的檔案 → 機密文書依規定不能用 AI 處理
• 要它做「系統自動判斷、自動通知民眾不符資格」→ 要加上人工確認的步驟
• 要它在畫面上顯示完整的身分證字號 → 要遮蔽部分號碼

如果您認為您的需求有法律依據、應該可以做，請洽詢機關的法制或資訊單位。

問：AI 問我「無障礙要做到 AA 還是 AAA」，我不知道怎麼回答。

答：直接說「依你的建議」就好。AI 會依網頁的功能判斷：功能單純的頁面（例如只有一個表單）建議做到最高的 AAA；功能複雜的（例如有地圖）至少做到 AA。

問：AI 做好了，可以直接放上網路嗎？

答：不行。 請先：

1. 自己實際操作一遍，確認功能正常、文字正確。
2. 看完 AI 的交付說明，補上所有標示〔請填入〕的地方。
3. 交給機關資訊單位，由他們協助設定主機、HTTPS、資安檢測、無障礙檢測後再上線。

問：我可以把民眾的真實資料給 AI，讓它幫我測試嗎？

答：不可以。 依行政院和臺北市政府的規定，不得把個人資料提供給外部 AI 服務。請用假資料測試，例如「王小明」「0912-345-678」。AI 也會主動用假資料。

問：檔案名稱一定要是 SKILL.md 嗎？可以改成小寫嗎？

答：請維持 SKILL.md（全部大寫），Claude Code 只認得這個檔名。soul.md 則維持小寫。

問：規範更新了怎麼辦？

答：重新從第一步下載，用新的 soul.md 和 SKILL.md 覆蓋舊的就好。如果您的資料夾已經設定過，先把新的 SKILL.md 放進資料夾最上層，再請 AI 幫您：「請用資料夾最上層新的 SKILL.md 覆蓋 .claude/skills/taipei-gov-dev/SKILL.md，完成後刪除最上層那份 SKILL.md。」新的 soul.md 直接覆蓋舊的即可。

---

給機關資訊單位的說明

• SKILL.md 採用 Agent Skills 格式（YAML frontmatter ＋ Markdown），name 為 taipei-gov-dev，只放一份在 .claude/skills/taipei-gov-dev/。Claude Code、VS Code Copilot、Cursor 會從這個位置載入 Skill；Codex CLI、Gemini CLI 不掃描 .claude/skills/，改由 AGENTS.md、GEMINI.md 指示直接讀取檔案。不另外複製到 .agents/skills/，是為了避免 VS Code 同時讀到兩份同名 Skill，也避免更新時兩份內容不一致。
• CLAUDE.md、GEMINI.md 的 @ 匯入語法只有 Claude Code 和 Gemini CLI 看得懂。GitHub Copilot 也會讀這兩個檔案，但只會看到文字，不會出錯；它另外從 AGENTS.md 與 .github/copilot-instructions.md 取得完整指示。
• Google Antigravity 會讀 AGENTS.md、GEMINI.md 與 .agents/rules/*.md，但只用 .agents/skills/ 載入 Skill，GEMINI.md 裡的 @soul.md 也只會變成檔案路徑、不會載入內容。因此另建 .agents/rules/taipei-gov.md（trigger: always_on），用 @[soul.md](../../soul.md) 把 soul.md 全文嵌入，SKILL.md 則以路徑指示讀取。Antigravity 單一規則檔上限 24 KB（嵌入後計算），soul.md 若日後擴寫，請注意不要超過。
• 其他未列出的工具（例如 Windsurf、Cline、JetBrains AI Assistant），多半支援 AGENTS.md；不支援時，請在每次對話開頭先輸入「請先閱讀 AGENTS.md，並依照其中指示閱讀 soul.md 與 SKILL.md」。
• soul.md 透過 CLAUDE.md、GEMINI.md 的 @ 匯入語法，在每次對話開始時載入；Codex、Copilot、Cursor 則由 AGENTS.md 指示讀取。Skill 只在 AI 判斷相關時才會載入，所以法規紅線放在 soul.md，確保每次都會讀到。
• Codex CLI 讀取 AGENTS.md 的預設上限是 32 KiB，因此 AGENTS.md 只放指引，不要把兩份檔案的全文貼進去。
• 機關若有自己的代表色、Logo 規範或內部資安規定，可以在 SKILL.md 或 soul.md 末尾增加「本機關補充規定」一節。主色更換後，請重新計算文字對比度。

參考資料

• 人工智慧基本法
• 行政院及所屬機關（構）使用生成式 AI 參考指引
• 臺北市政府使用人工智慧作業指引
• 數位發展部人工智慧風險分類框架
• 數位發展部網站無障礙規範
• 個人資料保護法、資通安全管理法、著作權法