【2026 最新】Whiteboard 教學：Claude Code／Codex 架構圖如何對照程式碼？5 步驗收

你讓 Claude Code 或 Codex 解釋一段改動，Agent 很快畫出漂亮的架構圖。可是圖上的「驗證服務」在程式裡究竟是哪個檔案？箭頭代表現在的呼叫，還是 Agent 想像的設計？這是 Whiteboard 教學 最該先解決的問題：看懂圖之後，如何回到證據。

本文寫給第一次用程式 Agent 審查變更、但不想先學完整架構術語的讀者。我們從安裝入口、三個視窗的用途講起，再用一個小改動示範五步驗收。你會得到可直接複製的提問與檢查清單，也會知道目前哪些限制必須先安排人工補位。

先說結論：圖是索引，Git 才是底稿

一句話記住：Whiteboard 圖＝導航；Git diff＋檔案位置＋提交＝驗收底稿。圖能幫你找到要問的問題，不能自己證明程式真的照圖運作。Whiteboard 的 官方 README 說明圖形可跳到程式碼、語意 diff 可濃縮相關變更，Decision Log 可串起 Agent 決策。這些是產品設計與功能說明；本文沒有把它們當成獨立的正確率測試。

• 你要看圖：快速掌握元件與資料流。
• 你要看 diff：知道這次實際改了哪些行。
• 你要看決策紀錄：找出 Agent 為何選這個做法，再確認理由是否有程式證據。

Whiteboard 是什麼？把架構討論和程式審查放在同一張桌上

把一般架構圖想成地圖，程式碼則是街道。Whiteboard 是一個開放原始碼桌面應用程式：人在畫布上看設計，Claude Code、Codex 等 coding agent 也能在同一工作區繪圖與解釋。官方 Quickstart 是下載並開啟桌面程式、從歡迎畫面連接 Agent、請 Agent 比較目前分支與 main。逐步入口在官方 Quickstart。

這裡的語意 diff，白話是「先看有意義的變化」，不是把每個字元修改都攤開。官方 README 稱它是 Rust 實作、理解 AST（程式語法樹）的檢視器，預設會摘要大型新增函式，並折疊部分測試與文件變更。摘要可以省時間，審查時仍應展開原始 diff 對照。官方功能說明。

Decision Log 像會議紀錄：它連結需求、Agent trace 與自主選擇。但「有記錄」不等於「選得對」。如果你想先理解跨工作階段為何要保存決策，可以讀 Claude Code Decision Ledger 教學；它處理的是保存決策狀態，本文處理的是在 Whiteboard 裡把決策反查到變更。

Whiteboard 教學：用 5 步對照架構圖與程式碼

① 固定審查範圍：先鎖分支與提交

痛點：你一邊看圖，另一邊 Agent 又推進了程式碼，兩份內容可能指向不同時間。先在一個可丟棄的測試 repo 或工作分支操作，記下 git rev-parse HEAD 的結果，再用 git status --short 確認工作目錄狀態。基準分支也記下 git rev-parse main。白話說，就是替這次審查拍一張有版本號的快照。

如果你尚未有測試 repo，可在自己的練習資料夾建立一個含 main 與 feature 的小專案，讓功能分支只改一條資料流，例如「表單送出後多一層驗證」。先讓 Git 有兩個可比較的提交，再進入 Whiteboard。不要拿尚未釐清的正式專案當第一次練習。

② 連接 Agent，要求它明示圖的證據

依 官方三步 Quickstart 開啟 Whiteboard，從歡迎畫面連接已可使用的 Claude Code 或 Codex。在 Agent 對話貼上：「請比較目前分支與 main，在 Whiteboard 畫出這次修改的資料流。每個方框與箭頭都標出對應檔案、函式或呼叫位置；看不到證據的連線請標記為推測。另列出你使用的基準提交與目前 HEAD。」

這段提示詞是驗收要求，不是 Whiteboard 保證會自動完成的固定按鈕。Agent 產圖後，先核對它回報的兩個提交是否等於步驟 ① 的 Git 輸出；對不上就先停止審查，重新指定版本。

③ 從每條重要箭頭跳回程式碼

先挑最容易造成錯誤的一條路徑，例如「表單 → 驗證 → 儲存」。對圖上的每個方框寫下「哪個檔案、哪個函式」；對每個箭頭問「哪一行呼叫了下一站」。官方說圖上的視覺化項目可跳到底層程式碼；若連結落到一個同名但不在本次 diff 的函式，就把它標為待查，自己在編輯器搜尋呼叫點。官方圖碼連結說明。

一個可重複的做法：另開終端機執行 git diff --name-only main...HEAD，先列出功能分支相對共同祖先修改的檔案。接著用 git diff main...HEAD -- path/to/file 查一個檔案的逐行變化。這兩個 Git 指令檢查的是版本差異（Git 官方 diff 說明）；若畫面還顯示未提交變更，再另外核對 git diff 與 git status --short。

④ 把語意摘要攤開，核對被折疊的變更

假設 Whiteboard 把一個新增函式濃縮成「新增驗證流程」，這只是審查入口。你要追問三件事：呼叫端有沒有改、錯誤路徑有沒有改、測試與文件是否被折疊。再用原始 diff 對每一點取證。尤其當圖上寫「所有請求都驗證」時，要找繞過這條流程的入口，而不是只確認一條成功路徑。

這也是圖碼一致性最容易失手的地方：圖可能描述想要的架構，diff 只描述這次改過的內容，執行時行為又可能受舊程式與設定影響。三者範圍不同，請在筆記裡分開寫「已改」「未改但被引用」「仍待執行驗證」。若想練習大 repo 的安全審查，可接著讀 大型程式庫安全重構教學。

