Haft：AI辅助开发中的工程治理与决策可追溯性实践-程序员充电站

1. 项目概述：Haft——AI辅助软件交付的工程治理层

在AI编码助手（如Claude Code、Cursor）日益普及的今天，我们正面临一个全新的工程挑战：代码生成的速度前所未有，但生成代码背后的决策质量、长期可维护性以及决策依据的保鲜期，却成了一个巨大的黑箱。你可能会发现，一个月前让AI重构的某个模块，今天因为一个看似无关的依赖更新而突然崩溃，而你完全想不起当初为什么选择了那个特定的实现方案。Haft正是为了解决这个核心痛点而生的。

简单来说，Haft不是一个编码代理，也不是一个文档工具。它更像是一个“工程治理层”或“决策操作系统”，插在你的意图（“我想改进缓存层”）和AI代理的执行（生成具体代码）之间。它的核心使命是将“快速交付”转变为“正确交付”。它强制引入一套工程纪律：在解决问题前先框定问题，在公平的比较下评估选项，将决策记录为可证伪的“合约”，并在底层假设过时的那一刻向你发出警报。想象一下，你为每一个重要的技术决策都建立了一份带有“保质期”和“健康度评分”的活合同，Haft就是这份合同的起草人、保管人和审计员。

2. 核心设计理念与工作流拆解

2.1 “思考 → 运行 → 治理”循环

Haft的整个哲学建立在“思考-运行-治理”这个闭环之上。这听起来抽象，但落实到日常开发中，就是一套严谨的工作流。

思考阶段：这是最容易被忽略的部分。当你想让AI处理一个任务时，Haft不会让它立刻开始写代码。相反，它会引导你（或你的AI代理）先完成一系列结构化思考：

框定问题：我们到底要解决什么？是性能优化、bug诊断、功能设计还是技术选型？
定义评估维度：用什么标准来判断解决方案的好坏？是延迟、内存开销、代码可读性，还是团队熟悉度？Haft会要求为每个维度指定一个“角色”（例如，“性能守护者”、“维护性倡导者”），这迫使思考超越简单的技术参数，融入工程和业务视角。
探索多样方案：生成多个本质上不同的解决方案选项，而不仅仅是语法变体。Haft会检查方案的“多样性”，避免陷入局部最优的思维定式。
公平比较：在一个“公平竞技场”上比较所有选项。这意味着每个方案都在相同的约束条件下、针对相同的评估维度进行评估。Haft内置了防止“古德哈特定律”（当一项指标变成目标，它就不再是一个好指标）的观察机制，确保比较的诚实性。

运行阶段：一旦通过思考阶段做出了一个被记录的“决策合约”，你就可以放心地让AI代理去执行。Haft的haft run命令会读取这份合约中的所有上下文——包括决策依据、必须遵守的不变量、受影响的文件——然后将其打包成一个超级上下文的提示，喂给指定的AI代理（如Codex或Claude）。代理在编码时，这些“不变量”就像护栏一样，约束着它的输出，确保实现不偏离初衷。

治理阶段：代码写完了，事情并没有结束。Haft会为这次变更建立一个“基线”快照。更重要的是，决策合约中附带的“证据”（例如，性能基准测试结果）是有有效期的。Haft会持续计算每个决策的“有效信任分数”，这个分数会随着证据的老化而衰减。当分数低于阈值，或后续的代码变更违反了当初决策设定的“不变量”时，Haft的治理仪表盘就会亮起警报，提示你：“这个决策所依据的假设可能已经失效，需要重新审视了。” 这就完成了从决策、执行到持续验证的完整闭环。

2.2 两种交互界面：MCP插件与桌面应用

Haft提供了两种主要界面来接入这个工作流，它们共享同一个核心“内核”。

