1. 项目概述Haft——为AI编码时代引入工程纪律的“缰绳”如果你和我一样已经深度使用Claude Code、Cursor这类AI编码助手超过半年一个深刻的体会是它们写代码的速度快得惊人但代码背后的决策质量却像开盲盒。上周让AI重构的缓存层这周就因为一个边缘用例崩了昨天生成的API设计今天发现和另一个模块的接口约定冲突了。我们陷入了“快速交付”的幻觉却丢失了“正确交付”的确定性。这正是Haft要解决的核心问题——它不是另一个写代码的AI而是一个“工程治理器”一个确保AI辅助的软件交付过程具备可追溯、可验证、可持续决策的框架。简单来说Haft在你或你的AI助手的意图和最终执行之间架起了一座名为“工程纪律”的桥梁。它的核心理念可以概括为“思考 → 运行 → 治理”。在让AI动手写代码之前强制进行问题界定、方案对比和决策记录并将这些决策转化为可证伪的“工程合同”。当底层假设变化或代码发生漂移时Haft能第一时间告诉你当初做这个决定的依据已经失效了。这就像给你的AI助手配了一个经验丰富的技术负责人在每一个关键岔路口确保你选的是那条经得起时间考验的路而不是仅仅看起来最短的那条。目前Haft主要通过两种方式融入你的工作流一是作为MCP插件为Claude Code、Cursor、Gemini CLI等主流AI编码工具提供结构化的推理工具集二是通过一个独立的桌面应用目前处于pre-alpha阶段提供一个可视化的驾驶舱用于管理推理状态、编排AI代理和查看治理仪表盘。两者共享同一个核心引擎桌面端更适合人类进行深度思考和全局把控而MCP插件则是AI在编码时进行“思考”的底层操作系统。2. 核心设计理念与工作流拆解2.1 从“快”到“对”Haft引入的范式转变传统的AI编码流程往往是线性的你提出一个需求比如“优化登录接口的性能”AI直接生成代码。这个过程缺失了几个关键环节问题是否被正确定义有哪些可能的解决方案选择A而非B的量化依据是什么这个决策的有效期是多久Haft的整个设计都围绕着补全这些环节。它的理论基础源于Anatoly Levenchuk提出的“第一性原理框架”First Principles Framework, FPF。FPF是一套严谨的、跨学科的思维架构强调在解决问题前先框定问题在比较方案前先明确比较的维度和角色。Haft将这套理论工程化转化为AI代理可以理解和执行的六种MCP工具和一个核心命令从而将模糊的“让AI写代码”变成了一个可管理、可审计的工程过程。2.2 核心工作流两种驱动模式Haft提供了两种驱动工作流的方式适应不同场景下的精细控制需求。一站式命令/h-reason这是最快捷的入口。你只需要向AI助手描述你的问题例如在Cursor的命令面板中输入/h-reason “用户上传大文件时前端频繁超时需要优化”。Haft会接管后续所有步骤问题界定分析这是性能优化问题、架构设计问题还是资源分配问题。生成备选方案基于问题界定生成2-3个本质上不同的解决方案例如前端分片上传、后端流式处理、引入消息队列异步处理。公平比较按照预先定义的比较维度如开发成本、维护复杂度、用户体验、可扩展性在同等条件下对比各个方案。记录决策将最终的决策、选择理由、必须遵守的不变量、成功指标以及决策有效期记录为一个结构化的“决策合同”。整个过程是自动的Haft会根据问题的复杂度自动选择合适的推理深度。手动分步驱动对于更复杂或你想完全掌控的过程可以拆解为五个手动步骤对应五个MCP命令/h-frame明确“什么东西坏了” 这不是直接要解决方案而是界定问题的边界和本质。例如不是“优化数据库”而是“在并发用户超过1000时订单查询API的P99延迟从50ms飙升到2秒”。/h-char明确“什么才是重要的” 定义评估解决方案的维度和这些维度的权重。例如定义维度包括“实施难度1-5”、“预期性能提升%”、“对现有架构的侵入性1-5”并指定本次决策更关注性能提升。/h-explore探索“真正不同的选项”。Haft会确保生成的选项具有多样性而不是同一方案的细微变体。它会利用知识图谱回忆项目中过去类似的决策避免重复探索。/h-compare进行“公平的比较”。这是Haft的亮点之一。它会强制进行“对等比较”确保每个方案都在相同的约束条件和评估标准下被衡量并应用“帕累托前沿”分析剔除那些在所有维度上都次于其他方案的“劣势选项”。/h-decide生成“工程合同”。将比较结果固化为一个决策记录其中包含“不变量”无论如何修改代码都必须保持为真的条件、“主张”期望达成的目标如“P99延迟降低至200ms”、“证据”支持该决策的数据或文档链接以及“有效期”。这种分步模式将隐性的思考过程显性化、结构化非常适合在团队协作或处理关键架构决策时使用。3. 核心组件深度解析六种MCP工具Haft通过六种MCP工具将理论落地。理解这些工具是有效使用它的关键。haft_note微决策与自动过期用于记录小型、临时的决策。例如“暂时禁用某个缓存策略以调试一个诡异的问题”。它的特点是自带验证逻辑和自动过期时间。一旦过期该笔记就会在仪表盘中标记为“待审查”防止临时方案被遗忘而变成技术债务。haft_problem问题框定与维度定义这是所有推理的起点。它强制你在思考解决方案前先明确问题的类型是优化、诊断、搜索还是综合问题、边界和评估维度。你可以为每个维度分配一个“角色”例如“运维人员关心可用性”、“开发者关心可维护性”这有助于生成更全面、平衡的解决方案。haft_solution方案探索与多样性检查基于定义好的问题生成解决方案选项。关键功能是“多样性检查”它会分析方案之间的本质差异避免给你三个只是参数不同的“伪选项”。同时它会查询知识图谱找出历史上类似问题的解决方案供你参考或避免重复。haft_decision决策合同与生命周期管理这是Haft的核心产出物。一个决策合同包含不变量代码必须始终满足的条件例如“用户会话数据必须加密存储”。主张可衡量的目标例如“首页加载时间缩短30%”。证据支持决策的材料附带“形式化等级”和“一致性等级”。一张随手画的架构图可能是F1等级而一个经过压力测试的报告则是F3等级。生命周期包括创建时间、有效期限、关联的代码文件以及一个动态计算的“有效信任分数”。haft_decision还支持action”evidence”和action”measure”操作用于事后追加证据或进行实施后的效果验证。haft_refresh生命周期管理决策不是一成不变的。haft_refresh工具会扫描所有决策工件检查其证据是否过期、关联的代码是否发生漂移、依赖的底层决策是否已变更。当信任分数因证据过期而衰减到阈值以下时它会自动触发审查流程。haft_query搜索与状态仪表盘这是你的全局视图。你可以搜索所有决策、查看当前的治理健康状况有多少决策已过期、有多少不变量可能被违反、通过文件反向查找影响它的决策甚至直接在FPF知识库中搜索相关的第一性原理模式。注意这六个工具通过MCP协议暴露给你的AI助手。这意味着你在Claude Code或Cursor的聊天界面中可以直接通过自然语言调用它们例如说“帮我把这个决策的证据更新为最新的测试报告”AI会正确调用haft_decision工具并填充参数。4. 从决策到代码haft run与治理闭环记录决策只是第一步更重要的是将决策转化为代码并确保代码在后续演化中依然遵守决策的约定。这就是haft run命令和治理闭环的作用。4.1 自动化实施haft run命令详解当你通过/h-reason或手动流程产生了一个决策例如生成了一个ID为dec-20260414-001的决策你可以通过命令行来执行它haft run dec-20260414-001 --agent codex这个过程是高度自动化和上下文感知的读取决策上下文haft run会读取该决策合同的所有内容——问题定义、选择的方案、不变量、主张、受影响的文件列表。构建智能提示它将上述信息结合项目知识图谱通过依赖图建立决策与代码模块的链接构建成一个富含上下文、约束明确的提示词。生成代理执行根据--agent参数支持codex或claudeHaft会启动相应的AI编码代理如Codex并将构建好的提示词发送给它。代理将在完整的推理上下文中开始工作。不变量作为护栏决策中定义的“不变量”会作为硬性约束被注入到提示中。例如如果决策包含“不得修改外部支付接口的调用签名”这一不变量AI在生成代码时会主动避开相关修改。完成后自动基线快照代理完成代码修改后haft run会自动为相关文件创建一份“基线快照”。这份快照记录了决策实施后代码的预期状态是后续“漂移检测”的基准。桌面应用中的“Implement”按钮其背后调用的正是haft run这一套流水线。CLI和桌面端是同一内核的两个不同界面。4.2 证据工作流与信任衰减模型决策的可靠性建立在证据之上。Haft对证据的管理非常严谨形式化等级从F0口头讨论到F3形式化证明或严格的实验报告。等级越高证据的可靠性权重越大。一致性等级从CL0证据与主张无关或矛盾到CL3证据直接且有力地支持主张。CL0级别的证据会被系统拒绝。有效信任分数这是一个动态计算的指标R_eff。它综合了证据的形式化等级、一致性等级以及一个关键因素——时间。证据会“过期”过期的证据其贡献的信任值会衰减。例如一年前的性能测试报告对于当前系统性能的决策其R_eff会大打折扣。证据更新与替代当有新的、更强的证据出现时可以标记为“替代”旧证据。系统会维护证据的版本链。通过haft_decision(action”measure”, …)你可以在决策实施后进行效果验证并将验证结果作为新的证据附加到决策上。如果验证失败例如主张中“性能提升30%”未达到该决策会自动被重新打开转换为一个待解决的“问题卡片”从而形成闭环。4.3 治理健康检查haft check与/h-verify项目进行一段时间后如何知道整体的决策健康状况Haft提供了两个核心检查工具。haft check这是一个命令行工具用于本地治理验证。它会在项目根目录运行扫描所有决策检查其证据是否过期、不变量是否被违反、依赖决策是否已变更。它返回退出码0代表健康无问题1代表发现了需要关注的事项。这个命令可以轻松集成到CI/CD流水线中实现“治理即代码”。/h-verify这是一个MCP命令在AI助手界面中使用。它会提供一个更全面的、交互式的治理状态报告清晰地展示所有存在的问题、可能的不变量违反以及代码漂移情况。这两个工具确保了治理不是一次性的活动而是一个持续的、可集成到开发流程中的实践。5. 实战部署与集成指南5.1 安装与初始化Haft的安装非常简单通过一个安装脚本即可完成curl -fsSL https://raw.githubusercontent.com/m0n0x41d/haft/main/install.sh | bash安装后你会在系统路径中获得haft命令。接下来需要在你的项目根目录进行初始化。这里有一个关键点必须根据你使用的AI编码工具指定对应的标志。这是因为不同工具Claude Code, Cursor, Gemini CLI等的MCP服务器配置和命令/技能安装位置不同。# 如果你主要使用 Claude Code默认 haft init # 如果你使用 Cursor haft init --cursor # 如果你使用 Gemini CLI haft init --gemini # 如果你希望配置当前项目本地可用的命令便于团队共享 haft init --localhaft init命令会做以下几件事在项目根目录或用户全局配置目录下创建或更新MCP服务器配置文件如.mcp.json或.cursor/mcp.json将Haft的MCP服务器地址添加进去。将Haft的推理命令如/h-reason和技能安装到对应AI工具的目录下。对于已有项目强烈建议随后在AI助手中运行/h-onboard命令。这个命令会让AI代理扫描你的代码库识别出已有的、值得被捕获为决策的设计点或约定比如“为什么这里用Redis而不用Memcached”并帮你创建初始的决策记录快速建立知识图谱。重要提示针对Cursor用户执行haft init --cursor后你需要手动打开Cursor的设置界面找到MCP服务器列表定位到刚刚添加的haft服务器并将其启用Toggle打开。Cursor默认会将新添加的MCP服务器设置为禁用状态。5.2 与不同AI工具集成的细节下表详细说明了haft init对不同工具的具体影响帮助你理解其工作原理工具MCP 配置文件位置命令/提示词安装位置技能安装位置Claude Code项目根目录.mcp.json~/.claude/commands/或.claude/commands/(使用--local)~/.claude/skills/h-reason/或本地 (使用--local)Cursor.cursor/mcp.json~/.cursor/commands/或.cursor/commands/(使用--local)~/.cursor/skills/h-reason/或本地 (使用--local)Gemini CLI~/.gemini/settings.json~/.gemini/commands/或本地 (使用--local)—Codex CLI/App.codex/config.toml~/.codex/prompts/或.codex/prompts/(使用--local)~/.agents/skills/h-reason/JetBrains Air.codex/config.toml项目skills/目录项目skills/h-reason/目录实操心得本地模式 vs 全局模式--local模式将配置和命令安装在项目目录内如.claude/commands/。这非常适合团队项目确保所有成员使用同一套Haft配置和命令版本管理也通过Git同步。缺点是每个项目都需要单独初始化。全局模式将配置安装在用户主目录。方便个人在多个项目间使用统一的Haft环境但不利于团队协作时的配置一致性。对于团队项目我强烈推荐使用--local模式并将其产生的配置文件如.cursor/mcp.json纳入版本控制。5.3 桌面应用Pre-Alpha的探索桌面应用提供了更丰富的可视化治理体验但目前处于早期阶段需谨慎使用。启动安装Haft后在终端运行haft desktop。它会尝试查找已安装的Haft.app如果未找到则回退到开发构建版本。核心功能界面仪表盘总览所有决策、治理发现的问题和近期活动。问题看板以看板形式管理处于不同阶段待界定、探索中、已决策的问题。决策详情页展示单个决策的所有信息包括证据链、信任分数衰减曲线、关联的代码文件。组合对比使用帕累托前沿网格图可视化对比多个方案的优劣。搜索通过CmdK快速搜索决策、问题或代码。警告桌面应用目前是Pre-Alpha版本可能存在不稳定性和功能变更。不建议在生产关键环境中依赖它。当前最稳定、最成熟的使用方式是通过MCP插件与你的AI编码工具集成。6. 常见问题与故障排查实录在实际集成和使用Haft的过程中我遇到了一些典型问题。这里记录下排查思路和解决方案希望能帮你绕过这些坑。6.1 MCP工具未生效或AI助手无法识别命令症状执行haft init --cursor后在Cursor中键入/看不到h-reason等命令。排查步骤检查MCP服务器是否启用这是Cursor下最常见的问题。进入Cursor Settings → MCP Servers找到名为haft的条目确认其旁边的Toggle开关是**绿色启用**状态。Cursor默认添加新服务器时为禁用。检查配置文件路径确认haft init命令是在项目根目录执行的。检查项目根目录下是否生成了.cursor/mcp.json文件对于Cursor。文件内容应包含指向Haft MCP服务器的配置。重启AI助手有时更改MCP配置后需要完全重启Claude Code、Cursor或Codex的应用才能使新配置生效。查看日志运行haft serve命令可以手动启动MCP服务器并查看日志检查是否有错误。同时在AI助手的设置中开启MCP调试日志看是否有连接错误。6.2 决策记录的文件存储与合并冲突症状团队协作时多人同时创建决策在合并Git分支时产生冲突。背景与解决方案早期版本的Haft使用基于时间的决策ID如dec-20260414-001在并行开发时极易冲突。v6.2版本后Haft引入了随机十六进制后缀的ID如dec-20260420-a3f7c1极大降低了冲突概率。实操建议确保团队使用的Haft版本在v6.2及以上。决策文件默认存储在.haft/decisions/目录下。建议团队在.gitattributes文件中为该目录下的JSON文件设置合适的合并策略例如设置为union因为决策文件是新增居多内容冲突较少。6.3haft check报告误报或漏报症状haft check命令报告某个不变量被违反但代码看起来没问题或者代码实际已偏离决策但检查却没发现。排查思路理解“不变量”的链接机制Haft通过静态分析如依赖图和轻量级模式匹配将决策中的不变量与代码中的特定模块或函数“链接”起来。这种链接可能不完美。检查链接准确性在桌面应用或使用haft query查看该决策的详情确认它关联了哪些具体的代码文件。链接可能错误地关联了无关文件或漏掉了关键文件。审查不变量表达式决策中的不变量是用自然语言描述的例如“用户服务的API响应时间必须小于100ms”。haft check目前还无法直接检测这种性能指标它主要检测代码结构上的不变量如“类X必须继承自类Y”、“函数Z不能直接调用数据库”。对于前者需要依赖haft_decision(action”measure”)进行运行时验证。更新决策范围如果代码结构发生了较大变化可能需要使用haft_decision工具更新决策修正其关联的文件列表或重新表述不变量。6.4 性能与规模考量症状在大型单体仓库中Haft扫描和知识图谱构建速度变慢。经验之谈作用域化不是所有代码都需要Haft治理。可以在项目根目录创建.haft/config.toml文件通过include_paths和exclude_paths配置将Haft的分析范围限定在核心业务模块排除第三方库、生成的代码和文档目录。.haft/workflow.md文件这是v6.1引入的仓库级代理策略文件。你可以在这里定义一些全局规则例如“对于test/目录下的代码不执行深度决策分析”从而提升效率。增量分析Haft的设计支持增量更新。大部分操作如haft check只针对变更的文件和受影响的决策进行分析而非全量扫描。确保你的Haft版本保持更新以获取最佳性能。6.5 文化融入与团队采纳最大挑战Haft引入了一种新的、更严谨的工作流程可能会被团队成员视为“额外负担”。推广技巧从小处着手不要强迫在所有修改上都使用Haft。建议首先在架构决策、关键重构和性能优化这三类任务中强制使用/h-reason。让大家亲身体验到“先思考再动手”带来的长期收益减少返工、设计更清晰。展示价值在代码评审中不仅看代码变更也要求附上相关的Haft决策ID。评审者可以快速理解变更背后的完整上下文和约束条件大幅提升评审效率和质量。将治理集成到CI将haft check作为CI流水线的一个必通步骤。如果检查失败如发现过期决策或违反不变量则流水线中断。这能将治理从“可选项”变为“质量门禁”并逐步培养团队习惯。利用“考古”功能当新人接手一个模块或遇到难以理解的“历史遗留代码”时教会他们使用haft query或桌面应用的搜索功能通过文件查找关联的决策。这能极大降低理解成本是Haft一个非常直观的价值体现。Haft不是一个能立刻解决所有AI编码痛点的银弹但它提供了一套系统性的方法论和工具将软件工程中宝贵的“设计决策”和“上下文”从开发者的头脑和临时聊天记录中沉淀为可管理、可追溯、可验证的组织资产。在AI编码能力日益强大的今天这种对“决策质量”和“工程纪律”的强调或许比单纯追求“生成速度”更为重要。