Workflow

Workflow

說明

Workflow 定義人類與 AI Agent 在 AI Playbook 專案中的協作方式。它不是抽象流程圖，而是每次開工、寫文件、改架構、Review、部署前可以執行的操作順序。

第一版 Workflow 以「讀取來源、限制範圍、執行修改、驗證結果、更新狀態」為核心。

Why

AI Playbook 是給多種 Agent 共用的規範入口。如果每個 Agent 都用自己的流程工作，會造成內容格式不一致、技術決策散落、驗證缺漏與部署風險。

Workflow 的目的，是讓每次工作都能被追溯、驗證與接續。

Universal Workflow

所有任務預設遵守以下流程：

1. Read
2. Scope
3. Plan
4. Execute
5. Verify
6. Record
7. Commit

1. Read

先讀必要上下文。

最低要求：

• PRD.md
• src/content/docs/docs/project-dashboard.md
• 任務相關章節

2. Scope

確認本次修改範圍。

要回答：

• 這次要改哪些檔案？
• 哪些檔案不應該碰？
• 是否需要新增程式碼？
• 是否需要部署或外部服務？

3. Plan

規劃可驗證的最小步驟。

原則：

• 不為未來假設做過度抽象。
• 不一次完成所有可能內容。
• 每一步要能驗證。

4. Execute

依範圍執行。

原則：

• 文件內容留在 Markdown / MDX。
• 不把 Playbook 內容硬寫在程式碼裡。
• 保持七區塊格式。
• 遵守現有目錄邊界。

5. Verify

根據任務類型驗證。

文件或內容：

• 檢查七區塊格式。
• 檢查路由可存取。
• 檢查搜尋索引是否更新。

程式碼或設定：

• npm run check
• npm run build
• HTTP smoke test

部署：

• Cloudflare Pages build logs
• live URL smoke test
• sitemap / llms.txt 檢查

6. Record

更新專案狀態。

通常需要更新：

• src/content/docs/docs/project-dashboard.md
• src/content/docs/docs/changelog.md
• 必要時更新 public/llms.txt

7. Commit

提交前確認：

• git status 只包含本次相關檔案。
• 驗證已完成或明確記錄未完成原因。
• commit message 使用繁體中文，描述實際完成事項。

Task Workflows

Content Workflow

適用於補文件、改寫章節、建立 Prompt 或 Workflow。

步驟：

1. 讀取對應章節。
2. 確認七區塊格式。
3. 補內容，不改技術架構。
4. 跑 npm run check && npm run build。
5. 做必要 HTTP smoke test。
6. 更新駕駛艙與 Changelog。

Coding Workflow

適用於 Astro / Starlight 設定、路由、build、搜尋、部署相關修改。

步驟：

1. 讀 PRD.md、駕駛艙與相關文件。
2. 檢查目前 Git 狀態。
3. 修改最小必要檔案。
4. 跑 npm run check && npm run build。
5. 用 dev 或 preview 做 smoke test。
6. 更新相關文件與 commit。

Review Workflow

適用於 code review、文件 review、架構 review。

步驟：

1. 先列 findings。
2. 每個 finding 指向具體檔案或規則。
3. 區分 blocking、risk、improvement。
4. 檢查是否缺少驗證。
5. 最後才給摘要。

Deploy Workflow

適用於 Cloudflare Pages 部署。

步驟：

1. 確認本機 npm run build 通過。
2. 確認遠端 Git 已推送。
3. Cloudflare Pages 使用 npm run build 與 dist。
4. 部署後做 live smoke test。
5. 確定正式 URL 後補 site。
6. 驗證 sitemap、/llms.txt 與主要頁面。

Do

• 工作前先讀 Source of truth。
• 明確記錄輸入、輸出與驗證方式。
• 每次修改都回報檔案、目的與下一步。
• 先限制範圍，再執行修改。
• 把驗證結果寫回專案狀態。
• 每次 commit 前檢查工作樹。

Don’t

• 不要跳過需求文件直接實作。
• 不要在未決定技術棧前新增大量框架程式碼。
• 不要忽略文件格式與目錄邊界。
• 不要把未驗證的狀態寫成已完成。
• 不要在同一個 commit 混入無關變更。
• 不要為了流程完整而執行不必要的外部操作。

Checklist

• 定義 Universal Workflow
• 定義 Content Workflow
• 定義 Coding Workflow
• 定義 Review Workflow
• 定義 Deploy Workflow
• 建立 content-workflow.md
• 建立 coding-workflow.md
• 建立 review-workflow.md
• 建立 deploy-workflow.md

Prompt Example

請依 AI Playbook 的 Workflow，執行下列任務。

任務：
{{task}}

要求：
- 先讀 PRD 與專案駕駛艙
- 先限制本次修改範圍
- 只修改任務相關檔案
- 完成後執行對應驗證
- 更新專案狀態與 Changelog
- 最後回報修改摘要、驗證結果與下一步