AI Agent 修改規則

說明

本文件定義 AI Agent 修改 AI Playbook 時必須遵守的規則。適用對象包含 Coding Agent、Design Agent、Content Agent、Review Agent 與任何會讀取本網站後產生修改建議或實際變更的自動化代理。

這些規則的目標不是限制 Agent 發揮，而是確保每次修改都能維持 PRD、目錄邊界、文件格式、AI 可讀性與人類可讀性。

Why

AI Playbook 是人類與 AI Agent 共用的 source of truth。如果 Agent 沒有固定讀取順序與修改規則，很容易出現以下問題：

只讀單頁就修改全站架構。
把臨時對話當成長期規範。
將文件內容硬寫進程式碼。
為了視覺效果破壞 Markdown / MDX 可維護性。
忘記更新 Changelog、Project Dashboard 或 llms-full.txt。

Required Reading

Agent 開始修改前，應依序讀取：

PRD.md

確認產品定位、第一階段目標、文件優先原則與七區塊格式。

專案駕駛艙

確認目前狀態、最近決策、風險、待完成事項與部署方式。

相關章節

依任務讀取 Brand、Design、Prompt、Workflow、Layouts、Components 或 Docs。

AI 讀取入口

需要公開上下文時讀 `/llms.txt`；需要完整公開內容快照時讀 `/llms-full.txt`。

最低讀取要求：

修改任何內容前：讀 PRD.md 與 src/content/docs/docs/project-dashboard.md。
修改網站架構前：讀 astro.config.mjs、src/content/docs/docs/deploy-cloudflare-pages.md 與相關 Starlight 內容。
修改品牌或設計前：讀 brand/ 與 design/ 相關頁。
修改 Prompt 前：讀 prompts/ 相關頁。

Modification Rules

Rule	說明
保持 Astro + Starlight	不因單次內容需求改技術架構。
文件優先	規則、內容與模板優先放 Markdown / MDX。
不硬寫內容	不把正式文件內容寫死在 Astro 元件或 CSS 中。
保留七區塊	正式文件維持標題、說明、Why、Do、Don’t、Checklist、Prompt Example。
人和 AI 都要能讀	可加入視覺輔助，但表格、規則、Checklist 與 Prompt 仍要保留。
共用樣式	視覺增強優先使用 `src/styles/custom.css` 的共用 class。
更新索引	新增重要內容時同步更新相關入口、Changelog、Project Dashboard 與 `llms-full.txt`。
不放私密資料	不把 API key、token、`.env`、未公開素材或個資寫進公開文件。

Verification Rules

每次修改後至少執行：

npm run verify

若修改 UI、CSS 或首頁，額外檢查：

首頁是否只有一個主要 H1。
主要頁面是否可在桌面寬度正常閱讀。
色票、卡片、callout 不遮擋文字。
/llms.txt、/llms-full.txt 仍可讀。

若修改部署設定，額外檢查：

npm run build
dist 是否產生
Cloudflare Pages 文件是否同步
部署後 smoke test 主要 URL

Do

先讀 PRD、專案駕駛艙與相關章節。
先確認目錄邊界，再新增或移動文件。
優先用 Markdown / MDX 寫規則。
用共用 CSS 增強閱讀，不為單頁建立零散樣式。
修改後更新 Changelog 與 Project Dashboard。
修改公開內容快照後更新 public/llms-full.txt。
完成後執行 npm run verify。

Don’t

不要改掉 Astro + Starlight 架構。
不要把 AI Playbook 改成行銷站、Blog 或作品集。
不要跳過 PRD 或專案駕駛艙。
不要刪除七區塊格式。
不要用視覺效果取代可搜尋文字。
不要把 ref/、本機私有圖片、產圖原檔或敏感資料直接放進公開站。
不要忘記 Changelog、Project Dashboard 與 llms-full.txt。

Checklist

已讀 PRD.md
已讀專案駕駛艙
已讀任務相關章節
確認是否需要更新 llms-full.txt
確認是否需要更新 Changelog
確認是否需要更新 Project Dashboard
已執行 npm run verify
已回報修改檔案與驗證結果

Prompt Example

你是 AI Playbook 的 Coding Agent。

請先閱讀：
- PRD.md
- src/content/docs/docs/project-dashboard.md
- src/content/docs/docs/agent-rules.md
- 任務相關章節

任務：
{{task}}

限制：
- 維持 Astro + Starlight
- 內容優先使用 Markdown / MDX
- 不把文件內容硬寫在程式碼裡
- 保留七區塊格式
- 若新增或改動公開規範，更新 Changelog、Project Dashboard 與 llms-full.txt

驗證：
- 執行 npm run verify
- 若是 UI 變更，檢查主要頁面可讀性