最佳實踐文件技能

自動化 TAM 知識庫中最佳實踐文件的完整工作流程，將原本需要 2-4 小時的手動工作縮減至 10-15 分鐘。

使用方式

/best-practice <主題名稱>
/bp <主題名稱>

範例：

/bp webhook-timeout-patterns
/best-practice runner-disk-management
/bp ansible-integration-patterns

此技能的功能

執行完整的最佳實踐文件工作流程：

驗證與檢查現有項目 - 確保無重複，處理更新
研究知識庫 - 尋找類似的調查、最佳實踐、客戶範例
搜尋文件 - 尋找官方指引與版本資訊
搜尋產品程式碼 - 驗證技術細節與預設值（相關時）
搜尋 GitHub - 尋找社群議題、錯誤與功能請求
搜尋 Jira - 定位內部開發工單與修正版本
社群搜尋 - 必要時擷取外部來源（可選）
綜合發現 - 呈現研究摘要，等待使用者確認
產生文件 - 依照 TEMPLATE.md 結構建立最佳實踐
更新 INDEX.md - 新增至類別、字母順序表格與快速參考
回報完成 - 提供詳細摘要與後續步驟

指令

當此技能被呼叫時，請遵循以下步驟：

步驟 1：解析引數與驗證

從引數中提取主題名稱：

必要：主題名稱（例如 "webhook-timeout-patterns"）
若非 kebab-case，則轉換為 kebab-case
如果主題超過 80 個字元，警告：「主題似乎過於廣泛。請考慮拆分？」

若未提供主題：

錯誤：「使用方式：/best-practice <主題名稱>」
顯示範例

步驟 2：檢查現有的最佳實踐

搜尋名稱相似的最佳實踐：

Glob pattern="*${關鍵字}*" path="best-practices/"

決策邏輯：

完全符合： 詢問使用者：「最佳實踐已存在於 <檔案>。(1) 更新現有文件，(2) 以不同重點建立新文件，(3) 取消？」
部分符合： 列出它們，詢問：「找到相似項目：<檔案>。(1) 更新其中一個，(2) 建立新文件，(3) 取消？」
無符合項目： 繼續建立流程

如果使用者選擇更新，請記下檔名，以便後續使用 Edit 而非 Write。

步驟 3：搜尋知識庫

從主題名稱中提取搜尋關鍵字（移除連字號，拆分為詞彙）。

搜尋最佳實踐：

Grep pattern="<關鍵字>" path="best-practices/" output_mode="content" -C 3 head_limit=50

搜尋調查：

Grep pattern="<關鍵字>" path="investigations/" output_mode="content" -C 3 head_limit=50

搜尋客戶設定檔（若相關）：

Grep pattern="<關鍵字>" path="customers/" output_mode="files_with_matches"

如果找到客戶設定檔，請 Read 以收集背景資訊。

收集並記錄：

相關最佳實踐（用於「相關最佳實踐」章節）
調查範例（用於「實際案例」章節）
來自相似文件的常見標籤（用於後設資料）
適用的客戶背景資訊

步驟 4：搜尋官方文件

Grep pattern="<關鍵字>" path="repositories/docs/" output_mode="content" -C 2 head_limit=30

收集並記錄：

官方指引與建議
特定版本的資訊
設定參考與選項
已知限制或注意事項

步驟 5：搜尋產品程式碼（條件性）

何時搜尋：

主題涉及特定功能的行為
需要預設設定值
了解效能特性
驗證技術限制

Grep pattern="<元件|類別>" path="repositories/rundeckpro/" output_mode="content" head_limit=30

收集並記錄：

預設設定值
實作細節與行為
技術限制或範圍
特定版本的邏輯

步驟 6：搜尋 GitHub 議題（透過 Runlayer 連接器）

透過 Runlayer 連接器查詢 GitHub — 此環境中沒有 gh CLI。呼叫 search_tools 以定位 GitHub 議題搜尋工具，然後使用 execute_tool 搜尋 rundeck/rundeck 和 rundeckpro/rundeckpro 中的 <關鍵字>，包含開放和已關閉的議題。請勿直接執行 shell 指令 gh。

收集並記錄：

已知問題或錯誤
功能請求與社群回饋
解決方案與社群提供的作法
供引用的議題編號

如果 GitHub 連接器不可用，請記錄此情況並繼續。

步驟 7：搜尋 Jira RUN 專案（透過 Runlayer 連接器）

透過 Runlayer 連接器查詢 Jira。呼叫 search_tools 以定位 Jira 議題搜尋工具，然後使用 execute_tool，並使用傳回的確切 tool_name 和引數。請勿直接呼叫 mcp__atlassian__* 工具。使用等同於以下參數：

jql: "project=RUN AND (summary ~ \"<關鍵字>\" OR description ~ \"<關鍵字>\") ORDER BY updated DESC"
maxResults: 15

收集並記錄：

內部開發工單
修正版本與發行資訊
開發狀態與背景資訊
供引用的 Jira 金鑰（RUN-XXXX）

