跳至主要内容

實戰演練：跨專案 AI 防呆起手式 (Playbook)

當我們學會了 Workflow, Skill 以及 Knowledge Items (KI) 的「動態指針模式」後，接下來就是最實用的部分：當我今天開啟了一個全新的專案（例如切換到 liwenStudio），我該怎麼做才能用最快速度把 AI 防呆機制建立起來？

這是一套我親自驗證過，最無痛、最乾淨、最一勞永逸的「新專案 AI 起手式 SOP」。

Step 1: 建立專屬的本地教戰手冊​

在你的新專案根目錄下，手動建立一個名為 .agent 的檔案（沒有副檔名）。 將你針對這個專案的獨特要求寫進去。你可以參考以下的模板：

# AI Agent 協作守則與專案規範

這是本專案與 AI Agent 協作時的最高指導原則：

## 1. Git 操作與部署規範 (CRITICAL 🔴)
- **Push 前必須先進行本地端測試**：每次完成修改後，必須先啟動 `npm run start`，並請我先在 `localhost:3000` 進行確認。
- **未經授權，絕對禁止 `git push`**：必須先詢問並取得我的「明確文字授權」。
- **部署前必須進行 Build 檢查**：在收到許可後，禁止直接 Push。必須先執行 `npm run build` 攔截死結或語法錯誤。
- **部署後主動監聽與防呆**：必須使用 `npx ghaction-lis` 監聽 GitHub Actions。若失敗，立刻解析 Error Log，主動詢問下一步，絕對禁止盲目修復。
- **維護根目錄整潔**：如果 AI 為了 debug 或攔截 Build 錯誤需要導出日誌檔，必須存放在 `.logs/` 資料夾內，嚴禁污染根目錄。

## 2. 專案專屬目錄與風格約定 (Docusaurus)
- **防暴雷機制**：課程實作筆記必須使用 `<details>` 將「解答程式碼」折疊隱藏起來。
- **統一的 Emoji 標籤**：`_category_.json` 必須包含 `"link": { "type": "generated-index" }`，且 `label` 必須包含 Emoji，防止數字誤判 Bug。
- **Frontmatter 設定**：部落格文章必須包含 `<!-- truncate -->` 標記與 SEO 屬性 (`slug`, `description` 等)。

💡 最佳實踐：請務必打開專案的 .gitignore，並把 .agent 加上去！這份檔案是你與本機 AI 之間的私人契約，不需要被提交到公開的 GitHub 上去污染原始碼。

Step 2: 召喚 AI，植入動態指針記憶​

這是最關鍵的一步！請在該專案的 IDE 裡開啟與 AI Agent (Antigravity) 的全新對話，然後直接複製、貼上這段**「最強咒語」**給它：

「我已經在專案根目錄建立好 .agent 檔案了。請幫我建立一個此專案專屬的 Knowledge Item (KI)，設定為**『動態指針模式』**：在 metadata.json 的摘要中下達強制指令，強迫未來的每次對話，都『必須』優先讀取專案根目錄下的 .agent 檔案，並以該檔案內的最新內容作為本專案的最高協作指導原則。」

Step 3: 享受一勞永逸的開發體驗​

執行完以上兩步後，AI 就會在這個專案的底層記憶庫中，為你植入一個「永遠掃描 .agent」的超強雷達。

從此之後：

  1. 你不需要再在每次對話開頭耳提面命「不要亂 Push」、「要照某個格式寫」。
  2. 你不需要再去手動跟 AI 說「我的規則更新了，請幫我更新 KI」。
  3. 你只需要專心維護專案裡的那份 .agent。未來不論你加了什麼新規定，AI 只要一「開機」，就會被雷達強制引導去閱讀最新版的內容！

這就是結合了本地靈活性與系統全域記憶的最強 AI 協作模式！🚀