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 等标准工具进行深度集成。

• 对于维护技术文档往往次于交付代码的团队至关重要，能有效自动化在快速功能开发中通常会产生的“同步债务”。