Keyboard shortcuts

Press ← or → to navigate between chapters

Press S or / to search in the book

Press ? to show this help

Press Esc to hide this help

2. transition 時間審計 — 不應該有 300ms/500ms（只保留 1200ms、700 圖像、200 opacity）

grep -rn “duration-300|duration-500” src/ –include=“*.astro”

3. global.css !important 檢查

grep -rn “!important” src/styles/global.css

4. 定價格式審計 — 不應該有「K」縮寫在價格附近

grep -rn “NT$.K” src/pages/ –include=“.astro”

5. 技術名洩漏審計 — 行銷頁（排除 blog）不該有技術名

grep -rn “GitHub|Astro|Tailwind|Sveltia|Cloudflare” src/pages/ –include=“*.astro” | grep -v blog


**時機：每次建完一個新頁面後。每次 git push 前。**

---

### E. 除錯 SOP

| 症狀 | 第一步 | 第二步 |
|------|--------|--------|
| 「改了 class 但完全沒效果」 | global.css 有 `!important`？ | 硬重整 `Cmd+Shift+R` |
| 「線上版跟本地不一樣」 | Cloudflare 部署完沒？等 1-2 分鐘 | `curl -s https://網站 \| grep "關鍵字"` |
| 「有的卡片亮、有的不亮」 | 跑段落 D 審計 #1 — shadow 有幾種？ | 看哪一頁漏了 glow class |
| 「hover 跳太快或太慢」 | 跑段落 D 審計 #2 — duration 值統一嗎？ | 檢查 global.css 有無 `transition-duration: Xms !important` |
| 「後台進不去」 | `curl https://網站/admin/config.yml` — YAML 正常？ | 檢查縮排（2 格、fields 在 collection 下） |
| 「照片上傳後消失」 | 等 2-3 分鐘 Actions 轉檔 | 檢查 .md 引用是否 .jpeg → .webp |
| 「按鈕連結 404」 | 該頁面是否已刪除/改名？ | `grep -rn "href=\"/舊路徑\"" src/` |

#### 除錯黃金法則

① 先跑審計腳本（自動發現 80% 的問題） ② 比較本地 vs 線上：curl 確認部署狀態 ③ 比較兩站：正常的那站做對照組（如 ming-website 對照旅誌） ④ 一次只改一個變數，確認效果後再改下一個


---

### F. 起手式提示詞（貼入新 OpenCode session）

**完整版（包含所有關鍵規則）：**

在開始寫任何程式碼之前，請根據我的規範先建立兩份文件：

① AGENTS.md：記錄技術堆疊 + 技術規範（6 條必須遵守） ② 視覺規範表：主色、輔色、字體、圓角、hover光暈公式、 transition時間、badge風格、背景blur規格、手機優先原則

填完後讓我確認。確認後才能開始寫頁面。

設計規範（必須遵守）：

  • 所有對比表在手機上用直式卡片（hidden md:block / md:hidden）
  • 方案卡片手機單欄、桌面三欄（grid-cols-1 md:grid-cols-3）
  • hover 光暈公式只用一種：hover:shadow-[0_0_20px_rgba(主色,0.15)]
  • 全站 transition 只用一個值：duration-[1200ms]
  • 手機最小字體 16px

每個頁面建完後，請跑審計腳本確認沒有違反規範。 詳細規範參考：SETUP_GUIDE.md §0.5 前置作業規範


**加上你想要的風格：**

我要開一個新的 [旅遊部落格] 網站。風格選 [日落暖橙色]。

（風格選項見附錄 C：🌿侘寂 🌊海洋 🖤黑白 🌸粉嫩 🌲森林 🌅暖橙 🏙️城市 🎨撞色）

**部署後檢查順序（出問題時照這順序查，不要先懷疑程式碼）：**

