plumb

Plumb 是一款專注於開發人員的工具，旨在維護「規格驅動開發」（Spec-Driven Development）三角的完整性。它解決了 AI 輔助開發中常見的問題：設計文檔、自動化測試與實際實作之間的嚴重脫節。透過 git pre-commit hook，Plumb 持續監控您的暫存更改與對話歷史，以識別架構與行為決策，確保在沒有經過驗證的文件與測試覆蓋之前，不會提交任何變更。

• 自動攔截 git commit，分析暫存差異與大型語言模型 (LLM) 的決策歷史。

• 透過 CLI 呈現待決策事項供互動式審查，確保自動化變更有專業人員進行監督。

• 自動同步已核准的決策至 Markdown 規格文件，並產生相對應的測試案例。

• 追蹤三種不同的覆蓋率指標：程式碼覆蓋率 (pytest)、規格對測試的映射以及規格對程式碼的一致性。

• 提供強大的決策拒絕工作流程，可觸發自動化的程式碼修改，將變更撤銷至原始程式碼庫狀態。

• 在版本控制的 .plumb 目錄下管理專案狀態，支援基於分支的決策日誌與持久性歷史記錄。

• 最適合使用 AI 程式設計助手且需要維持「單一事實來源」的開發人員，確保開發成果與文件相符。

• 使用方式包括在儲存庫中初始化工具，這會設定掛鉤、設定 .plumbignore 模式並對映現有的規格。

• 需要持續使用 plumb 指令：plumb status 用於健康檢查，plumb diff 用於提交前預覽，以及 plumb sync 用於完成文件更新。

• 最佳運作方式是進行明確的人工驗證；請勿對架構變更使用自動核准。

• 與基於 Python 的工作流程相容，使用 pytest 與 git 等標準工具進行深度整合。

• 對於維護技術文件往往次於交付程式碼的團隊至關重要，能有效自動化在快速功能開發中通常會產生的「同步債務」。