MCP插件模式：这是当前最稳定、推荐的生产使用方式。MCP（Model Context Protocol）是Anthropic推出的一种协议，允许外部工具将功能“注入”到兼容的AI编码工具中。Haft作为一个MCP服务器运行，为你的Claude Code、Cursor、Gemini CLI等工具新增了一系列以/h-开头的命令和背后的思考工具。你直接在熟悉的编辑器或AI聊天界面里，就能调用Haft的完整推理能力。例如，在Cursor里输入/h-reason “如何优化这个API的响应时间”，就能启动一次完整的结构化决策流程。

桌面应用：这是一个独立的可视化操作台，目前处于pre-alpha阶段。它提供了更宏观的视图：所有项目的决策仪表盘、治理健康状态、问题看板、决策的详细证据链分解图等。你可以在这里跨会话、跨项目地管理你的技术决策资产。桌面应用上的“Implement”按钮，其背后调用的就是haft run的相同管道。它更适合项目负责人或架构师进行全局的工程治理俯瞰。

实操心得：对于日常开发，强烈建议从MCP插件模式开始。它无缝集成到你的编码流中，学习成本最低。桌面应用更适合在定期（如每周）进行工程复盘或规划重大重构时使用，它能帮你一眼看清系统中哪些决策已经“年久失修”，构成了潜在的技术债。

3. 核心工具与实操命令详解

3.1 六大MCP工具：你的决策脚手架

Haft通过六个MCP工具将结构化思考过程具象化。理解它们，就理解了Haft的“语言”。

haft_note：微决策记录器。用于捕捉那些小的、临时的决定，比如“暂时禁用这个缓存是因为发现了竞态条件”。它可以附加验证条件和自动过期时间，避免这些临时方案被遗忘而变成永久隐患。
haft_problem：问题框定器。这是所有思考的起点。它强制你清晰地描述“什么东西坏了”或“什么目标没达到”，并定义评估解决方案的维度和角色。一个模糊的“让系统更快”会被它要求具体化为“将P95 API延迟从200ms降低到100ms以下”。
haft_solution：方案探索器。基于框定好的问题，生成多个候选解决方案。它的关键作用是进行“多样性检查”，确保选项在架构或思路上有本质区别，而不是同一个想法的不同写法。
haft_decision：决策合约生成器。这是核心产出。它将选定的方案、放弃的方案、决策理由、必须遵守的代码不变量、可测量的声明（如“内存使用增幅不超过10%”）、支撑证据以及一个“有效期至”日期，打包成一份结构化合约。这份合约是后续所有治理活动的基础。
haft_refresh：生命周期管理器。用于管理所有决策产物的生命周期。当证据过期或环境变化时，它可以触发对旧决策的重新评估流程。
haft_query：知识图谱查询器。你可以搜索历史上的所有决策，查看它们的当前状态（健康、警告、过期），或者查找某个特定文件受到哪些决策的约束。这是理解系统“为什么长成这样”的强大工具。

3.2 核心实操命令：从入门到精通

初始化与集成：安装Haft后，在你的项目根目录运行haft init（根据你的AI工具附加对应flag，如--cursor）。这个命令会在你的项目及AI工具配置中植入Haft所需的MCP配置和命令。完成后，在你的AI工具（如Cursor）中输入/，你应该就能看到一系列/h-开头的命令了。

一键式推理：/h-reason这是最强大的入口命令。你只需描述你的问题，例如/h-reason “用户登录模块的密码验证逻辑需要增强安全性，防止时序攻击”。Haft代理会自动接管后续所有步骤：框定问题、生成方案、公平比较、形成决策合约。它会根据问题的复杂度自动选择合适的“思考深度”。对于大多数日常任务，这个命令就够了。

手动分步驱动：如果你希望对思考过程有更精细的控制，可以使用分步命令链：

/h-frame：专门用于厘清和定义问题。
/h-char：定义评估解决方案的维度和角色。
/h-explore：发散思维，生成多样化的候选方案。
/h-compare：在公平的基准上对比所有方案。
/h-decide：综合所有信息，生成最终的决策合约。这种方式适合处理非常复杂或争议性的架构决策，你可以和AI在每个步骤上进行多次对话和调整。