錯誤處理： 如果 Jira 連接器不可用，請記錄「Jira 搜尋不可用」並繼續。

步驟 8：社群搜尋（可選/視需要）

觸發時機：

在步驟 3-7 中找到的相關來源少於 3 個
新穎或新興的模式，文件尚不完整
使用者表示需要更廣泛的研究

WebFetch with parameters:
  url: "https://groups.google.com/g/rundeck-discuss/search?q=<關鍵字>"
  prompt: "尋找關於 <主題> 的討論。提取內容：回報的問題、提議的解決方案、建議的模式、常見問題"

收集並記錄：

社群解決方案與模式
常見陷阱與問題
實作變體
重要： 標記未經證實的主張，並與官方文件交叉驗證

步驟 9：綜合發現與取得使用者確認

分析所有研究發現：

識別模式，跨越多個來源
決定建議： 主要方法與其理由
識別替代方案： 其他方法以及為何主要方法較優
提取實作方式： 逐步說明，附程式碼範例
記錄優點與權衡
選擇後設資料：
- 產品領域： 從以下類別中決定：
  - 🎯 工作設計與編排
  - 🖥️ 節點管理與目標設定
  - 🔐 安全性與存取控制
  - 📊 效能與擴充
  - 🔗 整合與 Webhook
  - 🏗️ 架構與部署
  - 📝 文件與維護
- 適用版本： 從 Jira/文件取得（具體如「Rundeck 5.6.0+」或保守如「所有版本」）
- 標籤： 使用現有分類法（掃描步驟 3 中找到的標籤），最多 3-8 個標籤

向使用者呈現研究摘要：

# 研究摘要：<主題名稱>

## 找到的來源
- 知識庫：X 項調查，Y 項最佳實踐
- 文件：N 頁
- GitHub：P 項議題
- Jira：Q 張工單
- 社群：[若已搜尋]

## 建議方法
[1-2 段摘要，說明根據研究的主要建議]

## 識別出的主要模式
- [來自研究的模式 1]
- [來自研究的模式 2]
- [來自研究的模式 3]

## 建議的後設資料
- **產品領域：** [已決定的類別]
- **適用版本：** [來自研究的版本]
- **標籤：** #標籤1 #標籤2 #標籤3 [取自相似的最佳實踐]

## 品質檢查
- ✓ [X] 個來源已找到（建議至少 4 個）
- ✓ [Y] 個程式碼/設定範例可用
- ✓ [Z] 個實際案例已找到

準備好產生文件了嗎？

等待使用者確認。 使用者可以：

確認並繼續
要求修改後設資料或方法
要求額外研究
取消工作流程

在獲得使用者確認之前，請勿繼續進行文件產生。

步驟 10：產生最佳實踐文件

一旦使用者確認，請產生文件：

讀取範本以供參考：

Read file_path="best-practices/TEMPLATE.md"

使用研究內容填入所有章節：

標頭（第 1-6 行）：

# [標題大小寫的主題名稱]

**最後更新：** 2026-04-20
**產品領域：** [來自步驟 9]
**適用版本：** [來自步驟 9]
**標籤：** #標籤1 #標籤2 #標籤3 [來自步驟 9]

---

使用案例 / 情境：

描述何時需要此內容（來自調查與文件）
解決了什麼問題？
此內容與哪些情境相關？

建議：

清晰、可操作的指引（「該做什麼」）
綜合分析後的主要方法
若有多個選項，可使用表格

實作方式：

逐步操作說明
如果適用，可包含多種模式（模式 1、模式 2 等）
來自文件與程式碼研究的程式碼範例

# 包含實際的 YAML/設定範例
# 使用研究中找到的程式碼片段

為何有效：

來自程式碼與文件研究的技術說明
底層原則或機制
此方法為何有效

優點：

來自研究發現的編號列表
具體優勢（效能、安全性、可維護性等）
盡可能量化

權衡 / 注意事項：

研究中識別出的限制
效能考量
可能不適用的情況
⚠️ 若發現衝突資訊，請標記

考慮過的替代方案：

研究中找到的其他方法
為何建議的方法較佳
何時替代方案可能更好

實際案例：

調查的連結：[客戶/案例](../investigations/YYYY-MM-DD-description.md)
如果沒有：「尚未記錄任何調查。此最佳實踐基於 [官方文件/程式碼分析/社群模式]。」

相關最佳實踐：

來自知識庫搜尋的相關文件連結
格式：[標題](./filename.md) - 簡短說明

官方文件：

文件儲存庫檔案的連結
依編號標記的 GitHub 議題
依金鑰標記的 Jira 工單
官方網站的連結

寫入前的品質檢查：

✓ 所有 4 個後設資料欄位都已填入
✓ 3-8 個標籤，來自現有分類法
✓ 所有範本章節都存在
✓ 至少 1 個程式碼/設定範例
✓ 至少引用 2 個來源
✓ 正確的 Markdown 格式

寫入文件：

如果是建立新文件：

Write file_path="best-practices/<kebab-主題名稱>.md" content="<產生的內容>"

如果是更新現有文件（來自步驟 2）：

