Communitygithub.com

aiswarya797/find-your-knowns

AI 編碼助手的技能,用於在實作前將隱藏的未知轉化為可操作的已知。

find-your-knowns 是什麼?

這個名為「Find Your Knowns」的 AI 代理人工作流程,旨在解決開發者在實作時因資訊不對稱而導致的風險。它借鑒了 Thariq Shihipar 的「找出你的未知」框架,引導代理人在執行任何重大、模糊或高風險任務前,先系統性地區分「已知的已知」、「已知的未知」、「未知的已知」和「未知的未知」。此技能支援 Claude Code 等編碼代理平台,透過觸發政策、快速分類和路由表,根據任務的模糊程度和影響範圍,選擇最合適的探查策略(如盲點掃描、設計探索、原型製作)。最終產出具體的工件(如風險表、決策記錄),並在需要時提出一個高影響力的問題,確保在錯誤的方向上浪費最少資源,同時保留足夠的靈活性以應對實作中出現的意外。

相容平台~Claude Code~Codex CLI~Cursor
npx skills add aiswarya797/find-your-knowns

在你喜歡的 AI 中提問

開啟一個已預先載入此 Agent Skill 的新對話。

說明文件

找出你的已知(Find Your Knowns)

使用這個路由工作流程,在做出有風險的實作選擇之前,縮小使用者的「地圖」與真實「領域」之間的差距。地圖是使用者提供的提示、工單、計劃或參考資料。領域是實際的儲存庫、產品行為、設計系統、資料、API、生產環境限制以及使用者的預設期望。

歸屬:這是一個原創的代理人工作流程,靈感來自 Thariq Shihipar 的文章《Field Guide to Fable: Finding Your Unknowns》及其配套的「Know your unknowns」範例。在產出可重複使用的工件時請標明此框架,但請勿複製來源文本。

觸發政策

在以下情況使用此工作流程:任務模糊、涉及美學、策略性、高風險、不熟悉、執行時間長、位於未經檢查的程式碼庫區域,或可能隱藏產品、設計、API、安全性、資料、遷移或營運限制。

強烈的觸發詞包括「更好」、「更乾淨」、「不錯」、「直覺」、「可商轉」、「你決定」以及「像 X 那樣」。在制定大型實作計劃之前、當實作現實與計劃不符時,或在實作後為了獲得審查者/利害關係人的認可、合併前的說明或變更理解工作流程時,也應使用此工作流程。

請勿將此工作流程用於一般的程式碼審查、錯誤審查、安全性審查或 PR 缺陷查找請求。這些任務需要專門的審查方法,而不是未知探索路由。當變更很小、很明顯、直接指定、影響低或修復成本低於探索成本時,請保持此工作流程輕量化,或直接跳過它。

操作規則

  1. 避免對微小、顯而易見的工作進行過度儀式化。如果變更直接、風險低且明確指定,請說明未知影響不大並直接進行。
  2. 在推測之前,優先檢查領域。在將風險作為事實提出之前,先閱讀相關檔案、測試、文件、配置、架構、日誌或產品參考資料。
  3. 在進行不可逆的實作之前,優先使用低成本探針。在投入大型架構之前,使用模擬、grep 搜尋、小型測試、一次性腳本或參考映射。
  4. 當需要使用者輸入時,一次只問一個高影響力的問題。優先考慮那些會改變架構、資料模型、使用者體驗、安全態勢、遷移策略、公開 API 或發行風險的問題。
  5. 產出具體工件。有用的工件可以是風險表、語義映射、模擬、決策記錄、實作說明文件、認可文件或測驗。避免產生沒有後續行動的通用「考慮 X」列表。
  6. 除非受阻,否則繼續工作。如果使用者無法聯繫,且風險不涉及架構/API/安全性/資料關鍵事項,請選擇最保守的可逆預設值,記錄該假設,然後繼續。

快速分類

在選擇劇本之前先對任務進行分類:

  • 已知的已知(Known knowns):使用者明確提出的需求。
  • 已知的未知(Known unknowns):使用者已經明確提出或暗示的開放性問題。
  • 未知的已知(Unknown knowns):使用者在看到後會認同的品味、慣例、品質標準和領域期望。
  • 未知的未知(Unknown unknowns):雙方都尚未發現的隱藏限制、行為、風險或缺失的領域知識。

然後對不確定性進行分類:

  • 低不確定性,低影響:直接實作。可選擇性地記錄你使用的一個假設。
  • 中等不確定性:執行一個專注的劇本並繼續。
  • 高不確定性或高影響範圍:檢查儲存庫,執行盲點掃描,然後路由到訪談、參考搜尋、模擬或可調整計劃。
  • 計劃與現實在工作進行中發生矛盾:使用實作說明並重新規劃受影響的部分。
  • 工作已完成但缺乏理解或認可:使用認可文件或變更測驗。

路由表

僅載入目前任務所需的劇本:

  • 不熟悉的程式碼庫模組、隱藏限制或高風險區域:閱讀 references/blindspot-pass.md。
  • 使用者缺乏領域詞彙或專家級品質標準:閱讀 references/teach-me-my-unknowns.md。
  • 模糊的設計、使用者體驗品味、「讓它更好看」、「直覺」或「像 X 那樣」:閱讀 references/design-directions.md。
  • 在使用者體驗/產品形狀在後端、API 或狀態工作之前不明確:閱讀 references/mock-before-wire.md。
  • 解決方案空間開放且成本/風險權衡重要:閱讀 references/effort-axis-brainstorm.md。
  • 已知的模糊性需要使用者決定:閱讀 references/interview.md。
  • 現有的實作、產品或競爭對手行為應作為規格:閱讀 references/reference-hunt.md。
  • 即將制定一個大型計劃:閱讀 references/tweakable-plan.md。
  • 實作揭示意外或使計劃無效:閱讀 references/implementation-notes.md。
  • 已完成的工作需要審查者或利害關係人的認可:閱讀 references/buy-in-doc.md。
  • 使用者希望在合併前理解一個大型變更:閱讀 references/change-quiz.md。

預設工作流程

  1. 簡要重述地圖:使用者要求什麼以及已知資訊。
  2. 檢查領域:在對風險進行排序之前,從相關的儲存庫/產品表面收集證據。
  3. 指出影響最大的未知:除非使用者要求探索,否則保持簡短。
  4. 路由:從表中選擇一個或多個參考劇本。
  5. 行動:產出要求的工件,提出一個高影響力的問題,或根據記錄的假設進行實作。

當不需要專門的劇本時,使用這個簡潔的輸出格式:

未知檢查:
- 已知的已知:...
- 風險最高的未知:...
- 已執行的低成本探針:...
- 假設或問題:...
- 下一步行動:...

範例路由

  • 不熟悉的程式碼庫模組:「將 SSO 加入這個 auth 套件;我之前沒碰過它」 -> blindspot-pass.md,如果風險高則接著使用 tweakable-plan.md。
  • 模糊的設計請求:「讓審查儀表板更簡潔、更高級」 -> design-directions.md,可選用 mock-before-wire.md。
  • 已知的架構模糊性:「這個應該放在 API 閘道還是 Worker 裡?」 -> interview.md,接著使用 tweakable-plan.md。
  • 基於參考的實作:「將這個 Rust crate 的重試行為移植到我們的 TypeScript 客戶端」 -> reference-hunt.md。
  • 實作中出現偏離:「這個 schema 不支援計劃中的遷移」 -> implementation-notes.md,僅在新路徑改變資料/API 合約時才發問。
  • 合併前測驗:「確保我在合併前理解這個分支」 -> change-quiz.md。

相關技能