TechSpecs搜尋

Theme / v1.2.3

Matt Pocock's Engineering Skills

可組合的 AI 工程工作流技能庫

主題首頁GitHub ↗
實戰範例

實戰範例 007：用 /research 調查 OAuth Refresh Token Rotation

決定串接第三方 OAuth provider 前先用背景代理查證官方規則，把發現寫成附引用的 Markdown。

情境背景

你要把第三方 OAuth provider（這裡假設是架空 provider FooAuth）接到現有會員系統，最關鍵的決策是「refresh token 要不要做 rotation」。這個決策影響資料庫 schema、token 表設計、以及撤銷流程。你不想憑印象或部落格文章決定，因為走錯代價很高。

/research 是設計來處理這類問題的工具。它會啟動背景代理，針對一手來源（官方文件、原始碼、規格、第一方 API reference）進行調查，最後在 repo 存放研究筆記的位置留下單一附引用的 Markdown 檔。

第 1 步：界定可回答的問題

目標：把模糊的需求收斂成一個可調查的問題

/research 對問題陳述很挑。它不是搜尋引擎，不接受「告訴我 OAuth 怎麼用」。它要的是一個可回答的具體問題。

AI 對話：

  • You:

    /research FooAuth 的 refresh token rotation 在 2026 年的官方規則是什麼？

  • AI:

    啟動背景調查。來源鎖定：

    • FooAuth 官方文件（docs.fooauth.com）
    • FooAuth 原始碼（github.com/fooauth/server）
    • FooAuth 的 OAuth scope 規格與 release notes
    • IETF RFC 6749 與 RFC 8414 關於 token rotation 的章節

    完成後寫入 docs/research/fooauth-refresh-token-rotation.md，每個結論附引用。

你不必停下來等代理。/research 是背景執行，你可以繼續做別的，例如先準備 schema migration 的骨架。

第 2 步：理解一手來源的把關

目標：知道哪些來源會被接受、哪些會被駁回

/research 對來源嚴格把關，理由是一手來源是權威的，二手來源是可能過時或誤讀的快取。

會被接受的來源

  • 官方文件（例如 docs.fooauth.com、docs.python.org）
  • 原始碼（GitHub repo 上的實際 code）
  • 規格 / RFC（IETF RFC、語言規格、官方 spec）
  • 第一方 API reference（廠商提供的 API docs）

會被駁回的來源

  • 部落格文章（即便是知名作者）
  • Stack Overflow 答案
  • 論壇討論
  • 二手轉述、摘要文章

如果你曾看過某篇 Medium 文章講 FooAuth 的 rotation，背景代理不會引用它。它會去原始碼或官方文件找同樣的事實，並引用源頭。

第 3 步：拿到附引用的 Markdown

目標：理解研究筆記的結構

背景代理完成後，會把結論寫成單一檔案。每個主張都附來源連結，方便日後追溯。

檔案結構範例：

# FooAuth Refresh Token Rotation（2026 官方規則）

## 結論
FooAuth 自 v3.2 起強制 refresh token rotation（來源 1、來源 2）。

## 細節
- 每次交換 access token 時，舊 refresh token 立即失效（來源 1）。
- 重複使用已失效的 refresh token 會撤銷整個 token 家族（來源 1、來源 3）。
- 視窗期為 0 秒，沒有寬限（來源 2）。

## 來源
1. FooAuth 官方文件 - Token Lifecycle: https://docs.fooauth.com/token-lifecycle
2. FooAuth v3.2 release notes: https://github.com/fooauth/server/releases/v3.2.0
3. RFC 8414 Section 2.2: https://tools.ietf.org/html/rfc8414

注意每個數字主張都對應到一個可點開的官方連結。

第 4 步：用研究結果驅動後續決策

目標：把研究變成 ADR 與 schema 設計

拿到研究檔之後，不要讓它躺在 docs/research/ 沒人讀。下一步通常是：

  1. 用 /domain-modeling 把發現寫進 CONTEXT.md：定義「token 家族」「rotation 視窗」這些新詞，讓之後對話與程式碼都用共享語言。
  2. 用 /to-spec 把決策寫成規格：例如「token 表需記錄 family id 並在 rotation 時失效舊 token」。
  3. 寫 ADR 記錄不可逆決策：「選擇支援 rotation，因為 FooAuth 在 v3.2 後強制」。

第 5 步：在 wayfinder 流程裡大量使用 /research

目標：理解 /research 不只是獨立技能

/wayfinder 在規劃大型工作時會建立「research ticket」這類共享阻塞項。charting session 會為每張 research ticket 啟動一個 /research 子代理，平行燒掉所有調查工作，把發現捕獲在 research/<name> 的拋棄式分支上。

意思是如果你在跑 /wayfinder，/research 會被模型自動觸發，不必你記得切換。

何時不應該用 /research

能用 --help 或一份 config 回答的問題

直接查，不必啟動代理。/research 是給需要查證多份一手來源的問題，不是給一行指令就能答的。

主觀意見或取捨討論

這是一手事實調查，不是觀點收集。要逼問取捨用 /grilling。

你自己已經很熟的領域

直接回答，不必研究。/research 是給有真實不確定性的問題。

工具使用摘要

Skill 用途 在本例的作用
research 一手來源調查 背景代理查 FooAuth rotation 規則並附引用
domain-modeling 詞彙建立 把 token 家族、rotation 視窗寫進 CONTEXT.md
to-spec 規格化 把發現變成 schema 設計需求
wayfinder 大型規劃 在多服務拆分時大量並行觸發 /research

結果

  • 拿到一份附 3 個官方引用的 Markdown 研究檔，每個主張可追溯
  • 確認 FooAuth v3.2 後強制 rotation，不需要再憑印象決策
  • 學會把研究結果接到 /domain-modeling、/to-spec 與 ADR 形成完整決策鏈

關鍵學習點

  • /research 只接受一手來源，部落格、Stack Overflow、論壇答案一律駁回。
  • 它是背景執行，啟動後你可以繼續做別的，不必停下來等。
  • 問題陳述要具體可回答，例如「官方規則是什麼」，不是「告訴我 OAuth 怎麼用」。
  • 研究檔不要躺在資料夾沒人讀，下一步要接到 /domain-modeling 與 /to-spec 形成決策。