正式環境發生問題時，如果團隊規模較小，負責相關程式碼的開發人員也許可以很快從記憶中找到根因；如果問題能在測試環境重現，也能直接進行偵錯。但當測試環境無法有效重現問題，或系統規模、複雜度較高，根因與問題症狀之間的關係又不明顯時，事故調查往往會先收集資訊並建立相關上下文。
在 AI 開發工具盛行的現在，越來越多程式碼由工具產生，逐行人工審查的成本也隨之提高。團隊可以透過規格驅動開發、單元測試等手段確保品質，也可以把偵錯工作交給 AI 工具；但 AI 工具可能很有把握地提出錯誤的根因候選。因此實務上可以由人與 AI 協作，先建立上下文資訊，再依照標準作業流程進行故障排除。
這個 digital-thread 專案探討如何在軟體交付過程中自動收集資料並預先建立上下文：持續記錄並串連需求、程式碼、測試、發布與事故。事故發生時，AI Agent 或工程師可以據此取得上下文並形成初步根因推測；事故處理完成後留下的紀錄，也能加速未來類似事故的故障排查。
預先建立與故障排除時重建上下文的挑戰
針對複雜故障，單一原始碼檔案所能提供的上下文通常有限。過往類似問題的工單可能只記錄結果，缺少故障排查細節；PR 看得到實作內容，但可能沒有鏈結到原始需求文件。測試全部通過，仍可能有未涵蓋的極端案例，導致測試雖然全綠，上版後仍發生事故。
偵錯前通常會視情況收集資訊來建立相關上下文，例如：
- 產品或業務當時想解決什麼問題？
- 這個需求對應哪個待辦工作項目？
- 哪個決策設定了系統邊界，或解決了需求之間的衝突？
- 這次變更涉及哪些 PR、提交與檔案？
- 哪些測試驗證了這次變更？建置結果是否正常？
- 哪個發布版本把它帶到正式環境？又是哪個事故暴露了問題？
如果這些答案只存在聊天紀錄、工單留言或某個人的記憶裡，事故發生時可能就要找人、翻紀錄、補上下文。數位線索的做法，是在平時就把這些資訊整理好，讓下一位接手的人也能從同一份脈絡開始。
數位線索要解決什麼
數位線索會先把偵錯需要的事實整理好，讓 AI Agent 或工程師從同一份上下文開始調查，形成初步的根因推測，再根據實際行為確認根因。
系統會在交付過程中建立一條可回溯的交付鏈：
產品意圖
→ 需求與需求版本
→ 待辦工作項目
→ 設計決策
→ PR 與提交
→ 異動檔案
→ 測試與建置結果
→ 發布版本
→ 事故與修復工作這條交付鏈不一定只有一條路徑。一個工作項目可能對應多項需求，一次變更可能影響多個服務，一個事故也可能需要多項修復工作。重要的是，每個關聯都要能說明來源、時間與目前狀態。
這個專案如何收集上下文
實作分成四個步驟：
- 先從來源收集資料。連接器會掃描本機 Plane 待辦清單或 Git 程式碼儲存庫，寫入來源事件與掃描資訊。系統先記錄來源實際回報的內容；推測出的關聯則另外標示並等待審查。
- 把識別資訊固定下來。待辦工單、檔案、發布版本與事故都要有穩定的邏輯識別資訊；內容與狀態則保存為不同版本，後續變更不會覆蓋先前的上下文。
- 把關聯怎麼來的記錄下來。明確的需求識別碼或 PR 參照，必須和根據分支名稱或文字相似度推測出的關聯區分開來。前者可以直接接受；後者必須經過人工審查。舊版本的關聯會保留並標記為過時。
- 建立可查詢的圖形。Neo4j 用來建立查詢圖形。來源事件會持續保存，讓圖形可以隨時重建。
不同工具之間如何建立對應關係
幾個系統出現相似文字，還不足以認定它們描述的是同一件事。不同來源之間要先定義清楚的對應規則，也要保留判斷時使用的證據。
在本機 Plane 情境中，預先建立的工作項目帶有穩定的情境識別碼、需求識別碼與上層項目資訊。情境識別碼作為邏輯識別；Plane UUID 與流水號則保存為來源證據。未來程式碼儲存庫、PR、CI 與事故連接器也可以採用同一套方式。
如果工單沒有標籤，掃描器會先把它保留為尚未確認的候選對應。系統仍可比對分支名稱、PR 描述、提交參照、異動檔案路徑、時間關係與內容相似度，提出候選對應供人工審查。重新掃描可以補充候選所需的上下文，推測出的關聯仍會維持候選狀態。
事故發生時如何使用數位線索
事故發生後，AI Agent 或工程師都可以從事故與發布版本的數位線索開始，沿著相關版本與關聯逐步往回追查：
- 確認事故發生時正式環境實際執行的發布版本，以及對應的程式碼版本。
- 從發布版本找到相關的 PR、提交、異動檔案、測試與建置結果。
- 再從這些變更往回找到當初提出這些變更的需求、待辦工作項目與設計決策。
- 確認追查路徑中的關聯是否仍然有效；已過時或尚未審查的關聯只能作為候選線索，不能直接視為已確認的事故證據。
- 根據這些資訊提出初步根因推測，由 AI Agent 協助整理與比較，再由工程師對照實際行為加以確認。
儀表板中的圖形探索器（Graph Explorer）會從選定的實體開始，顯示一到三層的鄰近關係，讓工程師查看節點或關係背後的來源、版本、狀態、建立者、信心程度與來源事件，避免一次把整個專案畫成難以閱讀的圖。紅色線用來標示選定的事故證據路徑；因果判斷與責任歸屬仍需另外確認。
目前這個專案已做到什麼
本機參考實作包括：
- 以自架的 Plane Community 作為本機待辦來源。
- 以可重複的測試資料模擬程式碼儲存庫、PR、測試、建置、發布與事故資料。
- 建立查詢圖形前，驗證來源事件、版本、關係與掃描狀態。
- Neo4j 可根據持久保存的事件輸入重新建立查詢圖形。
- 儀表板呈現發布檢查、待審查項目、版本細節與指定範圍內的圖形探索。
實作先維持小型且可檢查，用來驗證資料模型、收集規則與事故調查流程，再逐步增加其他來源連接器。
系統邊界
Plane、Git、CI 與事故管理系統，仍是各自領域紀錄的權威來源；數位線索負責彙整這些來源之間的關聯與上下文。
數位線索會標示每個關聯的來源、狀態與新舊程度。AI Agent 提出的根因候選仍需對照證據；若關聯只是推測、證據彼此衝突，或現有紀錄不足以解釋正式環境的行為，仍需人工審查。
如何啟動本機範例
使用下列指令啟動本機環境：
pnpm install
pnpm plane:setup
pnpm graph:up
pnpm graph:init
pnpm graph:rebuild
pnpm plane:up完成 Plane 初始設定後，建立本機 API 金鑰並寫入 Git 忽略的 .env，再掃描待辦清單、重播事件記錄並啟動儀表板：
pnpm plane:reseed
pnpm plane:scan
pnpm replay -- --events data/plane-thread-events.jsonl
pnpm dashboard開啟 http://127.0.0.1:3000，即可在本機檢查、查詢與重建已收集的上下文。