从决策到代码：haft run这是连接“思考”和“运行”的桥梁。假设你通过上述流程得到了一个决策IDdec-20260414-001，要实施它，只需在终端执行：

haft run dec-20260414-001 --agent claude

Haft会做以下几件事：

从知识库中读取该决策的所有细节。
构建一个包含完整上下文（问题、方案对比、决策理由、代码不变量）的超级提示。
在后台启动一个Claude Code会话（或你指定的其他代理），并将这个提示发送给它。
AI代理在编码时，会明确知晓哪些规则（不变量）必须遵守，哪些目标（声明）需要达成。
代码生成并应用后，Haft会自动为相关文件创建“基线”快照，作为后续变更检测的参照点。

治理健康检查：haft check定期在项目根目录运行这个命令。它会扫描所有的决策合约、证据和代码现状，给出一个治理健康报告。退出码为0表示一切正常，为1则表示发现了需要关注的问题（如证据过期、不变量被违反）。这个命令可以轻松集成到CI/CD流水线中，作为代码合并前的一道质量关卡。

4. 深度解析：Haft的差异化优势与底层原理

4.1 决策作为“活文档”与“可计算资产”

传统文档是静态的，写完就过时了。Haft的决策合约是“活”的。其核心在于引入了证据的有效性模型和信任衰减机制。

每个附加到决策上的证据（如性能测试报告、用户调研数据）都会被标记一个“形式化等级”和“一致性等级”，并设定一个过期日期。Haft内部使用一个公式计算决策的当前“有效信任分数”。这个分数是证据强度、一致性和新鲜度的函数。随着时间的推移，即使代码没变，该决策的信任分数也会自然下降，因为其依据的上下文可能已改变。当分数低于阈值时，仪表盘上该决策的状态就会变黄或变红，迫使工程师重新审视。这相当于为每一个技术决策内置了一个“保鲜期”倒计时。

4.2 基于第一性原理框架的思考操作系统

Haft并非凭空发明了一套方法论，其严谨性根植于第一性原理框架。FPF提供了一套跨学科的、用于严谨思考的架构模式。Haft的/h-reason等工具，本质上是为你的AI代理装备了一个FPF原生的“操作系统”。

例如，FPF强调在提出解决方案前，必须完成“问题框定”和“特征化”。Haft的/h-frame和/h-char工具就是这一原则的强制体现。FPF中的“帕累托前沿”概念被用于方案比较，以找到非支配最优解。“最弱链接保证”的思想则体现在决策合约的“不变量”上——系统的稳健性取决于其最薄弱环节的约束是否被满足。

通过haft fpf search命令，你甚至可以直接查询内嵌的FPF知识库，将具体的工程问题与底层的思维模式联系起来。这使得Haft不仅仅是自动化工具，更是一个工程思维训练器。

4.3 知识图谱：连接决策与代码实体

Haft在后台为你的项目构建了一个轻量级的知识图谱。这个图谱记录了：

决策与代码模块/文件之间的影响关系。
决策与决策之间的依赖或冲突关系。
不变量与具体代码行的约束关系。

当你运行haft query或点击桌面应用中的某个文件时，Haft能立刻告诉你：“这个文件受到哪三个历史决策的约束？其中哪个决策的证据已经过期了？” 这种从代码到决策缘由的追溯能力，对于理解复杂遗留系统、进行安全审计或新人入职，具有不可估量的价值。

5. 实战场景与常见问题排查

5.1 典型工作流示例：重构一个API端点

假设你需要重构一个陈旧的用户信息查询API/user/{id}。

