三個月前那次被 revert 的嘗試、團隊某人踩過的坑、某個檔案裡的隱藏慣例。
對策:讓 Claude 掃描 codebase / git 歷史,把它「教」回給你。
把一份實作計畫交給 AI coding agent 之前、之中、之後——你都可以用一個個「自包含 HTML 工件」,在最便宜的時機把落差挖出來。這是一趟導覽,帶你走過 11 個示範,並把每一個都翻譯成「你會怎麼指揮 Claude」。
改編自 Thariq Shihipar 的〈Know your unknowns〉。本站本身就是它主張的示範:用互動 HTML 取代一面文字牆。
全站的心智模型錨點——之後每個示範卡都會用象限色回指這裡。
三個月前那次被 revert 的嘗試、團隊某人踩過的坑、某個檔案裡的隱藏慣例。
對策:讓 Claude 掃描 codebase / git 歷史,把它「教」回給你。
需求裡寫清楚的部分、你熟悉的 API、已定案的規格。這是安全區,通常不需要工件去挖。
對策:直接寫進 prompt 當作約束條件即可。
那些會在 code review 或 production 才炸出來的地雷。這是返工與事故的主要來源。
對策:用「盲點掃描」主動照亮;一旦被照到,它就降級成已知未知。
「這個 schema 要不要支援多租戶?」你意識到了,但還沒答案。風險中等,容易被拖到實作中才踩到。
對策:用「訪談」「可調整計畫」把它們排序、逼自己現在就決定。
方法論的核心是一台「降級機」:把未知未知照成已知未知,把已知未知逼成已知已知。每往右上角移動一格,返工成本就掉一個量級。
而且時機決定價格。原文說得直接:「在寫下任何一行程式碼之前,是找到未知數最便宜的地方。」所以 11 個示範裡有 8 個都落在「實施前」。
這 11 個示範全都是「自包含的 HTML 檔案」,而不是段落式文件。原文的主張是:
「二十個 agent 產出的 .html 檔案,取代一整面 markdown 文字牆。每一個,都把『你會略讀的文件』換成『你真的會讀的東西』。」
差別在於——文件把資訊壓平成線性文字,逼你用腦力重建結構;HTML 工件則能把資訊攤在空間裡:並排比較、可點擊、有視覺層級。
這也是為什麼你正在讀的這個網站不是一篇文章——它是一份工件。你等一下會親手點過的每個示範,都是 Claude 可以為你的專案產出的東西。
〈Know your unknowns〉是「HTML Effectiveness」系列的一章。整個系列展示 AI coding agent 如何用互動 HTML 產出九類工作成果:探索規劃、code review、設計、原型、圖表、簡報、研究解說、報告、自訂編輯介面。本站聚焦其中最能改變工作品質的一環——在動手前後主動發現未知數。
這是 11 個示範的地圖,先看見全貌,再進入細節。
最便宜的地方。趁還沒寫程式,把落差挖乾淨。
邊做邊記。計畫偏離的每一處,當下就留痕。
送審前先驗收理解。別人真的看懂了嗎?
注意這個分佈——8:1:2。方法論在告訴你:發現未知數的槓桿,絕大部分在你動手之前。
情境是你要在陌生的 Acme auth 模組裡加一個新的 SSO provider。Claude 掃過 services/auth/(47 個檔案、214 筆近期 commit、3 個進行中 migration、2 次被 revert 的嘗試),產出七張「盲點卡」,每張標明它是地雷(Landmine)、慣例(Convention)還是失落的概念(Missing concept),並附「為什麼會咬你(Why it bites)」與修法。最後把七張卡壓縮成一段「改良版 prompt」——原文形容那是「七句你今天早上還寫不出來的話,每一句都是別人用半天換來的」。
把「加一個 SSO provider」換成你自己要碰的陌生模組,先別叫 Claude 動手,而是叫它做偵察。這一步專治「未知未知」——你連要問什麼都不知道的部分。
在動手之前,先對 <目標模組/資料夾> 做一次盲點掃描。
讀這個區域的程式碼、近期 git log、以及任何被 revert 的 commit。
列出 5–8 張「盲點卡」,每張標明類型(地雷/慣例/失落的概念)、
它為什麼會在實作或 review 時咬我、以及對應的規避作法。
最後把這些約束壓縮成一段我可以直接用來實作的 prompt。
先不要寫任何實作程式碼。
一個互動色彩分級(color grading)解釋器。它用「詞彙階梯」+「即時 before/after 畫面+滑桿+預設」把模糊需求教成專業術語,讓「把影片弄好看一點」變成一段精準、專業的 prompt。重點不是產品,而是把你的「已知未知」補成「已知已知」。
任何你「知道自己想要、但講不出精確規格」的領域(動畫緩動、資料庫索引策略、無障礙標準),先請 Claude 當家教,用互動方式建立你的詞彙表,再回頭下精準指令。
我想要 <模糊目標,例如「讓這個列表滑動更順」>,但我缺乏精確描述它的詞彙。
先當我的家教:用一個「詞彙階梯」從最粗到最細,教我這個領域的關鍵參數,
每個參數配一個具體的 before/after 例子。
教完之後,幫我把我的目標改寫成一段用上正確術語的精準 prompt。
同一個 review 佇列,用四種南轅北轍的排版同時呈現:ops console(維運主控台)、editorial(雜誌編排)、kanban(看板)、terminal(終端機)。每個版本配「steal/skip」小晶片,你一點,它就幫你把回覆寫好——把「你喜歡哪個方向」這個已知未知,變成可並排比較的選擇題。
面對開放式的 UI/架構決策,不要問「你覺得該怎麼做」,而是叫 Claude 一次生出多個真正不同的方向並排,你用「這個偷、那個跳」的方式給回饋,它據此收斂。這是善用 Claude 的關鍵心法:把它的產能用在「拓寬選項」而不是「猜你的偏好」。
針對 <某個介面/模組>,給我 4 個明顯不同的設計方向(不是微調,是不同哲學)。
四個並排呈現,各自標出它最適合的使用情境與取捨。
每個方向附幾個「採用/捨棄」的要點,讓我可以逐點挑選。
根據我挑的組合,收斂成一個最終方向。
一個可點擊、但完全沒接後端的標註工具列原型:三種可切換的擺放位置、幾組 A/B 問題、還有一個會自動填好的回覆範本——全部在動任何真實程式碼之前。你用點擊做決定,工件幫你把決定記下來。
與其口頭爭論「按鈕放哪、流程怎麼走」,不如叫 Claude 產一個純前端、不接邏輯的可點原型,把互動決策當成可操作的問題攤開。決策定了,這個 mock 本身就是最精準的實作規格。
幫我做一個「純畫面、不接任何邏輯」的可點擊 HTML 原型,主題是 <某個互動/流程>。
把還沒定案的地方做成可切換選項(例如位置 A/B/C、兩種流程),讓我點著做決定。
每做一個選擇,就在頁面上記錄下來,最後彙整成一份實作決策清單。
強調:這一步不要寫任何真正的商業邏輯或後端。
針對「降低流失(churn)」,列出十個扎根於實際 codebase 的介入方案,並沿一條軸線鋪開——從「今天下午就能上」到「一季的長押注」。每個方案配一個「有共鳴」核取方塊,你勾一勾,它就把你的回覆組好。
面對一個模糊的目標(提升留存、降延遲、減少 bug),叫 Claude 基於你真實的程式碼與資料發散十個方案,並用「投入成本 vs 影響」排開。這治的是「未知已知」——解法其實藏在你的 codebase 裡,只是你沒把它們攤出來看。
目標是 <某個模糊成果,例如「降低新用戶流失」>。
讀我的 codebase,給我 10 個「紮根於現有程式碼」的介入方案,
每個都指出它會動到哪些具體檔案/模組。
沿「今天就能出貨 → 一季長押注」這條軸排序它們。
每個方案讓我可以勾選「有共鳴」,最後把我勾的整理成下一步行動。
針對一個含糊的功能(標註匯出 annotation-export),Claude 一次只問一個問題,而且依「架構爆炸半徑(blast radius)」排序——答案越會改變架構的問題越先問。原文的觸發指令是:「一次問我一個問題,聚焦在標註匯出功能裡任何還模糊的地方;優先問那些我的答案會改變架構的問題。」整場訪談(例:7 個開放問題)最後收斂成一張決策表與一段可直接貼上的實作 prompt。
這是把「已知未知」一次清空的最強工具。不要讓 Claude 自己猜你的意圖然後埋一堆假設;反過來,叫它訪談你,而且用爆炸半徑排序問題,先把會動搖地基的決策問掉。產出的決策表,就是你和它之間的合約。
我要做 <某功能>,但還有很多沒定案。請訪談我:一次只問一個問題,
優先問那些「我的答案會改變整體架構」的問題(依爆炸半徑排序)。
我回答後你再決定下一題。問到重大不確定性都清掉為止。
最後輸出兩樣東西:(1) 一張決策表(決策/我的選擇/理由/影響範圍),
(2) 一段可以直接拿去實作的 prompt。
一張「語意驗證圖」,證明 Claude 讀懂了某個參考實作(Rust 範例),內含對上的程式碼片段、gotcha 註記、邊界案例表——全部在把它移植成 TypeScript 之前。它把「Claude 是不是誤解了我給的參考」這個隱形風險攤在你眼前。
當你叫 Claude「照這個做」「移植這段」「模仿這個 pattern」時,最大的未知數是它跟你理解的是不是同一件事。先要它畫出理解地圖(哪段對應哪段、有哪些坑、邊界怎麼處理),你確認無誤,它才動手。這一步把「未知已知」變成雙方共識。
我要你參考 <參考實作/檔案/連結> 來做 <目標>。
先別移植。請先產出一張「理解驗證表」:
參考裡的每個關鍵段落,對應到你打算怎麼在我的專案實作它,
並列出你發現的 gotcha 與需要特別處理的邊界案例。
我確認這張表正確之後,你才開始寫。
一份實作計畫,依「最可能被調整」排序,而非依執行順序。它把有疑慮的 schema 選擇標記出來、附上可切換的替代方案、為型別介面加註解,並把「純機械性的工作」摺疊收到最底部。你的注意力被導向真正需要你拍板的少數決策。
一般的計畫把所有步驟平鋪,你得自己找哪裡有風險。改成叫 Claude 把最可能被推翻的決策浮到最上面、把無腦步驟沉到底部,你就能只花力氣在會變的地方。這是「注意力經濟」的善用——讓 Claude 幫你分配你稀缺的判斷力。
給我一份 <某功能> 的實作計畫,但排序方式是「最可能被我改動的決策放最前面」,
不是按執行順序。每個關鍵決策(尤其 schema、型別、資料流)標出來,
並附 1–2 個可切換的替代方案與取捨。
把純機械性、沒有決策的步驟摺疊收到最底部。
Claude 在一段 3 小時的建構過程中維護的運行日誌——每一次偏離計畫都被記下來,連同它當下做的「保守選擇」,最後濃縮成三個要點,供「第二次嘗試」時折進計畫。它把實作中才浮現、原本會蒸發掉的未知數固定成文字。
長時間讓 Claude 跑一個任務時,最貴的損失是「它中途遇到分歧、默默選了一條路,你事後完全不知道」。明確要求它維護一份決策日誌:偏離計畫處、當下為何這樣選、有哪些先擱置的疑點。這份日誌就是你事後 review 與下一輪迭代的黃金線索。
在你實作 <任務> 的過程中,同步維護一份「實施筆記」:
每當你偏離原計畫、或遇到計畫沒交代的岔路,就記一筆——
你怎麼選的、為什麼選這個(尤其若你選了保守的做法)、以及你先擱置了什麼疑點。
做完後,把這份筆記濃縮成「下一次要折進計畫的 3 個要點」。
一份「可以出貨了」的說服文件,先用一段匯出流程的動畫演示開場(先給看的、再給讀的),接著逐一預先回應審核者的每個反對意見,並附證據,還明確點名「誰需要簽核什麼」。它把「審核者腦中的疑慮」這種你看不見的未知,提前挖出來擋掉。
要別人接受你的改動時,最大的未知是「他們會在哪裡卡住、會反對什麼」。叫 Claude 站在審核者立場,先列出所有可能的異議,再一條條用證據回應,並用動畫/視覺讓人「先看懂再讀細節」。你等於預演了整場 review。
幫我把 <這個改動/功能> 做成一份「說服文件」,對象是 review 我的人。
開場先用一段視覺化演示讓人立刻看懂它做了什麼(先展示、後文字)。
然後站在審核者立場,列出他們最可能提出的每一個反對意見,
每一條都用證據預先回應。最後明確標出「誰需要簽核哪一部分」。
針對一份 14 個檔案的 diff(把 clip 匯出從瀏覽器端 MediaRecorder 改成伺服器端 FFmpeg 背景渲染),最後是一場六題測驗,你必須全對(6/6)才能過。題目不是考記憶,而是「你在事故或 review 時真的得做對的判斷」。答錯會直接把你指回你剛才略讀過的那一段。全對後解鎖一句話:「你可以把這個改動解釋給那個半夜被 call 起來的人聽了。」
code review 最大的謊言是「LGTM」——按核准的人其實沒真的看懂。叫 Claude 為你的 diff 生一份「合併前測驗」,每題對應一個非顯而易見的行為,答錯就連回對應段落。這把「審核者的未知已知」逼成真正的理解,也逼你自己在 merge 前補完認知缺口。
針對這份 diff <指向你的 PR/變更>,幫我做一份「合併前測驗」:
先用一張心智模型圖說明這個改動的核心,
再列出 2–3 個「不明顯但很重要」的行為。
然後出 5–6 題,每題都是「事故或 review 時必須判斷對」的決策題(不是背誦題)。
答錯的題目要指回對應的說明段落。全對才算通過。
先偵察,後動手。
面對陌生的程式碼或領域,第一個指令永遠是「先掃描、先教我」,而不是「開始寫」。(對應 01、02、05、07)
讓它問你,而不是猜你。
把「一次問一題、按爆炸半徑排序」設成預設互動,讓已知未知在動工前清空。(對應 06)
要選項,不要它替你決定。
叫它一次生多個真正不同的方向並排,把 Claude 的產能用在拓寬選項空間。(對應 03、04)
按「會不會變」排序,而非按執行順序。
讓它把最可能被推翻的決策浮到最上面,替你分配稀缺的判斷力。(對應 08)
讓它邊做邊留痕。
長跑任務要求它維護決策日誌,記下每個當場自己做的選擇。(對應 09)
用產出驗收理解,而不是用「看起來對」。
送審與合併前,讓它用說服文件與測驗把「別人/自己是否真懂」變成可驗證的事。(對應 10、11)
這六條的共同點:不要把 Claude 當成「更快的打字員」,而要當成「幫你把未知數照出來的探照燈」。它最大的價值,往往在它寫下第一行程式碼之前。
這一整套「實施前掃盲點、訪談澄清 → 實施中記日誌 → 實施後出說服文件與測驗」的流程,可以打包成一個 Claude Code / skills.sh 的可複用 skill。你只要對著自己的專案說一句「跑 known-your-unknowns」,Claude 就會依三階段自動走完,並在關鍵節點產出 HTML 工件給你看。
掃盲點、訪談澄清
→ 產出:盲點卡、決策表
記日誌
→ 產出:實施筆記
出說服文件與測驗
→ 產出:說服文件、合併前測驗
skill 套件正在準備發佈,敬請期待。