1. 项目概述为什么我们需要为AI驱动的软件开发生命周期套上“缰绳”在AI代理Agent技术席卷软件工程领域的今天我们谈论的焦点往往集中在两个核心组件上大语言模型LLM和编排框架Harness。模型负责思考、决策和生成代码而框架则负责协调工具调用、管理上下文和执行多步骤工作流。这两者结合确实带来了前所未有的自动化能力。然而一个关键的问题也随之浮现当我们将开发任务交给一个自主运行的AI代理时我们如何确保它是在一个可控、可审计、符合既定规则和流程的“物理世界”中工作而不是在一个可以随意发挥、缺乏约束的“想象空间”里横冲直撞这就是Keel项目试图回答的核心问题。它不是一个替代模型或框架的新工具而是一个被长期忽视的、至关重要的第三层宿主层Host Layer。你可以把它想象成软件开发团队的“物理定律”或“交通规则”。无论执行者是人类工程师还是AI代理这套规则都同样适用并且被一个持久化的状态机强制执行。Keel将自己定位为这个宿主层的一个具体实现——一个命令行状态机它定义了什么是“有效的工作”什么是“完成的证据”以及“完成”本身意味着什么。它不是限制模型能思考什么而是保证系统会强制执行什么。这就像给一匹能力强大的骏马套上缰绳Leash不是为了束缚它的奔跑而是为了确保它始终奔跑在正确的赛道上并能在需要时被安全地引导。2. 核心设计理念CLI状态机作为统一的治理层2.1 从“上下文信任”到“结构信任”的范式转变在传统的“模型框架”模式中我们依赖的是一种“上下文信任”。我们通过精心设计的提示词Prompt告诉模型我们的规则和期望并希望模型在本次会话的上下文窗口内记住并遵守它们。然而这种信任是脆弱且临时的。模型可能会“忘记”或误解提示词中的约束当会话重启、上下文重置后所有的规则都需要重新“协商”。人类不得不反复检查AI的工作以确保它没有偏离几天前甚至几小时前设定的架构决策或完成标准。这种模式将人类变成了一个永不停歇的“一致性检查器”成本高昂且不可持续。Keel引入的“结构信任”则完全不同。它将规则和约束从易变的提示词和短暂的会话记忆中抽离出来固化到一个持久化的、由状态机管理的系统中。规则不再是建议而是“物理定律”。例如一条处于“提议中”状态的架构决策记录ADR会像一堵真实的墙一样阻止任何涉及该架构边界的工作被启动——无论执行者是谁。这种阻塞不是通过模型“想起来要检查ADR”来实现的而是状态机在底层直接拒绝了工作项的状态变迁请求。信任的对象从模型的“自觉性”转移到了状态机“不可违背的规则”上。2.2 统一交互界面人与代理共用同一套“物理接口”Keel最精妙的设计之一是它强制所有参与者——无论是人类开发者还是AI代理——都通过完全相同的命令行接口CLI与系统交互。这套CLI就是状态机的外在表现。它定义了一系列命令每个命令都对应着状态机的一个合法状态变迁。# 无论是人还是AI代理都使用同样的命令序列 keel turn # 查看看板整体状态方向 keel next --role operator # 以“执行者”角色领取下一个可执行任务 keel story start id # 开始处理一个用户故事状态变为“进行中” keel story record id # 为故事的验收条件附加可验证的证据 keel story submit id # 提交故事触发关卡检查所有验收条件必须有证据这个设计消除了“侧门”。AI代理没有特权路径它必须像人类一样遵守相同的流程撞击相同的关卡提供相同格式的证据。如果一个代理试图跳过“提交证据”的步骤直接标记故事完成它会收到和人类操作者一模一样的、来自状态机的硬性拒绝错误。这种设计极大地简化了系统的复杂性和可理解性因为治理逻辑只有一套并且对所有人透明。2.3 文件即真相Git即审计日志为了实现持久化和可审计性Keel将所有看板状态用户故事、史诗、ADR、航行等都存储为带有YAML前置元数据的Markdown文件。没有隐藏的数据库没有可能不同步的后台守护进程也没有需要查询的独立服务。这种选择带来了几个根本性优势真相唯一源系统的当前状态完全由文件系统中的文件内容定义。要了解状态只需读取文件。不可变的审计追踪Git提交历史成为了系统所有变更的完整、不可篡改的审计日志。当AI代理提交一个故事时证据文件和生命周期状态变更会作为一次提交的一部分被记录到代码库中。你可以通过git log追溯任何一个工作项从创建到关闭的完整历程包括谁或哪个代理在什么时候做了什么附带了什么证据。可移植性与简单性整个系统的状态可以像任何代码库一样被克隆、分支、合并和回滚。部署和备份变得极其简单。知识图谱可视化基于文件间的引用关系如故事链接到史诗ADR关联到有界上下文可以动态生成并可视化整个项目的“工件网络”。一个缺失的链接直接意味着证据的缺失一个孤立的节点则代表着一个被遗忘的工件。这为项目健康度提供了结构化的洞察。3. 核心机制深度解析3.1 验证驱动开发用证据替代断言在AI辅助开发中一个常见的失败模式是“自信的错误答案”。模型声称它完成了任务编排框架就相信并记录了完成状态。但由于缺乏结构化的要求往往没有人去实际验证证据是否存在或有效。Keel通过其核心机制——验证驱动开发——在状态机层面解决了这个问题。每个用户故事都包含一组明确的验收标准。故事从“进行中”状态变迁到“待人工验证”状态即提交时状态机会执行一个硬性关卡检查每一项验收标准都必须有已记录的、可验证的证明文件与之关联。# 假设故事ID为VDmdk1uib它有两项验收标准AC-01和AC-02 # AI代理完成了代码编写但只记录了AC-01的测试通过日志 $ keel story submit VDmdk1uib Error: Transition blocked by gate all-acs-verified. - Acceptance criterion AC-02 has no recorded verification proof. Please run keel story record VDmdk1uib to attach proof for all pending ACs.这个错误不是来自模型的自我反思也不是来自人类的事后审查而是来自状态机基于规则的自动拒绝。AI代理的工作流因此必须适应它不能仅仅“断言”功能已实现而必须主动运行验证如单元测试、集成测试、API调用测试捕获输出如测试报告、日志截图、性能基准数据并使用keel story record命令将这些输出作为证据与特定的验收标准绑定。只有这样提交才能成功。实操心得证据的粒度与质量提示证据的质量直接决定审查效率。对于“用户能登录”这样的验收标准证据不应只是一句“测试通过”而应该是一个具体的测试结果文件如JUnit XML报告、一段关键的成功日志、或者一个API响应的截图。建议在项目初期就定义好各类验收标准所需的证据模板例如性能测试需附上perf输出UI变更需附上前后对比截图。这能让AI代理生成证据时更有针对性也让人工审查者一目了然。3.2 双队列拉动模型清晰分离“判断”与“执行”另一个常见的困境是“人在回路”的模糊性。到底哪些决策必须由人类做出哪些工作可以放心交给AIKeel通过双队列拉动模型和角色隔离给出了清晰的答案。系统维护两条独立的“工作流”管理通道存放需要人类判断和决策的工作项。例如等待评审的架构决策记录ADR、待验收的用户故事、需要规划的技术探索航行。交付通道存放可以被AI代理安全执行的工作项。例如实现已明确需求的故事、编写单元测试、修复已知的Bug。与之对应的是两种角色管理者只能从管理通道领取工作。他们永远不会被分配具体的编码任务。执行者只能从交付通道领取工作。他们永远不会被要求做架构决策。# 人类项目经理以“管理者”身份查看待办事项 $ keel next --role manager → accept: Story VE3IAG4jZ needs your verification (Management Lane) # AI开发代理以“执行者”身份查看待办事项 $ keel next --role operator → work: Story VDmdk1uib is ready to start (Delivery Lane)这种强制分离带来了管理上的清晰度。人类专注于需要创造力和经验的高价值判断而AI则高效处理定义明确的执行任务。两者不会越界减少了混淆和错误。3.3 高保真CLI输出为AI设计的“可读界面”对于纯人类使用的CLI工具输出信息可以相对简洁甚至有些模糊因为人类可以凭借经验和上下文进行推断和追问。但对于依赖CLI输出来理解系统状态并决定下一步行动的AI代理来说模糊的输出是致命的。一个模糊的列表、一个不完整的状态提示都可能导致AI代理对看板状态产生“幻觉”进而基于错误假设执行操作造成“漂移”。因此Keel特别强调CLI视觉保真度。像keel flow --scene dashboard这样的命令会渲染出一个信息丰富、布局清晰的终端仪表盘实时展示管理通道和交付通道的队列深度。各个故事、ADR的当前状态阻塞中、进行中、待验证。需要立即关注的阻塞条件如未决议的ADR。这种高保真输出不是UI的“锦上添花”而是保障AI代理工作流结构可靠性的必需品。它为模型提供了一个稳定、明确、无歧义的“世界状态”视图。4. 实战工作流从需求到上线的受控之旅让我们通过一个完整的虚拟场景看看Keel如何在实际项目中运作。假设我们正在开发一个微服务“用户服务”需要添加一个“用户头像上传”功能。4.1 第一步创建与规划人类主导产品负责人在代码库中创建一个新的“史诗”Markdown文件epics/avatar-upload.md描述业务目标。技术负责人针对“如何安全存储用户上传的文件”发起一个架构决策。他创建adrs/2024-05-20-use-s3-for-uploads.md状态为proposed。在Keel中这条ADR会关联到“用户服务”这个有界上下文。由于存在proposed状态的ADR关联到该上下文所有与该上下文相关的“交付通道”工作会自动被状态机阻塞。AI代理此时无法领取任何“用户服务”的开发任务。4.2 第二步决策与解封人类判断团队开会评审S3存储的ADR。评审通过后技术负责人执行keel adr accept 2024-05-20-use-s3-for-uploads。状态机更新ADR状态为accepted并解除对“用户服务”上下文的交付阻塞。工程师根据史诗拆解出具体的用户故事stories/VSF8a9j1-avatar-upload-api.md并定义清晰的验收标准如AC-01: POST /api/v1/users/{id}/avatar 接口接受图片文件返回201。AC-02: 上传的图片被存储到配置的S3存储桶中。AC-03: 图片大小超过2MB的请求被拒绝返回413。4.3 第三步AI代理执行与验证AI代理以operator角色运行keel next领取到故事VSF8a9j1。代理运行keel story start VSF8a9j1故事状态变为in-progress。代理开始编码。完成后它需要为每个AC提供证据针对AC-01和AC-03运行集成测试将测试通过的输出日志保存为文件执行keel story record VSF8a9j1 --ac AC-01 --proof ./test-ac01.log。针对AC-02编写一个脚本调用API后检查S3桶内是否确实生成了新文件将脚本和其执行成功的输出记录为证据。所有AC证据记录完毕后代理运行keel story submit VSF8a9j1。状态机检查通过故事状态变为needs-human-verification并自动移动到“管理通道”。4.4 第四步人类验证与闭环人类开发者以manager角色运行keel next看到待验证的故事VSF8a9j1。他审查代码变更并重点审查AI代理提交的证据。他可以看到AC-01的测试日志、AC-02的S3验证脚本输出。这些是具体的、可复现的证明而非AI的文本总结。如果满意他运行keel story accept VSF8a9j1故事关闭。如果不满意他运行keel story reject VSF8a9j1 --comment 需要补充文件类型校验的证据故事退回in-progress状态等待代理补充证据。在整个流程中状态机像铁面无私的裁判确保流程的每一步——从架构决策的遵守到验收证据的提供再到最终的人工把关——都得到严格执行。AI代理在“物理定律”的约束下自由发挥其编码能力。5. 高级特性与运维实践5.1 “医生”诊断持续对抗熵增在长期的、由多个AI代理并行参与的项目中即使有严格的规则也会不可避免地出现“结构漂移”。例如一个故事被创建但忘记关联到父史诗一个ADR所管辖的代码边界发生了演变但ADR文档没有更新一个航行技术探索结束后其产出文档没有正确链接到后续的设计或故事。Keel内置的keel doctor命令就是专门对抗这种熵增的工具。它会扫描整个代码库中的看板工件检查其结构一致性所有故事是否都正确关联了史诗所有验收标准是否都有SRS软件需求规格引用所有处于“活跃”状态的ADR其定义的上下文边界是否与当前代码结构一致是否存在“孤儿”工件没有任何入站或出站链接关键点在于keel doctor报告的不是“警告”而是状态机认定的“阻塞条件”。在Keel的最佳实践中AI代理在每次会话开始前必须首先运行keel doctor。如果发现任何漂移代理的首要任务是修复这些结构性问题然后才能开始新的工作。这确保了系统的“结构债务”能被即时发现和清偿知识图谱始终保持健康。5.2 场景与可视化掌握全局态势对于管理者或刚加入项目的成员来说快速理解项目全局状态至关重要。Keel的keel flow命令配合不同的--scene参数提供了强大的可视化能力。# 查看整体项目仪表盘 keel flow --scene dashboard # 聚焦于某个特定史诗下的所有故事进展 keel flow --scene epic E-ABC123 # 可视化某个有界上下文内ADR如何约束当前的工作项 keel flow --context user-service这些视图在终端中渲染提供了即时、无需打开浏览器或复杂工具的项目洞察。对于AI代理而言--scene dashboard的输出是其理解“现在该做什么”和“哪里被阻塞了”的主要信息来源。高保真的渲染确保了信息传递的准确性。5.3 集成与扩展嵌入现有CI/CD流水线Keel本身是CLI工具这使其能轻松集成到任何现有的开发环境和自动化流程中。Git Hooks可以在pre-commit钩子中运行轻量级的keel doctor检查防止将结构不完整的变更提交到仓库。CI/CD流水线在持续集成阶段可以运行keel verify命令针对某个Pull Request中的所有故事自动重新运行其关联的验收证据如测试确保新的合并不会破坏已有功能的验证链。与编排框架集成像LangChain、AutoGen这样的AI代理编排框架可以将Keel CLI命令封装成工具Tool供代理调用。代理的“大脑”负责规划和决策而Keel工具则负责与受治理的项目状态机进行安全、规范的交互。6. 常见问题与排查技巧实录在实际引入和运行Keel的过程中团队可能会遇到一些典型问题。以下是一些实录与解决方案。6.1 问题AI代理卡在“keel next返回空”可能原因1角色配置错误。检查代理使用的--role参数。一个配置为operator的代理在管理通道为空时自然拉取不到工作。可能原因2交付通道全局阻塞。运行keel flow --scene dashboard查看是否有proposed状态的ADR阻塞了相关上下文。这是最常见的原因。可能原因3故事依赖未满足。某些故事可能设置了前置依赖需要等待其他故事完成。排查命令# 检查看板全局状态和阻塞项 keel flow --scene dashboard # 检查代理关联的上下文是否有未决的ADR keel adr list --context your-context --state proposed6.2 问题keel story submit失败提示证据缺失但代理坚称已记录可能原因1证据文件路径错误。keel story record命令记录的路径是相对于当前工作目录的。如果代理在记录证据后工作目录发生了变更提交时状态机可能找不到证据文件。可能原因2证据未关联到正确的AC。确认--ac参数指定的是验收标准的唯一ID如AC-01而不是文字描述。可能原因3故事状态已变更。在代理记录证据的过程中是否有其他参与者人或代理修改了故事状态或AC列表排查命令# 查看该故事当前所有已记录的证据 keel story show story-id --proofs # 验证特定证据文件是否存在 keel story proof-verify story-id --ac ac-id实操心得证据文件管理提示建议为每个故事建立一个临时工作目录所有为该故事生成的证据测试报告、日志、截图都放在该目录下。使用绝对路径或相对于项目根目录的路径进行记录。在故事完成后可以清理此目录。这能有效避免因路径问题导致的证据丢失。6.3 问题keel doctor报告大量“孤儿节点”或“缺失链接”可能原因手工创建或修改了工件文件。Keel严重依赖文件间的YAML元数据进行链接如故事中的epic: E-ABC123。如果手工创建Markdown文件时格式错误或修改了引用ID就会导致链接断裂。解决方案尽量避免手动编辑工件文件。使用Keel CLI命令来创建和更新如keel story create,keel epic link。如果已经损坏可以使用keel doctor --fix如果支持进行自动修复尝试或者手动检查并修正YAML元数据中的引用字段。预防措施将Keel工件的Markdown文件模板纳入项目代码规范并对团队进行培训。6.4 问题如何管理大型项目中的大量ADR挑战随着项目演进ADR会积累有些可能已过时但状态仍是accepted这会持续对关联上下文产生约束。最佳实践定期审计每个季度或主要版本发布前运行keel adr list --state accepted逐一评审其是否仍适用。设立生命周期可以为ADR引入superseded被取代或deprecated已弃用状态。Keel状态机可以配置为只尊重accepted状态的ADR的阻塞效应。细化上下文创建更细粒度的有界上下文让ADR的约束范围更精确避免“一刀切”的阻塞。7. 引入Keel的路径与团队文化适配将Keel这样的治理层引入团队不仅仅是引入一个工具更是引入一种新的工作文化和纪律。以下是一些循序渐进的建议。阶段一试点与熟悉选择一个小型、边界清晰的内部工具或微服务项目作为试点。团队先以纯人工方式严格按照Keel定义的工作流创建ADR、写故事、附证据、提交验证进行2-3个迭代周期的开发。目的是让团队成员熟悉“证据驱动”和“状态机强制执行”的思维模式理解CLI命令的使用。阶段二引入AI代理辅助执行在团队熟悉流程后引入AI代理如基于GPT-Engineer、Claude Code等的自定义代理将其角色限定为“执行者”。从最简单的任务开始如“为现有API添加单元测试”、“修复静态代码分析指出的明确缺陷”。人类专注于需求拆分、架构决策管理通道工作和最终验证。观察代理与状态机的交互调整提示词以确保代理能正确理解和使用Keel命令。阶段三扩大范围与流程固化当团队对“人机协作”模式感到舒适后逐步扩大AI代理的职责范围覆盖更多的“交付通道”工作。同时将Keel的流程固化到团队的Definition of Done中并将keel doctor和keel verify集成到CI/CD管道成为质量门禁的一部分。文化转变的关键从“信任人/AI”到“信任流程”团队需要建立起对状态机规则的尊重。规则不合理可以讨论修改但一旦确立就必须通过状态机来执行。证据文化“完成”不再是一个主观判断而是客观证据的集合。代码评审的重点从“这段代码看起来对不对”部分转移到“这些证据是否充分证明了需求被满足”。清晰的责任分离管理者人类负责决策和判断执行者AI/人类负责在明确规则下的高效实施。两者各司其职通过状态机无缝协作。Keel所代表的“宿主层”思想为AI代理进入软件工程核心流程提供了一条可控、可审计、可持续的路径。它没有试图创造一个全知全能、完全自主的AI开发者而是聪明地构建了一个“物理世界”让强大但有时不可预测的AI能力能够在人类设定的轨道上安全、可靠地奔跑。这根“缰绳”不是束缚而是规模化、工业化应用AI辅助开发的基石。它最终改变的不是AI的能力上限而是我们与AI协作的信任下限。
Keel：为AI驱动的软件开发生命周期套上“缰绳”的宿主层实践
1. 项目概述为什么我们需要为AI驱动的软件开发生命周期套上“缰绳”在AI代理Agent技术席卷软件工程领域的今天我们谈论的焦点往往集中在两个核心组件上大语言模型LLM和编排框架Harness。模型负责思考、决策和生成代码而框架则负责协调工具调用、管理上下文和执行多步骤工作流。这两者结合确实带来了前所未有的自动化能力。然而一个关键的问题也随之浮现当我们将开发任务交给一个自主运行的AI代理时我们如何确保它是在一个可控、可审计、符合既定规则和流程的“物理世界”中工作而不是在一个可以随意发挥、缺乏约束的“想象空间”里横冲直撞这就是Keel项目试图回答的核心问题。它不是一个替代模型或框架的新工具而是一个被长期忽视的、至关重要的第三层宿主层Host Layer。你可以把它想象成软件开发团队的“物理定律”或“交通规则”。无论执行者是人类工程师还是AI代理这套规则都同样适用并且被一个持久化的状态机强制执行。Keel将自己定位为这个宿主层的一个具体实现——一个命令行状态机它定义了什么是“有效的工作”什么是“完成的证据”以及“完成”本身意味着什么。它不是限制模型能思考什么而是保证系统会强制执行什么。这就像给一匹能力强大的骏马套上缰绳Leash不是为了束缚它的奔跑而是为了确保它始终奔跑在正确的赛道上并能在需要时被安全地引导。2. 核心设计理念CLI状态机作为统一的治理层2.1 从“上下文信任”到“结构信任”的范式转变在传统的“模型框架”模式中我们依赖的是一种“上下文信任”。我们通过精心设计的提示词Prompt告诉模型我们的规则和期望并希望模型在本次会话的上下文窗口内记住并遵守它们。然而这种信任是脆弱且临时的。模型可能会“忘记”或误解提示词中的约束当会话重启、上下文重置后所有的规则都需要重新“协商”。人类不得不反复检查AI的工作以确保它没有偏离几天前甚至几小时前设定的架构决策或完成标准。这种模式将人类变成了一个永不停歇的“一致性检查器”成本高昂且不可持续。Keel引入的“结构信任”则完全不同。它将规则和约束从易变的提示词和短暂的会话记忆中抽离出来固化到一个持久化的、由状态机管理的系统中。规则不再是建议而是“物理定律”。例如一条处于“提议中”状态的架构决策记录ADR会像一堵真实的墙一样阻止任何涉及该架构边界的工作被启动——无论执行者是谁。这种阻塞不是通过模型“想起来要检查ADR”来实现的而是状态机在底层直接拒绝了工作项的状态变迁请求。信任的对象从模型的“自觉性”转移到了状态机“不可违背的规则”上。2.2 统一交互界面人与代理共用同一套“物理接口”Keel最精妙的设计之一是它强制所有参与者——无论是人类开发者还是AI代理——都通过完全相同的命令行接口CLI与系统交互。这套CLI就是状态机的外在表现。它定义了一系列命令每个命令都对应着状态机的一个合法状态变迁。# 无论是人还是AI代理都使用同样的命令序列 keel turn # 查看看板整体状态方向 keel next --role operator # 以“执行者”角色领取下一个可执行任务 keel story start id # 开始处理一个用户故事状态变为“进行中” keel story record id # 为故事的验收条件附加可验证的证据 keel story submit id # 提交故事触发关卡检查所有验收条件必须有证据这个设计消除了“侧门”。AI代理没有特权路径它必须像人类一样遵守相同的流程撞击相同的关卡提供相同格式的证据。如果一个代理试图跳过“提交证据”的步骤直接标记故事完成它会收到和人类操作者一模一样的、来自状态机的硬性拒绝错误。这种设计极大地简化了系统的复杂性和可理解性因为治理逻辑只有一套并且对所有人透明。2.3 文件即真相Git即审计日志为了实现持久化和可审计性Keel将所有看板状态用户故事、史诗、ADR、航行等都存储为带有YAML前置元数据的Markdown文件。没有隐藏的数据库没有可能不同步的后台守护进程也没有需要查询的独立服务。这种选择带来了几个根本性优势真相唯一源系统的当前状态完全由文件系统中的文件内容定义。要了解状态只需读取文件。不可变的审计追踪Git提交历史成为了系统所有变更的完整、不可篡改的审计日志。当AI代理提交一个故事时证据文件和生命周期状态变更会作为一次提交的一部分被记录到代码库中。你可以通过git log追溯任何一个工作项从创建到关闭的完整历程包括谁或哪个代理在什么时候做了什么附带了什么证据。可移植性与简单性整个系统的状态可以像任何代码库一样被克隆、分支、合并和回滚。部署和备份变得极其简单。知识图谱可视化基于文件间的引用关系如故事链接到史诗ADR关联到有界上下文可以动态生成并可视化整个项目的“工件网络”。一个缺失的链接直接意味着证据的缺失一个孤立的节点则代表着一个被遗忘的工件。这为项目健康度提供了结构化的洞察。3. 核心机制深度解析3.1 验证驱动开发用证据替代断言在AI辅助开发中一个常见的失败模式是“自信的错误答案”。模型声称它完成了任务编排框架就相信并记录了完成状态。但由于缺乏结构化的要求往往没有人去实际验证证据是否存在或有效。Keel通过其核心机制——验证驱动开发——在状态机层面解决了这个问题。每个用户故事都包含一组明确的验收标准。故事从“进行中”状态变迁到“待人工验证”状态即提交时状态机会执行一个硬性关卡检查每一项验收标准都必须有已记录的、可验证的证明文件与之关联。# 假设故事ID为VDmdk1uib它有两项验收标准AC-01和AC-02 # AI代理完成了代码编写但只记录了AC-01的测试通过日志 $ keel story submit VDmdk1uib Error: Transition blocked by gate all-acs-verified. - Acceptance criterion AC-02 has no recorded verification proof. Please run keel story record VDmdk1uib to attach proof for all pending ACs.这个错误不是来自模型的自我反思也不是来自人类的事后审查而是来自状态机基于规则的自动拒绝。AI代理的工作流因此必须适应它不能仅仅“断言”功能已实现而必须主动运行验证如单元测试、集成测试、API调用测试捕获输出如测试报告、日志截图、性能基准数据并使用keel story record命令将这些输出作为证据与特定的验收标准绑定。只有这样提交才能成功。实操心得证据的粒度与质量提示证据的质量直接决定审查效率。对于“用户能登录”这样的验收标准证据不应只是一句“测试通过”而应该是一个具体的测试结果文件如JUnit XML报告、一段关键的成功日志、或者一个API响应的截图。建议在项目初期就定义好各类验收标准所需的证据模板例如性能测试需附上perf输出UI变更需附上前后对比截图。这能让AI代理生成证据时更有针对性也让人工审查者一目了然。3.2 双队列拉动模型清晰分离“判断”与“执行”另一个常见的困境是“人在回路”的模糊性。到底哪些决策必须由人类做出哪些工作可以放心交给AIKeel通过双队列拉动模型和角色隔离给出了清晰的答案。系统维护两条独立的“工作流”管理通道存放需要人类判断和决策的工作项。例如等待评审的架构决策记录ADR、待验收的用户故事、需要规划的技术探索航行。交付通道存放可以被AI代理安全执行的工作项。例如实现已明确需求的故事、编写单元测试、修复已知的Bug。与之对应的是两种角色管理者只能从管理通道领取工作。他们永远不会被分配具体的编码任务。执行者只能从交付通道领取工作。他们永远不会被要求做架构决策。# 人类项目经理以“管理者”身份查看待办事项 $ keel next --role manager → accept: Story VE3IAG4jZ needs your verification (Management Lane) # AI开发代理以“执行者”身份查看待办事项 $ keel next --role operator → work: Story VDmdk1uib is ready to start (Delivery Lane)这种强制分离带来了管理上的清晰度。人类专注于需要创造力和经验的高价值判断而AI则高效处理定义明确的执行任务。两者不会越界减少了混淆和错误。3.3 高保真CLI输出为AI设计的“可读界面”对于纯人类使用的CLI工具输出信息可以相对简洁甚至有些模糊因为人类可以凭借经验和上下文进行推断和追问。但对于依赖CLI输出来理解系统状态并决定下一步行动的AI代理来说模糊的输出是致命的。一个模糊的列表、一个不完整的状态提示都可能导致AI代理对看板状态产生“幻觉”进而基于错误假设执行操作造成“漂移”。因此Keel特别强调CLI视觉保真度。像keel flow --scene dashboard这样的命令会渲染出一个信息丰富、布局清晰的终端仪表盘实时展示管理通道和交付通道的队列深度。各个故事、ADR的当前状态阻塞中、进行中、待验证。需要立即关注的阻塞条件如未决议的ADR。这种高保真输出不是UI的“锦上添花”而是保障AI代理工作流结构可靠性的必需品。它为模型提供了一个稳定、明确、无歧义的“世界状态”视图。4. 实战工作流从需求到上线的受控之旅让我们通过一个完整的虚拟场景看看Keel如何在实际项目中运作。假设我们正在开发一个微服务“用户服务”需要添加一个“用户头像上传”功能。4.1 第一步创建与规划人类主导产品负责人在代码库中创建一个新的“史诗”Markdown文件epics/avatar-upload.md描述业务目标。技术负责人针对“如何安全存储用户上传的文件”发起一个架构决策。他创建adrs/2024-05-20-use-s3-for-uploads.md状态为proposed。在Keel中这条ADR会关联到“用户服务”这个有界上下文。由于存在proposed状态的ADR关联到该上下文所有与该上下文相关的“交付通道”工作会自动被状态机阻塞。AI代理此时无法领取任何“用户服务”的开发任务。4.2 第二步决策与解封人类判断团队开会评审S3存储的ADR。评审通过后技术负责人执行keel adr accept 2024-05-20-use-s3-for-uploads。状态机更新ADR状态为accepted并解除对“用户服务”上下文的交付阻塞。工程师根据史诗拆解出具体的用户故事stories/VSF8a9j1-avatar-upload-api.md并定义清晰的验收标准如AC-01: POST /api/v1/users/{id}/avatar 接口接受图片文件返回201。AC-02: 上传的图片被存储到配置的S3存储桶中。AC-03: 图片大小超过2MB的请求被拒绝返回413。4.3 第三步AI代理执行与验证AI代理以operator角色运行keel next领取到故事VSF8a9j1。代理运行keel story start VSF8a9j1故事状态变为in-progress。代理开始编码。完成后它需要为每个AC提供证据针对AC-01和AC-03运行集成测试将测试通过的输出日志保存为文件执行keel story record VSF8a9j1 --ac AC-01 --proof ./test-ac01.log。针对AC-02编写一个脚本调用API后检查S3桶内是否确实生成了新文件将脚本和其执行成功的输出记录为证据。所有AC证据记录完毕后代理运行keel story submit VSF8a9j1。状态机检查通过故事状态变为needs-human-verification并自动移动到“管理通道”。4.4 第四步人类验证与闭环人类开发者以manager角色运行keel next看到待验证的故事VSF8a9j1。他审查代码变更并重点审查AI代理提交的证据。他可以看到AC-01的测试日志、AC-02的S3验证脚本输出。这些是具体的、可复现的证明而非AI的文本总结。如果满意他运行keel story accept VSF8a9j1故事关闭。如果不满意他运行keel story reject VSF8a9j1 --comment 需要补充文件类型校验的证据故事退回in-progress状态等待代理补充证据。在整个流程中状态机像铁面无私的裁判确保流程的每一步——从架构决策的遵守到验收证据的提供再到最终的人工把关——都得到严格执行。AI代理在“物理定律”的约束下自由发挥其编码能力。5. 高级特性与运维实践5.1 “医生”诊断持续对抗熵增在长期的、由多个AI代理并行参与的项目中即使有严格的规则也会不可避免地出现“结构漂移”。例如一个故事被创建但忘记关联到父史诗一个ADR所管辖的代码边界发生了演变但ADR文档没有更新一个航行技术探索结束后其产出文档没有正确链接到后续的设计或故事。Keel内置的keel doctor命令就是专门对抗这种熵增的工具。它会扫描整个代码库中的看板工件检查其结构一致性所有故事是否都正确关联了史诗所有验收标准是否都有SRS软件需求规格引用所有处于“活跃”状态的ADR其定义的上下文边界是否与当前代码结构一致是否存在“孤儿”工件没有任何入站或出站链接关键点在于keel doctor报告的不是“警告”而是状态机认定的“阻塞条件”。在Keel的最佳实践中AI代理在每次会话开始前必须首先运行keel doctor。如果发现任何漂移代理的首要任务是修复这些结构性问题然后才能开始新的工作。这确保了系统的“结构债务”能被即时发现和清偿知识图谱始终保持健康。5.2 场景与可视化掌握全局态势对于管理者或刚加入项目的成员来说快速理解项目全局状态至关重要。Keel的keel flow命令配合不同的--scene参数提供了强大的可视化能力。# 查看整体项目仪表盘 keel flow --scene dashboard # 聚焦于某个特定史诗下的所有故事进展 keel flow --scene epic E-ABC123 # 可视化某个有界上下文内ADR如何约束当前的工作项 keel flow --context user-service这些视图在终端中渲染提供了即时、无需打开浏览器或复杂工具的项目洞察。对于AI代理而言--scene dashboard的输出是其理解“现在该做什么”和“哪里被阻塞了”的主要信息来源。高保真的渲染确保了信息传递的准确性。5.3 集成与扩展嵌入现有CI/CD流水线Keel本身是CLI工具这使其能轻松集成到任何现有的开发环境和自动化流程中。Git Hooks可以在pre-commit钩子中运行轻量级的keel doctor检查防止将结构不完整的变更提交到仓库。CI/CD流水线在持续集成阶段可以运行keel verify命令针对某个Pull Request中的所有故事自动重新运行其关联的验收证据如测试确保新的合并不会破坏已有功能的验证链。与编排框架集成像LangChain、AutoGen这样的AI代理编排框架可以将Keel CLI命令封装成工具Tool供代理调用。代理的“大脑”负责规划和决策而Keel工具则负责与受治理的项目状态机进行安全、规范的交互。6. 常见问题与排查技巧实录在实际引入和运行Keel的过程中团队可能会遇到一些典型问题。以下是一些实录与解决方案。6.1 问题AI代理卡在“keel next返回空”可能原因1角色配置错误。检查代理使用的--role参数。一个配置为operator的代理在管理通道为空时自然拉取不到工作。可能原因2交付通道全局阻塞。运行keel flow --scene dashboard查看是否有proposed状态的ADR阻塞了相关上下文。这是最常见的原因。可能原因3故事依赖未满足。某些故事可能设置了前置依赖需要等待其他故事完成。排查命令# 检查看板全局状态和阻塞项 keel flow --scene dashboard # 检查代理关联的上下文是否有未决的ADR keel adr list --context your-context --state proposed6.2 问题keel story submit失败提示证据缺失但代理坚称已记录可能原因1证据文件路径错误。keel story record命令记录的路径是相对于当前工作目录的。如果代理在记录证据后工作目录发生了变更提交时状态机可能找不到证据文件。可能原因2证据未关联到正确的AC。确认--ac参数指定的是验收标准的唯一ID如AC-01而不是文字描述。可能原因3故事状态已变更。在代理记录证据的过程中是否有其他参与者人或代理修改了故事状态或AC列表排查命令# 查看该故事当前所有已记录的证据 keel story show story-id --proofs # 验证特定证据文件是否存在 keel story proof-verify story-id --ac ac-id实操心得证据文件管理提示建议为每个故事建立一个临时工作目录所有为该故事生成的证据测试报告、日志、截图都放在该目录下。使用绝对路径或相对于项目根目录的路径进行记录。在故事完成后可以清理此目录。这能有效避免因路径问题导致的证据丢失。6.3 问题keel doctor报告大量“孤儿节点”或“缺失链接”可能原因手工创建或修改了工件文件。Keel严重依赖文件间的YAML元数据进行链接如故事中的epic: E-ABC123。如果手工创建Markdown文件时格式错误或修改了引用ID就会导致链接断裂。解决方案尽量避免手动编辑工件文件。使用Keel CLI命令来创建和更新如keel story create,keel epic link。如果已经损坏可以使用keel doctor --fix如果支持进行自动修复尝试或者手动检查并修正YAML元数据中的引用字段。预防措施将Keel工件的Markdown文件模板纳入项目代码规范并对团队进行培训。6.4 问题如何管理大型项目中的大量ADR挑战随着项目演进ADR会积累有些可能已过时但状态仍是accepted这会持续对关联上下文产生约束。最佳实践定期审计每个季度或主要版本发布前运行keel adr list --state accepted逐一评审其是否仍适用。设立生命周期可以为ADR引入superseded被取代或deprecated已弃用状态。Keel状态机可以配置为只尊重accepted状态的ADR的阻塞效应。细化上下文创建更细粒度的有界上下文让ADR的约束范围更精确避免“一刀切”的阻塞。7. 引入Keel的路径与团队文化适配将Keel这样的治理层引入团队不仅仅是引入一个工具更是引入一种新的工作文化和纪律。以下是一些循序渐进的建议。阶段一试点与熟悉选择一个小型、边界清晰的内部工具或微服务项目作为试点。团队先以纯人工方式严格按照Keel定义的工作流创建ADR、写故事、附证据、提交验证进行2-3个迭代周期的开发。目的是让团队成员熟悉“证据驱动”和“状态机强制执行”的思维模式理解CLI命令的使用。阶段二引入AI代理辅助执行在团队熟悉流程后引入AI代理如基于GPT-Engineer、Claude Code等的自定义代理将其角色限定为“执行者”。从最简单的任务开始如“为现有API添加单元测试”、“修复静态代码分析指出的明确缺陷”。人类专注于需求拆分、架构决策管理通道工作和最终验证。观察代理与状态机的交互调整提示词以确保代理能正确理解和使用Keel命令。阶段三扩大范围与流程固化当团队对“人机协作”模式感到舒适后逐步扩大AI代理的职责范围覆盖更多的“交付通道”工作。同时将Keel的流程固化到团队的Definition of Done中并将keel doctor和keel verify集成到CI/CD管道成为质量门禁的一部分。文化转变的关键从“信任人/AI”到“信任流程”团队需要建立起对状态机规则的尊重。规则不合理可以讨论修改但一旦确立就必须通过状态机来执行。证据文化“完成”不再是一个主观判断而是客观证据的集合。代码评审的重点从“这段代码看起来对不对”部分转移到“这些证据是否充分证明了需求被满足”。清晰的责任分离管理者人类负责决策和判断执行者AI/人类负责在明确规则下的高效实施。两者各司其职通过状态机无缝协作。Keel所代表的“宿主层”思想为AI代理进入软件工程核心流程提供了一条可控、可审计、可持续的路径。它没有试图创造一个全知全能、完全自主的AI开发者而是聪明地构建了一个“物理世界”让强大但有时不可预测的AI能力能够在人类设定的轨道上安全、可靠地奔跑。这根“缰绳”不是束缚而是规模化、工业化应用AI辅助开发的基石。它最终改变的不是AI的能力上限而是我们与AI协作的信任下限。
