技術文件撰寫：PRD／架構／Runbook

用途

根據口頭討論、需求描述或現有系統，生成結構清晰的技術文件，含背景說明、需求定義、系統依賴與完成定義，讓工程師與利害關係人對齊。

何時用

• 適合：新功能或新系統要把口頭討論轉成可以協作的正式技術文件；要寫 PRD、架構說明或操作 Runbook；多人協作需要統一的文件基準。
• 不要用：客戶面文案或行銷文不要套這個格式（受眾不同）；純內部備忘筆記不需要走完整文件結構；尚未有基本需求共識時先對齊需求，不要急著寫文件。

Prompt

你是一位資深技術文件工程師，熟悉 PRD、系統架構文件與操作 Runbook 的標準格式。

文件類型：{{PRD / 架構設計文件 / Runbook，選其一}}
系統或功能描述：{{簡述系統或功能是做什麼的，2-5句}}
背景與動機：{{為什麼要做這個，解決什麼問題}}

---

請根據文件類型輸出對應格式：

若是 PRD：
- 背景（Problem Statement）
- 目標與成功指標
- 使用者故事（User Stories）
- 功能需求（功能點條列）
- 非功能需求（效能/安全/規模）
- 系統依賴
- 完成定義（Definition of Done）
- 不在範圍內（Out of Scope）

若是架構設計文件：
- 系統概覽（一段文字 + 架構圖描述）
- 元件說明（每個元件職責 + 邊界）
- 資料流（從輸入到輸出）
- 外部依賴與整合點
- 技術選型說明（為什麼選這個）
- 已知限制與取捨

若是 Runbook：
- 適用場景
- 前置條件
- 步驟（編號，每步附指令或截圖提示）
- 常見錯誤與解法
- 復原步驟

格式規範：
- 檔名建議：kebab-case 英文（例：gws-onboarding-runbook.md）
- 文件內容：繁體中文
- 日期欄位：ISO 8601（YYYY-MM-DD）
- 標題層級：H1 文件名 / H2 大段 / H3 子項

範例 / 變體

• 填好變數：文件類型「Runbook」、系統描述「使用 GAM 工具在 Google Workspace 批次管理共用雲端硬碟權限」、背景「IT 管理員每次手動操作容易出錯」→ 產出含前置條件、9 步指令與常見錯誤表的完整 Runbook。
• 變體（PRD 輕量版）：加上「只輸出背景、功能需求與完成定義三段，其他略過」，適合早期快速對齊需求的場景。
• 變體（中英對照）：在最後加「關鍵技術術語同時附英文原文（括號）」，適合跨語言技術團隊。

🎯 範例輸出（實測）

在 Claude.ai 跑這句、把 {{變數}} 填成「文件類型：Runbook、系統描述：使用 GAM 工具在 Google Workspace 批次管理共用雲端硬碟權限、背景：IT 管理員每次手動操作容易出錯且沒有記錄」的結果：

點開看 AI 實際輸出

適用場景

本 Runbook 適用於需要批次建立、修改或移除 Google Workspace 共用雲端硬碟（Shared Drive）權限的管理員作業，包含部門資料夾初始化、人員異動後的存取權更新、以及離職人員的撤銷流程。

前置條件

• GAM CLI 已安裝並通過 Google Workspace 管理員授權（gam info domain 可正常回傳）
• 執行者具有 Google Workspace 超級管理員或委派管理員權限
• 目標雲端硬碟的 ID 已確認（可透過 Google Drive URL 取得）

步驟

步驟 1｜確認目標共用雲端硬碟

gam show teamdrives

找到目標硬碟 ID（格式：0ABC...），記下備用。

步驟 2｜列出現有成員

gam show teamdriveacls drivefileid <DRIVE_ID>

步驟 3｜批次新增成員（以 CSV 匯入） 準備 members.csv（欄位：email, role），然後執行：

gam csv members.csv gam add teamdrivemember drivefileid <DRIVE_ID> user ~email role ~role

role 可用值：organizer、fileOrganizer、writer、reader

步驟 4｜驗收

gam show teamdriveacls drivefileid <DRIVE_ID>

確認新增成員出現在清單中。

常見錯誤與解法

錯誤訊息	原因	解法
User not found	Email 拼錯或尚未加入網域	確認 email 格式，用 gam info user <email> 驗證
Permission denied	GAM 授權不足	以超管帳號重新授權 gam oauth create

復原步驟

若誤操作需撤銷剛才新增的成員：

gam delete teamdrivemember drivefileid <DRIVE_ID> user <email>

💡 實測心得：這個提示詞生成的 Runbook 步驟指令格式很穩，但「常見錯誤」段 AI 容易寫通用情境而非你系統的真實狀況；先跑一次、手動把錯誤表換成你實際遇到過的情境，文件價值會高很多。

延伸

你有沒有遇過這種情況？系統做完了但沒有文件，下一個接手的人全靠問前人？技術文件不只是紀錄，是降低知識集中在少數人身上的風險。重點來了，寫文件最難的是「知道要寫什麼」，而不是「怎麼寫好看」，這個提示詞幫你把結構先定好。