① DNS（dig 網域 +short） ② Routes（Cloudflare 面板 → Workers Routes） ③ 部署狀態（Cloudflare → Deployments） ④ config.yml（grep “repo:” public/admin/config.yml） ⑤ 頁面硬編碼標題（grep “Layout title=” src/pages/*.astro） ⑥ 殘留舊部署檔（ls .github/workflows/deploy.yml） ⑦ 程式碼 bugs（最後才檢查）


---


# 卷二：開發與除錯（Development & Debugging）

## 第 4 章：OpenCode 協作 + 提示詞 {#opencode-guide}

> **👤 你：專案經理 — 決定做什麼、確認結果** — **🤖 AI：全端工程師 — 寫程式、跑審計、除錯**
>
> 你不是在「操作一個工具」，你是在跟一個全端工程師結對編程。你說需求，AI 寫程式。你測結果，AI 修問題。
> 以下每一節都標示了在這一步中，你該做什麼、AI 該做什麼。

### 4.1 Session 管理 {#opencode-session}

**第一次開新專案：**

我要建立一個 [網站類型] 網站。 使用 Astro + Tailwind + Sveltia CMS + Cloudflare 部署。 請先幫我建立 AGENTS.md，記錄技術堆疊和開發指令。 然後建立 PROJECT_NOTES.md 作為進度追蹤。


**每次開始新 Session：**

繼續 [專案名稱] 專案。路徑：[絕對路徑] 上次已完成：[摘要] 下一步要做：[任務] 請先確認 npm run dev 是否正常運行。


**Session 長度規則：**

| 情境 | 建議 | 原因 |
|------|------|------|
| 新功能開發 | 一個功能一個 session | context 乾淨，不會被舊程式碼干擾 |
| 除錯 | 一個 bug 一個 session | 太多錯誤訊息會讓 AI 混淆 |
| 微調（改色/改字/改間距） | 可以堆在同一個 session | 不影響架構 |
| 對話超過 30 輪 | 重開新的 | context 有上限，超過會遺忘前面的規則 |
| npm run dev 跑不起來 | 試第二次，不行就開新 session | 不要在同一個 session 裡試第三次 |

**跨 session 傳遞規則：** 每次結束貼這三行到 `PROJECT_NOTES.md`：

已完成：______ 卡住的地方：______ 下一步要做：______

下一個 session 第一句話貼這三行給 OpenCode。

**👤 你永遠不該交給 AI 的事：**

| 事 | 原因 |
|----|------|
| 輸入密碼、Token、信用卡號 | AI 對話可能被記錄 |
| 操作 Cloudflare 面板（刪除、改 DNS、Rollback） | 誤操作無法復原 |
| 註冊帳號（GitHub、Cloudflare、網域商） | 涉及簡訊/Email 驗證，AI 無法代勞 |
| 決定客戶報價 | AI 不知道你的成本、關係、客戶預算 |
| 決定何時 git push | 你決定何時部署、commit message 寫什麼 |
| **最終驗收**（肉眼判斷視覺、手機親測） | AI 沒眼睛，看不到瀏覽器渲染結果 |

**🤖 你該交給 AI 的事：**

| 事 | 原因 |
|----|------|
| 寫 .astro / .yml / .js 程式碼 | 全端工程師本職 |
| 跑審計（grep、audit.sh、lychee） | 自動化檢查不該人做 |
| 產出文件（AGENTS、PROJECT_NOTES、手冊更新） | AI 產文件比你快 |
| 對照新舊版本，提取教訓（§4.10 專案回顧） | AI 讀文件比你快 |
| 搜尋舊方法殘留（新入舊出） | grep 全文件，人做不到，漏掉一條就是 bug |

> **開新 session 前看這張表，3 秒判斷什麼用 OpenCode、什麼親手做。**

### 4.2 AGENTS.md 模板 {#opencode-agents}

```md
# 專案名稱
## Stack
- Astro v6 + Tailwind CSS v4
- Sveltia CMS（CDN）
- Cloudflare Workers
- Node >= 22.12.0

## Dev commands
npm run dev      # http://localhost:4321
npm run build    # 輸出到 dist/

## Key paths
| Path | Purpose |
|------|---------|
| src/content/blog/*.md | 部落格文章 |
| public/admin/config.yml | CMS 設定 |

## Deployment
git push → Cloudflare 自動部署
domain: https://xxx.xxx

每個 AGENTS.md 必須包含這條關鍵規則：

## 關鍵規則
- 新入舊出：任何修改都要搜尋並清除舊方法殘留，不允許新舊共存

4.3 測試循環 SOP

1. npm run dev → 本地確認
2. npm run build（0 error）
3. git add . && git commit && git push
4. 等 1-2 分鐘部署
5. 打開正式網址確認
6. 有問題 → 描述 + 回步驟 1

4.4 中斷後接續

繼續 ming-travel-blog 專案。
路徑：/Users/xxx/ming-travel-blog
上次完成：Lightbox 改用 <dialog>，手機和桌面正常。
現在問題：關於我頁面想換照片，但不確定流程。
請先看 PROJECT_NOTES.md 了解現狀，然後告訴我下一步。

4.5 黃金法則

#法則
1一次一件事，不要混雜需求
2每句話 = 問題 + 期望 + 上下文
3「試看看」信任循環：AI 改 → 你測 → 回報
4精確描述觀測結果
5每次結束都存 PROJECT_NOTES
6AGENTS.md 是第一印象
7犯錯直接說，比「再試試」有效
8讓 AI 自己檢查：「build 報錯，幫我看問題」
9做完掃技術名：grep -rn "GitHub|Astro|Sveltia|Zigbee|Home Assistant" src/pages/ --include="*.astro" | grep -v blog → 行銷頁不該出現這些字
10改一處，查全部：改完 A 檔案後，搜尋所有引用 A 的檔案是否也該連動修改（如：改了 index.html 的壓縮邏輯，admin-guide.astro 是否也要更新說明）
11新入舊出，不留殘留：新方法寫入的同時，必須搜尋並清除舊方法的殘留。不是只加新的，舊的錯誤資料不清 = 手冊信用破產 = 後續 bug 修不完。搜 grep -rn "舊的寫法" 所有.md 所有.astro，找到就換掉

4.6 技術名防洩漏檢查

客戶看到「Home Assistant」「Zigbee」「Intel N100」這些技術名會有兩個問題：① Google 比價 ② 覺得「不就是買零件」。所有行銷頁面（about、products、web-dev、contact、index）都應該用品牌化命名（如 AiHub C1），部落格保留 SEO 關鍵字。

每次建完新頁面後執行：

# 掃描行銷頁是否有技術名洩漏
grep -rn "Home Assistant\|Zigbee\|ESP32\|Intel N100\|mmWave\|Sveltia\|Astro\|Tailwind\|Cloudflare Workers\|GitHub Pages" src/pages/ --include="*.astro" | grep -v blog

# 如果有輸出 → 要在行銷頁模糊化
# 部落格（src/pages/blog/）的結果正常，保留

品牌化命名原則：

  • 產品/硬體：用代號（AiHub C1、AiSense S1）
  • 後台系統：對客戶說「智能管理後台」不是「Sveltia CMS」
  • 部署平台：對客戶說「全球高速節點」不是「Cloudflare Workers」
  • 網站技術：對客戶說「純靜態網站」不是「Astro + Tailwind」

4.7 有效提示 vs 無效提示

❌ 無效✅ 有效
「加一個燈箱」「攝影集點照片跳出全螢幕，← → 切換 + Esc 關閉」
「修一下 bug」「手機上分類選單打開後立刻關閉，請改用文字輸入」
「Footer 不對」「Footer 寫著 GitHub Pages，我們部署在 Cloudflare」
「顏色怪怪的」「暗色模式 blockquote 文字黑色看不到，改淺灰色」

4.8 回報問題格式

問題：手機上點分類選單會立刻跳掉
環境：iOS Safari / Chrome
步驟：後台 → 攝影集 → 編輯照片 → 點分類標籤
預期：打開下拉選單選分類
實際：選單打開後立刻消失

4.9 AI 卡住時的處理 SOP

AI 不是每次都一次到位。當它開始重複、幻覺、或產出錯誤程式碼時，你需要一個中斷流程。

① 症狀判定

症狀診斷對策
同一段程式改了 3 次還是錯不是你的問題，是提示詞沒說清楚回到②中斷
AI 開始重複產出相同內容context 爆了，遺忘前面的規則回到②中斷
AI 說「我理解了」然後產出無關的東西幻覺回到②中斷
build 一直報錯，AI 修的都不是對的地方AI 沒有真正理解問題回到③重來

② 中斷手段（依強度排列）

強度手段說明
輕貼入：「你現在重複產出相同內容，請停止。我要重新描述問題。」讓 AI 意識到它卡住了
中/clear清掉對話，從頭重新給提示詞
強Ctrl+C → 開新 OpenCode session全新 context，貼 PROJECT_NOTES 最後一段

③ 重來策略（不是重來整個專案，是重來「這一段對話」）

上一個 session 做到 PROJECT_NOTES.md 第 47 項：Lightbox 手機版點背景關不掉。
之前的解法：用的是 <dialog> + close()，
但手機上點 backdrop 不會觸發 close。

請看 src/pages/gallery.astro 的 Lightbox 區塊，找到原因，
不要重寫整個檔案，只修問題點。