1. 项目概述Haft为AI编程时代引入工程纪律如果你和我一样已经深度使用过Claude Code、Cursor这类AI编程助手你肯定经历过一个典型的“甜蜜期”后的阵痛代码生成得飞快但几天、几周后回头再看当初为什么选择这个方案那个关键的库版本升级后我们的假设还成立吗面对一个看似相似的bug我们是否在重复解决同一个问题我们交付的速度上来了但代码背后的决策质量却成了一个黑盒。这正是Haft要解决的核心痛点。它不是一个替代你现有AI助手的“另一个编码代理”而是一个工程治理层一个架设在你的意图与AI执行之间的“方向盘”。它的口号“Think → Run → Govern”精准地概括了其价值先思考再运行最后治理。在AI替你写出大量代码之前Haft强制你或你的AI助手完成问题界定、方案对比和决策记录在代码落地后它持续追踪这些决策所依赖的证据和假设是否“过期”确保工程决策的长期有效性。简单来说Haft给你的AI编程工作流装上了“审计日志”和“质量守门员”。它把一次性的、模糊的AI交互变成了可追溯、可验证、可长期维护的工程资产。这对于任何希望将AI辅助开发规模化、纳入严肃软件工程流程的团队或个人来说都是一个范式级的工具。2. 核心设计理念基于第一性原理的决策工程Haft的独特之处在于其坚实的理论基础——它深度整合了Anatoly Levenchuk提出的第一性原理框架。这不是一个简单的口号而是贯穿其所有工具和流程的设计哲学。FPF提供了一套严谨的、跨学科的思维架构用于应对复杂系统问题。Haft将这套理论工程化变成了AI代理可以理解和执行的“操作系统”。2.1 从模糊需求到可证伪的工程合同传统开发中一个需求可能始于一句模糊的对话或一段简短的描述。在AI辅助下这个模糊需求会直接转化为代码中间缺失了关键的工程化思考环节。Haft通过其工具链强制补全这个环节问题界定不是直接问“如何实现X功能”而是先问“当前系统中与X相关的核心矛盾或瓶颈是什么”haft_problem。这避免了解决错误的问题。特征刻画明确评价解决方案好坏的维度是什么性能、可维护性、成本、还是安全性每个维度由谁什么角色来关心haft_problem中的角色定义。方案探索与公平比较生成多个解决方案变体haft_solution并确保它们在同一个基准“奇偶性”上进行比较。Haft会检查方案是否真的具有多样性并应用约束感知的帕累托前沿分析淘汰明显劣势的方案防止“古德哈特定律”当一项指标变成目标它就不再是一个好指标的陷阱。决策记录最终的选择被记录为一个“工程合同”haft_decision。这份合同不是简单的备忘录它包含不变量决策必须遵守的系统约束或规则。主张决策预期达成的具体、可衡量的结果例如“第95百分位延迟降低至100ms”。证据支持该决策的数据、引用或推理附带“形式等级”和“一致性等级”。有效期决策自动失效的日期基于证据的“半衰期”计算。回滚计划如果决策被证明是错误的如何安全地撤销。这个流程确保了每个重要的代码变更背后都有一个经过结构化思考、可被未来验证或推翻的决策依据。2.2 活的决策与信任衰减模型这是Haft最颠覆性的概念之一决策不是静态的档案而是有生命周期的、活的对象。每个决策都有一个计算得出的有效信任分数。这个分数会随着支持它的证据“过期”而衰减。证据有保质期你引用的某个库的基准测试报告是6个月前的。在快速迭代的技术领域这份证据的效力会随时间下降。Haft通过R_eff有效信任度模型量化这种衰减。自动触发复审当决策的R_eff分数低于某个阈值或决策本身超过了“有效期”Haft的治理检查haft check会将其标记为“待刷新”。这就像一个自动化的日历提醒告诉你“是时候重新评估我们当初选择React Query而不是SWR的决定了因为新的版本已经发布”。闭环反馈决策实施后你可以使用haft_decision(action”measure”, …)附加实际的运行结果作为新证据。如果测量结果与决策主张不符该决策关联的问题会自动重新打开触发新一轮的评估。这种机制将事后的、被动的代码审查部分转变为了事前的、基于证据衰减的主动治理。3. 实战部署与你的AI编程工具深度集成Haft的设计非常务实它通过MCP协议无缝嵌入到你现有的AI编程环境中。MCP正迅速成为AI工具与外部服务通信的标准协议这意味着Haft能与你手头的顶级工具协同工作。3.1 安装与初始化一步接入工作流安装过程极其简单一条命令即可curl -fsSL https://raw.githubusercontent.com/m0n0x41d/haft/main/install.sh | bash安装后你需要在项目根目录下运行haft init。这里有一个至关重要的细节你必须根据你主要使用的AI工具来添加对应的标志。这决定了Haft将如何配置该工具的MCP服务器以及安装相关的命令和技能。# 如果你主要用Claude Code也是默认选项 haft init # 如果你希望命令和技能仅安装在当前项目内便于团队共享或版本控制 haft init --local # 如果你主要用Cursor haft init --cursor # 如果你主要用Gemini CLI haft init --gemini # 如果你主要用Codex CLI或Codex App haft init --codex # 如果你主要用JetBrains Air haft init --air # 贪心一点给所有工具都装上适用于多工具环境 haft init --all重要提示Cursor用户必读haft init --cursor执行后你必须手动打开Cursor的设置界面。路径是Settings - MCP Servers。在列表中找到名为haft的服务器你会看到它默认是禁用状态。你需要手动点击旁边的开关将其启用。这是Cursor的一个设计所有新添加的MCP服务器默认关闭以防意外加载。初始化命令具体做了什么它主要做了两件事配置MCP服务器在工具特定的位置如Claude Code的.mcp.jsonCursor的.cursor/mcp.json添加Haft服务器的配置告诉你的AI工具“有一个叫Haft的新能力可以调用”。安装命令/技能将Haft提供的对话命令如/h-reason和思考技能安装到工具的相应目录。这样你就能在聊天窗口直接使用这些命令了。3.2 核心交互模式一键推理与手动驾驶集成完成后你会在AI工具的聊天框里看到Haft提供的命令。主要有两种使用模式模式一全自动推理/h-reason这是最快捷的入门方式。直接输入/h-reason “你的问题描述”例如/h-reason “我们需要重构用户认证模块目前的代码耦合度太高难以添加新的OAuth提供商。”AI助手如Claude会接管并执行完整的Haft推理链调用haft_problem界定问题是性能问题、维护性问题还是扩展性问题。调用haft_solution探索不同的重构方案策略模式、工厂模式、完全外包给Auth0。在haft_solution中基于你定义的维度开发成本、未来灵活性、安全性进行公平比较。最后调用haft_decision将选定的方案及其理由、约束记录为一个决策合同。整个过程完全在对话中完成你就像有一个受过严格工程思维训练的AI架构师在引导讨论。模式二分步手动驾驶如果你希望对每个环节有更精细的控制可以使用分步命令/h-frame专门用于界定和框定问题。/h-char用于刻画问题特征定义评估维度和相关角色。/h-explore专注于生成真正多样化的解决方案选项。/h-compare在确保比较基准公平的前提下对比各个选项。/h-decide将对比结论固化为正式的决策记录。这种模式适合复杂的、战略性的技术决策你需要和AI进行多轮、深入的探讨。3.3 决策落地从合同到代码的桥梁haft run决策记录好了但它还只是文档。如何让它指导编码这就是haft run命令的用武之地。假设你通过上述流程产生了一个决策其ID为dec-20260414-a1b2c3。你可以在终端执行haft run dec-20260414-a1b2c3 --agent claude这个命令会做以下几件事读取决策上下文从Haft的知识图谱中加载该决策的所有信息——不变量、主张、受影响的文件、相关的治理规则。构建增强提示将这些结构化信息作为上下文构建一个远超普通“实现某个功能”的、富含约束和目标的提示词。生成代理启动你指定的AI代理如Claude并将上述提示词喂给它。代理会在严格的“护栏”决策中的不变量内进行代码实现。完成后快照代理完成代码修改后Haft会自动为相关文件创建基线快照。这个快照将成为未来“漂移检测”的基准——如果后续有人无意中修改了这些文件并违反了当初的决策约束Haft能发现。实操心得haft run不仅提高了AI编码的准确性更重要的是它将“决策”和“执行”两个常被割裂的环节连接了起来。执行者无论是AI还是人不再需要去翻找模糊的会议纪要或PR描述所有约束和意图都清晰、结构化地传递了过来。这极大地减少了因理解偏差导致的返工。4. 核心工具链与知识图谱深度解析Haft的强大源于其背后一套精心设计的工具和持久化的知识系统。理解这些组件能帮助你更好地驾驭它。4.1 六大MCP工具详解Haft通过六个MCP工具向AI暴露其核心能力每个工具都承担着特定的职责工具核心职责与使用场景haft_note微决策记录器。用于捕捉那些小的、临时的决定比如“为什么这里用一个临时变量”。它可以附加验证逻辑和自动过期时间避免代码注释变成过时的“谎言”。haft_problem问题框架构建器。这是理性思考的起点。它强制你在思考解决方案前先明确“问题到底是什么”。你可以定义多个评估维度如“性能”、“可读性”并为每个维度指定关心的“角色”如“终端用户”、“运维人员”。这确保了解决方案的评价是全面的、多视角的。haft_solution方案探索与比较引擎。它不只是生成选项还会检查选项之间的“多样性”防止比较两个本质相同的方案。在比较时它会强制执行“奇偶性”检查确保比较是苹果对苹果的。其内置的帕累托前沿分析能直观地展示非支配解。haft_decision工程合同生成器。这是最终的产出物。它将问题、方案、比较结果打包成一个包含不变量、主张、证据、回滚计划和有效期的正式记录。action参数支持create创建、evidence附加证据、measure附加测量结果等多种操作让决策成为一个可更新的活文档。haft_refresh生命周期管理器。用于批量检查和管理所有决策、问题、方案等“工件”的生命周期。它可以找出所有证据过期的决策或所有需要重新评估的开放问题是进行项目“治理健康度”大扫除的关键工具。haft_query知识图谱查询器。这是你的决策搜索引擎。你可以查找所有与某个文件相关的决策查看所有“健康状况不佳”的决策或者获取整个项目的治理状态仪表板。它让你对项目的决策资产一览无余。4.2 知识图谱连接决策与代码的纽带Haft在项目根目录的.haft文件夹下维护着一个本地知识图谱。这个图谱不仅仅是存储决策文本它建立了决策与代码实体之间的链接。依赖关系映射Haft会分析你的代码库支持主流语言构建模块间的依赖图。当你创建一个决策并指定其“影响范围”时Haft会将这个决策节点链接到具体的模块或文件节点上。影响传播分析这是治理的核心。当某个底层模块的决策因证据过期而失效时Haft可以向上追溯警告所有依赖该模块的更高层决策“您所依赖的基础假设可能已不再成立”。这种级联的信任衰减分析是人工管理几乎无法实现的。跨会话记忆你在一次会话中关于“数据库连接池”的决策会被记录下来。当几周后你在另一个会话中处理“API响应慢”的问题时Haft在问题界定阶段haft_problem就可能提示你“之前有一个关于数据库连接池配置的决策dec-xxx可能与当前问题相关”。这打破了AI对话固有的“失忆症”实现了决策上下文的长期延续。注意事项.haft文件夹包含的是项目的决策元数据建议将其纳入版本控制系统如Git。这能让团队所有成员共享同一套决策历史和上下文。但同时要注意其中可能包含AI生成的分析内容如果项目有严格的代码保密要求需制定相应的策略。5. 桌面应用可视化的治理驾驶舱除了命令行和MCP插件Haft还提供了一个桌面应用目前处于pre-alpha阶段。你可以通过haft desktop命令启动它。这是一个用Tauri 2Rust Web前端构建的本地应用提供了一个集中管理所有决策和治理状态的图形化界面。核心功能预览治理仪表板首页展示项目的整体健康状态有多少活跃决策、多少决策已过期、有多少待解决的问题、最近的活动记录。让你对项目“决策债”一目了然。问题看板以看板形式管理所有处于不同阶段待界定、探索中、已决策的问题。决策详情页点击任何一个决策可以看到其完整的合同内容、证据链、信任分数衰减曲线、以及所有关联的代码文件。证据的“形式等级”和“一致性等级”会以视觉化方式呈现。帕累托比较表对于涉及多方案比较的决策这里会展示一个清晰的表格用边框高亮标出帕累托最优解帮助你直观理解当时的权衡。一键实施在决策详情页点击“Implement”按钮会触发与haft run相同的流程在桌面内嵌的终端或你配置的AI工具中启动一个带有完整决策上下文的编码任务。全局搜索通过CmdKMac或CtrlKWindows/Linux可以快速搜索决策、问题、代码文件甚至搜索FPF规范库中的概念。个人体会桌面应用将Haft从一个“增强AI提示的工具”提升到了一个“项目决策治理平台”。对于技术负责人或架构师来说定期打开桌面应用浏览仪表板是一种极其高效的项目健康度巡检方式。它让原本隐形的技术决策和其生命周期变得可见、可管理。6. 进阶工作流与治理实践将Haft融入日常开发需要一些实践来发挥其最大价值。6.1 证据工作流的规范化决策的长期价值取决于其证据的质量。Haft鼓励你为证据附加元数据形式等级从F0非正式如口头讨论到F3高度形式化如经过同行评审的论文或严格的实验报告。等级越高证据的初始可信度越高但获取成本也越高。一致性等级从CL0与主张无关到CL3直接证明主张。CL0的证据会被Haft在计算信任分数时直接拒绝。这防止了用无关信息充数。有效期为证据设定一个合理的过期时间。一份三年前的性能测试报告其有效期应该很短。在决策实施后立即使用haft_decision(action”measure”, …)添加第一批证据比如单元测试通过率、集成测试结果、或初步的基准测试数据。这为决策建立了初始的信任锚点。6.2 利用haft check建立持续集成检查haft check是一个强大的命令行工具它会扫描整个项目输出所有治理层面的发现哪些决策的信任分数已低于阈值哪些决策已超过有效期哪些代码文件的当前状态与关联决策中记录的不变量相冲突漂移检测是否存在未关联到任何决策的“孤儿”代码模块可能意味着缺乏设计意图记录你可以将haft check集成到你的CI/CD流水线中。例如配置一个每晚运行的Job如果haft check返回非零退出码表示存在治理问题就自动生成一个报告或创建一个跟踪任务。这实现了对决策健康度的自动化监控。6.3 处理遗留项目深度上船/h-onboard对于一个已有大量代码但零决策记录的项目从头开始创建决策是令人望而却步的。这时可以使用/h-onboard命令。在你的AI工具中执行它AI会开始扫描你的代码库尝试识别出隐含的设计决策、关键模块和可能的依赖关系并建议将其捕获为正式的Haft决策。这个过程是半自动的需要你进行确认和细化但它极大地降低了为遗留系统建立决策知识图谱的启动成本。7. 常见问题与排查实录在实际使用中你可能会遇到一些典型情况。以下是我在早期采用过程中积累的一些经验。问题1执行haft init --cursor后在Cursor里看不到/h-开头的命令。排查首先确认初始化时是否在正确的项目根目录。然后最关键的一步打开Cursor设置 - MCP Servers查看haft服务器是否被启用。Cursor默认禁用新加的MCP服务器。解决找到haft点击切换按钮启用它。然后完全关闭并重启Cursor。重启后命令应该就会出现。问题2/h-reason命令执行时间很长或者AI没有按预期调用Haft工具。排查这通常是因为AI代理如Claude在生成回复时没有正确选择或调用MCP工具。检查AI的回复看它是否提到了“调用haft_problem”等字样。如果没有可能是提示词理解有偏差。解决尝试更清晰、更具体地描述问题。如果不行可以切换到手动分步模式/h-frame-/h-char…每一步给AI更明确的指令。确保你的AI工具订阅了足够的上下文长度因为Haft工具调用可能会返回较长的结构化信息。问题3.haft目录下的文件发生合并冲突。解决这是团队协作中可能遇到的问题。从v6.2版本开始Haft将决策ID从基于时间的序号dec-20260414-001改为了随机十六进制后缀dec-20260414-a3f7c1这大大降低了不同分支创建决策时ID冲突的概率。确保团队都使用较新版本的Haft。如果发生冲突手动合并JSON文件时需小心重点关注id,created_at,updated_at等字段。问题4haft check报告了大量“证据过期”警告如何处理策略不要试图一次性处理所有警告。将其视为技术债的一种。在团队计划中定期如每两周安排一个“决策刷新”时段。使用haft_query找出信任分数最低的Top 5个决策优先评估它们。如果证据依然有效就用haft_decision(action”evidence”, …)添加一条新的证据记录比如“经手动复查原假设在v2.0版本下仍成立”以重置其信任衰减时钟。问题5Haft适合所有类型的项目吗体会并非如此。对于快速原型、一次性脚本或生命周期极短的项目引入Haft的 overhead 可能得不偿失。它最适合中大型、长期维护、团队协作、业务逻辑复杂的项目。在这些项目中前期几分钟的决策记录可能在几个月后为你节省数小时甚至数天的排查和重构时间。我的经验法则是如果一个代码模块预计会被触摸修改或阅读超过3次那么就值得为它创建一个Haft决策记录。Haft代表的是一种思维方式的转变在AI极大提升编码速度的今天我们应该将宝贵的智力更多投入到思考、决策和治理上而不是沉浸在代码生成的细节里。它不替代你的AI助手而是让你的AI助手变得更像一个严谨的工程伙伴。开始可能会觉得流程有些繁琐但一旦你习惯了这种有纪律的思考方式并尝到它在长期维护中带来的甜头就很难再回到那种“写了就忘”的混沌状态了。