启动：在Cursor中，输入/h-reason “重构 /user/{id} API 端点，当前代码混乱且缺乏缓存，导致数据库压力大。”
自动流程：
- 框定：Haft引导你确认，这是一个“优化”问题（性能）和“合成”问题（代码结构）的混合。
- 特征化：你与AI一起定义维度：API响应延迟、数据库QPS降低率、代码可维护性（圈复杂度）、实现复杂度。并为每个维度分配角色。
- 探索：AI生成几个本质不同的方案：A) 在现有代码上加缓存层；B) 使用CQRS模式分离读写；C) 将逻辑迁移到一个新的微服务。
- 比较：Haft在一个公平表格中对比三个方案。方案B在可维护性和长期扩展性上得分高，但实现复杂度也最高。方案A最快但治标不治本。方案C引入了运维成本。
- 决策：经过讨论，你选择了方案B，并形成了一个决策合约dec-20250401-abc123。合约中声明了不变量：“用户读写模型必须分离”、“查询端不得包含业务逻辑”；以及可测量声明：“重构后，该端点P99延迟 < 50ms”。
执行：在终端运行haft run dec-20250401-abc123 --agent cursor。Cursor AI在全新的聊天窗口中开始工作，其系统提示中已经包含了上述所有约束和目标。
验证与基线：实现完成后，你运行测试和基准测试，将结果作为“证据”附加到决策合约上。Haft自动创建代码基线。
治理：两周后，另一位开发者在修改关联模块时无意中引入了业务逻辑到查询模型。Haft的haft check或持续集成流水线检测到“不变量被违反”，并标记该决策为“失效”，通知负责人。

5.2 常见问题与解决方案

问题1：安装后，在Cursor里看不到/h-命令。

排查：运行haft init --cursor后，需要手动在Cursor设置中启用MCP服务器。
解决：打开Cursor → Settings → MCP Servers。你应该能看到一个名为haft的服务器，但默认可能是关闭状态。将其切换为启用。重启Cursor后命令应该出现。

问题2：/h-reason命令执行时间很长，或者AI代理似乎“卡住”了。

排查：Haft的深度推理模式可能会进行多轮对话和复杂计算。同时，检查你的AI服务提供商是否有速率限制或上下文长度限制。
解决：对于简单问题，可以考虑使用分步命令（如先/h-frame），手动控制节奏。确保你的网络连接稳定。如果问题持续，查看Haft的日志（通常有--verbose标志）或AI工具的控制台输出。

问题3：haft check报告大量“证据过期”警告，但我觉得没必要更新。

排查：证据的过期日期和信任衰减模型是预定义的，可能不符合你的项目节奏。
解决：你可以使用haft_decision工具的action="refresh"参数来更新特定证据的有效期。更重要的是，你应该根据项目实际情况，在决策合约中设定更合理的valid_until日期。Haft的治理是辅助性的，最终判断权在工程师手中。

问题4：团队协作时，每个人的Haft决策记录会冲突吗？

排查：早期版本使用日期序列ID，在分支合并时可能冲突。
解决：v6.2之后，Haft使用了随机十六进制ID（如dec-20260420-a3f7c1），极大降低了合并冲突的概率。决策合约文件（通常是Markdown或JSON）应被纳入版本控制系统。团队需要约定对决策文件的修改和合并流程，就像对待代码一样。

问题5：桌面应用启动失败或显示异常。

排查：桌面应用处于pre-alpha阶段，稳定性不足。可能缺少运行时依赖或存在平台特定问题。
解决：首先确认你是通过haft desktop命令启动。如果失败，尝试从源码构建：确保已安装Rust工具链和Node.js环境，然后按照README在desktop-tauri目录中运行cargo tauri build。更稳妥的做法是，目前主要依赖稳定的MCP插件模式，桌面应用仅作为实验性功能查看。

从我的实际使用体验来看，Haft最大的价值不在于替代思考，而在于规范化和外化思考过程。它迫使你和AI在动手前先“对齐”，并把对齐的结果固化下来。在快节奏的AI辅助开发中，这看似多了一步，实则避免了未来数小时甚至数天的混乱、返工和技术债堆积。它特别适合用于架构决策、关键模块重构、性能优化方案选型等“牵一发而动全身”的场景。对于微小的、一次性的修改，直接让AI操作或许更高效，但对于那些会进入代码库并长期存在的逻辑，用Haft给它上一份“保险”，是未来高质量AI工程协作的必然趋势。