Edit file_path="best-practices/<現有檔名>.md"

在保留結構的同時更新相關章節。

步驟 11：更新 INDEX.md

讀取目前的 INDEX：

Read file_path="best-practices/INDEX.md"

決定主要類別（請精確使用表情符號）：
- 🎯 工作設計與編排
- 🖥️ 節點管理與目標設定
- 🔐 安全性與存取控制
- 📊 效能與擴充
- 🔗 整合與 Webhook
- 🏗️ 架構與部署
- 📝 文件與維護
使用 Edit 工具更新三個區段：

a) 類別區段： 找到適當的類別（例如 "### 🎯 工作設計與編排"）並新增項目：

- [標題](./filename.md) - 一行說明 #標籤1 #標籤2 #標籤3

在類別中按字母順序插入。

b) 所有最佳實踐（字母順序）表格： 找到正確的字母順序位置並插入：

| [標題](./filename.md) | 類別 [& 次要類別，如果適用] | 2026-04-20 | [相關案例或「N/A」] |

c) 依使用案例的快速參考區段： 新增 2-4 個「我需要...」項目，反映常見的使用案例：

- **...特定問題/任務** → [標題](./filename.md)

按字母順序排序。

更新「最後更新」日期： 更改頂部的日期：

**最後更新：** 2026-04-20

使用 Edit 工具執行更新： 使用 Edit 進行每項變更（如果它們位置相近，可以合併）：

Edit file_path="best-practices/INDEX.md" old_string="<現有文字>" new_string="<更新後的文字>"

步驟 12：回報完成

提供詳細的完成摘要：

✅ 最佳實踐已成功建立！

## 文件詳細資訊
**標題：** [完整標題]
**檔案：** best-practices/<檔名>.md
**類別：** [主要類別]
**標籤：** #標籤1 #標籤2 #標籤3

## 研究摘要
- 知識庫：X 項調查，Y 項最佳實踐
- 文件：N 頁
- GitHub：P 項議題
- Jira：Q 張工單
- 社群：[若已搜尋]
- **來源總數：** [計數]

## 已完成的文件章節
✓ 使用案例 / 情境
✓ 建議，包含 [計數] 個模式
✓ 實作方式，包含 [計數] 個程式碼範例
✓ 為何有效
✓ 列出了 [計數] 個優點
✓ 記錄了 [計數] 個權衡
✓ 考慮了 [計數] 個替代方案
✓ 實際案例：[連結或「待補充文件」]
✓ 連結了 [計數] 個相關最佳實踐
✓ [計數] 份官方文件參考

## INDEX.md 已更新
✓ 已新增至 [類別名稱]
✓ 已新增至字母順序表格（第 [N] 行）
✓ 已新增 [計數] 個快速參考項目
✓ 已更新「最後更新」日期

## 後續步驟
1. 在 best-practices/<檔名>.md 檢閱文件
2. 如果適用，在沙箱中測試實作
3. 與團隊分享：`/share-kb "<標題>" best-practices/<檔名>.md`
4. 如果適用，從相關的客戶設定檔建立連結

如果這是更新而非建立：

✅ 最佳實踐已成功更新！

## 已更新的文件
**標題：** [完整標題]
**檔案：** best-practices/<檔名>.md
[其餘摘要根據更新情境調整]

品質指引

研究品質

搜尋至少 4 個來源類別（知識庫、文件、程式碼、外部追蹤器）
引用特定的檔案路徑，供程式碼/文件參考
依編號連結到 GitHub 議題（#1234）
依金鑰連結到 Jira 工單（RUN-1234）
根據官方來源驗證社群主張
標記未經證實或衝突的資訊

文件品質

清晰度： 每個章節都應立即可操作或提供資訊
完整性： 所有範本章節都已填寫（無 TODOs）
基於證據： 所有建議都應有來源支援
實用性： 包含實際的程式碼/設定範例，而非僅有文字
誠實： 記錄取捨與注意事項

…

[為翻譯而截斷]

brmdias/best-practice

best-practice 是什麼？

在你喜歡的 AI 中提問

說明文件

最佳實踐文件技能

使用方式

此技能的功能

指令

步驟 1：解析引數與驗證

步驟 2：檢查現有的最佳實踐

步驟 3：搜尋知識庫

步驟 4：搜尋官方文件

步驟 5：搜尋產品程式碼（條件性）

步驟 6：搜尋 GitHub 議題（透過 Runlayer 連接器）

步驟 7：搜尋 Jira RUN 專案（透過 Runlayer 連接器）

步驟 8：社群搜尋（可選/視需要）

步驟 9：綜合發現與取得使用者確認

步驟 10：產生最佳實踐文件

步驟 11：更新 INDEX.md

步驟 12：回報完成

品質指引

研究品質

文件品質

Individual skills in this repo

brmdias/investigate

相關技能

affaan-m/uspto-database

affaan-m/scholar-evaluation

affaan-m/literature-review

affaan-m/everything-claude-code

forrestchang/andrej-karpathy-skills

langgenius/backend-code-review