⑤ 對 Decision Log 做反向盤問

看到「因為效能，所以改用快取」時，別只讀理由。追問：「哪段 trace 提出這個決定？對應哪個 commit？哪個測試或測量支持效能理由？若撤掉快取，程式會如何變？」如果找不到，結論就寫理由已記錄，效果未驗證。Decision Log 的價值在於讓問題有地方追，不是替理由背書。

最後把審查結果寫成三欄筆記：圖上主張 → 程式證據 → 判定。判定只用「吻合／不吻合／證據不足」。例如「驗證先於儲存 → handler 第 42 行呼叫 validate，通過後第 48 行才 save → 吻合」。行號是你自己審查時填入的實際位置，切勿照抄範例數字。

完整走一次：一條「驗證後儲存」箭頭怎麼查？

以下是假設的練習案例，不是 Whiteboard 產出的測試結果。你的功能分支把表單送出流程改為：submitForm 先呼叫 validateInput，通過後才呼叫 saveRecord。Agent 在 Whiteboard 畫出三個方框、兩條箭頭，並在 Decision Log 寫「把驗證放在儲存之前，避免錯誤資料寫入」。

1. 先抄下 Whiteboard 指向的 submitForm 檔案位置。若只連到檔案、沒有函式，先記「定位不足」。
2. 用 git diff main...HEAD -- path/to/file 找 validateInput 的新增呼叫，再查失敗分支是否會跳過 saveRecord。只看到函式名稱並不足以證明執行順序。
3. 打開測試：找「驗證失敗時沒有寫入」的案例；如果只有成功案例，把圖上的「所有錯誤都擋下」改成「目前只確認成功路徑」。
4. 最後對 Decision Log：這項選擇有需求或 bug 單作為起點嗎？若沒有，把理由列為待補，不因為 Agent 寫得有說服力就當成證據。

這份紀錄可以落成一句話：「圖上順序與目前 diff 的呼叫順序吻合；失敗路徑測試尚待補。」這比只說「圖看起來正確」更容易交接。若你要在多個 Agent 同時改動前就抓衝突，可看 Foremerge 的意圖檢查；它解的是前一個階段的問題。

三個官方已知限制，如何安排補位？

截至 2026 年 9 月 25 日，Whiteboard README 的 Known limitations 明列三件事。一，Whiteboard 內目前不能直接編輯檔案：發現不一致時回到編輯器或 Agent 修改，再重新審查。二，單次 review 跨多個 repo 工作與瀏覽的支援有限：先逐 repo 記錄各自 commit，再手動核對跨 repo 的介面契約。三，分享 review 後的新更新不會自動出現在收件者那份分享裡：每次重要修改後重新分享，並在訊息裡附上版本。

分享前還有一個容易忽略的邊界：官方隱私說明 寫明，分享會上傳固定版本的文件文字、圖片、軟體圖、所釘選的提交、GitHub 帳號及倉庫 clone URL；收到連結的人自行向 GitHub 取得提交。先檢查畫布文字與圖片是否含內部設計或秘密，再決定是否分享。

Whiteboard 教學：一張可複用的圖碼驗收清單

1. 版本：圖、diff、Decision Log 都指向同一個基準與 HEAD 嗎？
2. 節點：每個重要方框能定位到實際檔案與函式嗎？
3. 連線：每條重要箭頭都有呼叫、資料傳遞或事件證據嗎？
4. 負例：有沒有其他入口繞過圖上的路徑？
5. 隱藏內容：被折疊的測試、文件、大函式，原始 diff 是否查過？
6. 決策：理由能連到需求、trace、commit 與可驗證結果嗎？
7. 分享：分享版本、敏感內容與更新後重新分享是否確認？

如果某一項是「證據不足」，先不要把圖貼進 PR 當作定稿。可以把缺的檔案或問題交給 Agent 補畫，也可以自己在 PR 註明未知。這套清單也適合搭配 Archify 架構變動教學 比較兩種圖像介面，再用 Foremerge 教學 檢查平行 Agent 開工前的意圖衝突。

常見問題：先給你直接答案

Whiteboard 畫的架構圖可以當程式碼真相嗎？

不能直接當。用它定位問題，再用同一提交的原始 diff、呼叫點與測試驗收。

語意 diff 比 Git diff 更可靠嗎？

用途不同。語意檢視幫你縮小閱讀範圍；逐行 Git diff 保留完整變更細節。

Decision Log 有理由，是否就代表決策正確？

不代表。理由還要對照需求、提交與可觀察結果。

Claude Code 與 Codex 都能接嗎？

官方 Quickstart 同時列出兩者；實際可用性仍取決於你的安裝與連線環境。

可以在 Whiteboard 裡直接改檔嗎？

依 2026 年 9 月 25 日官方 Known limitations，目前不能在 Whiteboard 內編輯檔案。

一張 review 可以同時看多個 repo 嗎？

官方目前把單次 review 跨多 repo 的工作與瀏覽列為支援有限。先逐 repo 固定版本。

分享後，對方會看到我後來的修改嗎？

依官方目前說明，不會自動看到；需要重新分享更新後的 review。

我不是工程師，也需要看每一行嗎？

先抓關鍵路徑：入口、判斷、寫入與錯誤處理。把無法定位的方框與箭頭交給工程師複核。

給新手的 3 個重點

• 先固定版本：沒有基準與 HEAD，圖與程式無法公平比較。
• 先查最重要的箭頭：找呼叫點與原始 diff，比讀完整張圖有效。
• 把未知寫出來：Decision Log 是線索，未驗證的效果仍是待查。