代碼審查發現不了的Bug：工作樹狀態錯亂與自我修復

幾周前，我還在反思自己缺少紀律性，于是動手做了一個工具來彌補這個短板。這個工具叫 ArDD，本質上是一套為 Claude Code 內置的技能腳本，它能推著項目走完需求文檔、計劃和任務清單，而不是讓一個智能體從一句提示直接跳到寫代碼的步驟。那篇文章結尾，我留下了一個疑問：說到底，這會不會只不過是一個包裝漂亮的 CLAUDE.md？

直到目前，ArDD 只有我一個人在用。所以接下來這些記錄，更像是刮掉了私密細節的內部決策復盤。但這件事教會我的東西，完全超出了這個工具本身。更重要的是，如果我沒有實際運行它，而是反復讀代碼，就永遠看不到這些教訓——它們只出現在真實的執行現場里，藏在代碼審查永遠掃不到的那一層。

ArDD 的核心循環是“計劃→任務→實現”，其中“實現”環節可以把工作分發給一個子代理，這個子代理跑在自己專屬的 Git 工作樹里。這樣就不必盯著單線程的代理一步步推進。原始設計在交接上小心翼翼：在委派子代理之前，先把一部分粗略的狀態——比如計劃和任務清單——提交到主分支。我的邏輯是，分出去的工作樹需要一個穩定、已經落地的基點來創建分支。

這個邏輯錯了。發現錯誤靠的不是對設計的信任，而是一次實打實的冒煙測試。我先提交了一份用完就丟的計劃和任務文件，接著把工作委派到一個全新的工作樹里，然后直接檢查這個工作樹內部到底裝著什么。

結果對不上。工作樹是從 origin/main 分支出來的，里面根本沒有我剛剛在本地做的兩次提交。這套自動化骨架在創建工作樹時，用的是遠程跟蹤分支，而不是本地的 HEAD，而這個行為在技能的說明文字里完全沒法操控。更麻煩的是，根據問題跟蹤器里的記錄，不同版本的骨架在這點上的行為還會翻轉——所以“默認拉取最新”和“默認保持同步”兩種假設，都是錯的。唯一可靠的姿勢是：先驗證，永遠不要假定。

同一次運行還暴露了一個我至今解釋不了的問題。創建工作樹的動作，居然把我主工作區的 Git 配置項 core.bare 改成了 true。這會讓普通 Git 命令在那個工作區里直接壞掉，直到我注意到并手動改回來為止。git worktree add 理論上根本沒有權利去動調用它的那個工作區的配置，而我也始終沒找到觸發機制。既然找不到根源，我就不假裝去修復它。現在的協調器會在每次委派運行之后檢查這個配置項有沒有再次被篡改，一旦就發警報。用一道絆馬索去應對一個無法解釋的骨架級 Bug，這稱不上修復，我也不打算把它叫作修復——但一個會大聲報警的“已知未知”，總好過一個沉默的“未知未知”。

針對工作樹分支與本地不一致的問題，我寫了一個小腳本 worktree-align.sh，作為每一個被委派的子代理必須執行的第一項任務：把本地的默認分支快進合并到新工作樹的分支里，如果做不到干凈的快進，就直接拒絕繼續運行。這里沒有嘗試去調和五花八門的分歧，只做一次確定性的檢查——要么通過，要么停止整個進程。

比這兩項修復活得都久的，是由它們逼出來的一次流程重設計。按照作者原本的設計，工作流會先將協調狀態提交到主分支，然后再……（此處原文記錄不完整）。最后定下的方案，把協調狀態挪到了工作樹內部，不再依賴主分支的提交來傳遞。這次重設的根由很清楚：當“運行前提交狀態”的設計被事實證明不可靠之后，唯一能信任的，就是從運行現場拿到的實時數據。

整個事件鏈條給出了一條樸實但常被忽略的經驗：很多行為偏差寫在骨架的版本差異里，寫在 runtime 的副作用里，唯獨不會寫在代碼的靜態文本里。你不可能靠盯著 CLI 參數說明或者腳本源碼，就猜出工作樹究竟會從哪個分支分叉，更猜不到它會偷偷修改一個看似無關的配置項。只有讓程序完整跑一遍，再去檢查它實際生產出來的每一個產物、每一個殘留狀態，才能把這類問題從沉默的暗處拽到明處。這也解釋了為什么這條教訓很適合從個人工具里長出來——因為如果沒有親自運維的執念，沒有對著實際輸出刨根問底的下意識，這些 Bug 可能永遠埋在自動化流程的底層，偶爾炸一次，然后被歸為“環境問題”一筆帶過。