kode:harness：统一团队AI编码方向的工程框架

1. 项目概述kode:harness一个为团队AI编码对齐方向而生的工程框架如果你在一个团队里发现每个开发者用AI助手写代码时项目就像被几匹脱缰的野马往不同方向拉扯那么kode:harness就是那套统一的缰绳和导航系统。这不是另一个教你如何写提示词的AI工具而是一个基于“缰绳工程”理念构建的、企业级的、多开发者AI辅助开发方向管理框架。它的核心目标极其明确确保团队中每一位开发者的AI编码会话都朝着同一个项目方向前进。想象一下这个场景开发者A正在用AI重构代码库目标是微服务化而隔壁的开发者B他的AI助手却在加固现有的单体架构。在没有统一方向管理的情况下每个AI都在基于自己会话的局部上下文“优化”代码结果就是项目架构被无声地撕裂技术债务以指数级累积。kode:harness通过一套轻量级约25个文件17K tokens、零依赖的Markdown文件系统将项目的目标、非目标、关键决策和当前状态固化下来成为所有AI会话必须遵守的“宪法”。无论你用的是VS Code Copilot、Cursor、Claude Code还是其他支持的IDE你的AI都会基于同一套上下文工作从根本上解决了多开发者环境下的AI方向漂移问题。2. 核心设计理念从个人“缰绳”到团队“缰绳工程”传统的AI“缰绳”模式比如BMAD、gstack等框架本质上是为个人开发者服务的。它们通过结构化的提示词文件来引导单个AI代理的行为关注的是“AI在做什么”。而kode:harness所做的是将这个概念升维演变为一种面向多开发者团队的“缰绳工程”。它的焦点从“做什么”转移到了“去哪里”即项目的战略方向管理。这种转变带来了几个根本性的差异。首先是状态管理的分离。在团队模式下kode:harness将状态文件分为两类共享状态如项目简报、功能清单、依赖关系图和个人状态如项目进度、失败模式。共享状态通过Git进行版本控制确保团队信息同步个人状态则存放在.harness/目录下并被Git忽略避免了开发者之间的进度冲突。其次它引入了一套团队协作规则例如“预拉取协议”——在每次AI会话开始前强制拉取最新的共享状态文件确保不会基于过时的方向进行开发。还有“方向变更锁”任何对项目目标、技术栈或范围的修改都必须通过专门的pivot技能来原子化地更新所有相关状态文件并记录决策理由防止悄无声息的方向偏离。这套设计背后的逻辑是承认一个现实在团队中AI带来的效率提升与方向混乱的风险是并存的。kode:harness通过工程化的手段将风险管控起来让效率提升得以安全地规模化。它不试图控制AI生成的每一行代码而是为AI的决策划定一个清晰的边界和上下文让创造力在正确的轨道上发挥。2.1 状态文件系统项目的集体记忆与导航仪kode:harness的核心是一套由5个Markdown文件构成的状态文件系统它们共同构成了项目的“集体记忆”和AI的“导航仪”。理解每个文件的作用是有效使用该框架的关键。project-brief.md项目简报这是项目的“宪法”和“为什么”文档。它定义了项目的愿景、核心目标、明确的非目标以及最重要的“决策日志”。决策日志记录了所有关键的技术和产品决策及其背后的理由。当AI接到一个编码任务时Direction Guard方向守卫机制会首先检查该任务是否与project-brief.md中的目标一致是否触犯了非目标或是否与已有的决策相悖。这从根本上防止了AI做出与项目既定战略相冲突的修改。project-state.md项目状态这是项目的“在哪里”文档。它跟踪当前的冲刺周期、进行中的用户故事及其进度。在团队模式下这个文件是个人化的存放在.harness/目录下。它确保了每个开发者都能清晰地知道自己当前的工作上下文而AI也能基于准确的进度信息提供帮助例如避免去修改一个已经完成的故事相关的代码。features.md功能清单这是一个动态更新的功能注册表回答了“有什么”的问题。它记录了项目中已实现的所有功能模块、它们的简要描述和入口点。这对于大型项目或新加入的开发者及其AI至关重要能快速了解系统能力避免重复造轮子或误解现有功能。dependency-map.md依赖关系图这是项目的“如何”文档以文本形式描述了模块之间的依赖关系。当需要进行影响范围分析时无论是开发者还是AI都可以参考此文件来评估一个修改的“爆炸半径”避免因改动一个核心模块而引发不可预知的连锁反应。failure-patterns.md失败模式这是项目的“警惕”文档记录了项目特有的、反复出现的错误模式或陷阱。例如“在本项目中调用X服务前必须手动初始化Y客户端否则会静默失败”。这个文件让AI能够从项目历史中学习避免重复踩坑。在团队模式下个人的失败模式可以被提升到共享的failure-patterns.md中实现团队间的经验共享。这套文件系统之所以设计得如此轻量约17K tokens是为了确保它们能够被大多数LLM的上下文窗口完整容纳即使是小模型也能有效工作。它们不是一次性写成的文档而是通过bootstrap技能初始化并在整个开发周期中由各种技能和代理动态维护的活文档。2.2 技能与代理标准化的操作流程与角色扮演如果说状态文件是知识库那么技能和代理就是操作手册和执行者。kode:harness将常见的开发工作流封装成可复用的“技能”并为不同的任务场景定义了专门的“代理”角色。技能是一步步的、按需执行的操作流程。例如bootstrap项目初始化技能扫描代码库并自动填充所有5个状态文件。learn会话结束技能捕获本次会话的教训、更新项目状态、检测方向漂移。pivot方向变更技能当项目目标、技术或范围发生变化时原子化地更新所有状态文件。investigate系统化调试技能遵循“证据收集 → 问题定界 → 实施修复 → 验证结果”的四阶段流程。代理则是具有特定职责的AI角色扮演模板。它们内嵌了执行特定任务所需的上下文和行为准则planner规划师负责功能规划、依赖分析并执行“方向对齐”检查目标/非目标/决策核对。它有一个“确认优先”关卡在没有得到开发者明确批准前不会继续。reviewer审查员执行代码审查并审计状态文件的更新情况确保代码变更与项目文档同步。sprint-manager冲刺经理管理冲刺/故事状态防止范围蔓延并推荐下一步行动。它采用“波浪式节奏”在几轮实现之间穿插运行测试。architect架构师作为设计审查关卡验证结构性变更是否符合项目方向和模块边界。这种设计的精妙之处在于它将最佳实践和团队规范编码到了可执行的流程中。开发者不需要记住所有规则只需要在适当的时机调用对应的技能或切换至对应的代理AI就会在预设的框架内工作。例如在代码审查时reviewer代理会自动检查“模拟同步”修改接口必须同步更新模拟数据、“类型检查”调用构造器前必须阅读源码等“铁律”是否被遵守。3. 完整工作流与五大管道实战kode:harness不是一个孤立的工具它定义了一套完整的工作流并通过“导航分发器”和“五大管道”来引导开发者。导航分发器是一个始终激活的规则集约136行它位于每个IDE配置的核心位置负责在会话开始时提供指引、列出可用工作流和状态文件。而五大管道则针对不同的开发场景提供了明确的、带导航提示的执行路径。3.1 核心工作流从启动到收尾一个标准的开发循环遵循以下流程bootstrap → planner → [编码] → reviewer → sprint-manager → learn。启动运行npx kodevibe/harness init初始化项目然后让AI执行bootstrap技能。这是最关键的一步AI会扫描你的代码库并通过一系列提问来帮助你定义项目目标、非目标并自动生成初始的状态文件。没有这一步后续的所有方向守卫都将缺乏上下文。规划开始一个新功能或任务时切换到planner代理。它会基于project-brief.md进行方向对齐检查并将功能分解为依赖关系有序的实现任务。它会输出一个计划并要求你确认这就是“确认优先”关卡。编码在规划获得批准后AI会基于分解的任务进行编码。此时方向守卫在后台持续工作确保每一行代码的意图都与项目目标一致。审查编码完成后切换到reviewer代理进行代码审查。它不仅仅看代码质量还会审计相关的状态文件是否已按要求更新。例如如果新增了一个模块它会检查dependency-map.md和features.md是否已同步更新。状态管理sprint-manager代理会更新project-state.md中的任务进度。它采用“波浪式节奏”建议在实现几个小功能后运行一次测试保持节奏稳健。学习在会话结束时运行learn技能。它会总结本次会话的收获将遇到的陷阱记录到failure-patterns.md并检查是否有方向漂移的迹象。3.2 五大管道应对不同场景的导航图kode:harness将上述工作流具体化为五个清晰的管道每个管道都有明确的入口和下一步提示。 新功能开发管道当你开始一个全新的功能时使用。流程bootstrap(如果需要) →planner→sprint-manager→[编码]→reviewer→learn导航提示示例“规划已完成。接下来请让AI开始实现‘用户登录模块’。提示词示例‘基于刚才的规划开始实现用户登录模块的API层。’” 继续开发管道当你继续处理一个进行中的任务时使用。流程sprint-manager→[编码]→reviewer→learn导航提示示例“已加载当前故事‘优化查询性能’的进度。接下来请继续实现索引优化部分。提示词示例‘继续优化User表的查询添加复合索引。’” 缺陷修复管道当需要调试和修复Bug时使用。流程investigate→[修复]→reviewer→learn导航提示示例“调查阶段完成根本原因是空指针异常。接下来请实施修复。提示词示例‘根据调查结果修复UserService第45行的空指针检查。’” 方向变更管道当项目目标、技术栈或范围发生重大变化时使用。流程pivot→planner→sprint-manager→[编码]→reviewer→learn导航提示示例“方向变更从Monolith转向微服务已记录于决策日志。接下来请重新规划‘订单模块’的拆分。提示词示例‘基于新的微服务方向规划订单模块的独立服务拆分方案。’” 外部规划驱动管道当团队使用外部工具如产品需求文档、架构设计工具进行规划时使用。这是kode:harness一个强大的集成功能。流程bootstrap(crew) →planner→sprint-manager→[编码]→reviewer→learn实操细节将外部规划文档如PRD、架构图、ARB检查表放入项目的docs/crew/、docs/PM/等目录。运行bootstrap时AI会自动检测这些“船员产出物”并生成一个“产出物索引”和“验证跟踪器”。索引会映射每个文档的关键内容跟踪器则确保用户故事覆盖了规划中的关键绩效指标和功能需求。原始文档不会被修改kode:harness只是读取并建立引用关系。每个管道的每一步结束时AI都会给出一个明确的“ 导航”区块告诉你下一步该做什么甚至给出可复制的提示词示例。这种“导航分发器”的设计极大地降低了使用门槛让开发者无需记忆复杂的工作流。4. 团队模式深度解析与“铁律”执行对于企业团队而言solo模式下的工具直接套用往往会引发冲突。kode:harness的团队模式--teamflag正是为此而生它通过一系列精妙的规则和目录结构设计在保持个体灵活性的同时维护团队方向的一致性。4.1 目录结构与状态分离团队模式的核心是状态分离共享目录 (docs/): 存放project-brief.md,features.md,dependency-map.md。这些文件通过Git进行版本控制是所有团队成员AI会话的单一事实来源。任何方向性的修改都必须通过pivot技能并经过代码审查确保变更被所有人知晓和同意。个人目录 (.harness/): 存放project-state.md,failure-patterns.md以及代理的会话记忆。这个目录被.gitignore忽略。这意味着每个开发者可以自由地跟踪自己的任务进度记录自己遇到的坑而不会与其他人的文件产生合并冲突。4.2 六大团队协作规则团队模式内置了六条协作规则这些规则被编码在技能和代理的行为中预拉取协议在每次AI会话开始前planner或sprint-manager代理会提示开发者先执行git pull确保本地共享状态文件是最新的。这防止了基于过时方向进行开发。所有者标记在dependency-map.md中可以为关键模块标记“所有者”个人或团队。当AI试图修改一个非其所有者负责的模块时reviewer会发出警告建议先进行沟通防止意外的跨团队覆盖。共享文件只读/仅追加原则对于project-brief.md决策日志除外和features.mdAI在常规编码任务中将其视为只读。更新必须通过特定的技能如pivot、learn进行。failure-patterns.md的共享部分则采用仅追加模式只添加新的失败模式不删除或修改旧条目保留历史。方向变更锁任何对共享状态文件尤其是目标和决策的修改必须通过pivot技能完成。该技能会原子化地更新所有受影响的状态文件并在project-brief.md的决策日志中记录变更原因、日期和责任人。这确保了方向变更是一个显式的、可追溯的决策过程。失败模式提升当个人.harness/failure-patterns.md中的某个失败模式被多次遇到或被认为具有普遍性时开发者可以通过learn技能的建议将其“提升”到共享的docs/failure-patterns.md中使整个团队受益。合并冲突解决SOP如果共享状态文件在Git合并时发生冲突kode:harness建议的标准操作流程是1) 暂停AI编码2) 人工解决冲突重点理解冲突内容背后的方向分歧3) 运行harness validate命令验证状态文件完整性4) 必要时运行pivot技能来调和并正式记录决策。4.3 八大“铁律”嵌入工作流的代码质量红线除了团队规则kode:harness还定义了八条贯穿所有工作的“铁律”它们被硬编码到reviewer等代理和技能中是项目质量的底线。模拟同步修改接口后必须在同一次提交中更新对应的模拟数据或测试桩。reviewer和test-integrity技能会检查这一点防止接口与测试不同步。类型检查在调用构造函数或访问复杂对象属性前必须重新阅读源代码确认其类型和结构。AI不能仅凭记忆或推断来编码这减少了因误解代码库而引入的错误。范围合规严格保持在当前用户故事的定义范围内工作。如果需要修改范围外的文件必须先行报告并获得批准。sprint-manager会跟踪故事范围reviewer会检查变更集是否越界。安全第一绝对禁止在代码或提交中包含凭证、密码或API密钥。security-checklist技能和reviewer代理会对此进行扫描。三次失败停止如果同一种方法连续失败三次AI必须停止尝试并报告给开发者建议更换方法。这防止了AI在死胡同里无限循环。依赖图更新创建或修改一个模块后必须在同一次提交中更新dependency-map.md。reviewer和learn技能会强制执行这一点。功能注册实现一个新功能后必须在同一次提交中将其注册到features.md。同样是reviewer和learn来保障。会话交接每次开发会话结束时必须通过learn技能更新project-state.md中的“快速摘要”记录本次完成了什么、遇到了什么问题。这为后续会话提供了连续性。这些“铁律”不是建议而是被工具强制执行的规则。它们将许多容易被忽视的工程最佳实践变成了开发流程中自动化的检查点。5. 常见问题、排查技巧与实战心得在实际引入和使用kode:harness的过程中你可能会遇到一些典型问题。以下是一些排查思路和从实战中总结的经验。5.1 初始化与引导阶段问题运行bootstrap后状态文件内容看起来很泛泛没有准确反映我的项目。排查bootstrap技能依赖于AI对现有代码库的分析和理解。如果项目非常新或结构特殊AI可能无法提取足够信息。解决不要完全依赖自动化。初始化后手动审阅并编辑project-brief.md中的目标和features.md中的清单。你可以直接告诉AI“根据我们刚才的讨论更新project-brief.md将‘提高性能’具体化为‘将API P99延迟降低至200ms以下’。” AI会帮你完成修改。核心心得bootstrap是一个起点而不是终点。最重要的产出是文件结构和初始内容框架具体内容需要你和AI在初期共同打磨。问题在团队中一个开发者运行了pivot改变了技术栈但其他开发者的AI似乎没意识到。排查检查其他开发者本地的docs/目录下的共享文件是否已通过git pull更新。确认pivot技能确实更新了所有相关的状态文件特别是project-brief.md的决策日志。解决强化“预拉取协议”习惯。可以在团队晨会上强调开始任何新任务前先拉取代码。此外pivot技能生成的变更集应该包含所有更新的状态文件在代码审查时reviewer代理会重点审查这些变更这本身就是一个二次确认和传播的过程。心得方向变更是一个“广播”事件需要沟通PR/MR描述和工具pivot审查双重保障。5.2 日常开发与协作问题reviewer代理总是抱怨我没有更新dependency-map.md但我认为这个模块改动很小。排查“铁律”第6条是硬性规定无论改动大小。检查你是否确实修改了模块的导入/导出关系或职责边界。解决即使是一个很小的改动只要影响了模块的公共接口或依赖关系就应该更新依赖图。一个技巧是在提交前主动运行npx kodevibe/harness validate它会检查状态文件的完整性并给出具体警告。心得更新依赖图看似是额外开销实则是为未来做投资。当下次进行影响分析时一张准确的依赖图能节省大量排查时间。问题团队模式下我的project-state.md似乎和别人的没关联感觉像在孤岛工作。排查这是设计如此。project-state.md跟踪的是个人任务进度旨在避免合并冲突。团队的整体进度应该由项目管理工具如Jira, Linear或共享的看板来维护。解决将project-state.md视为你的个人工作清单和上下文记录器。团队进度同步应通过每日站会或项目管理工具进行。kode:harness 的sprint-manager代理可以帮你将用户故事分解为任务并跟踪完成情况但其主要服务对象是你和你的AI。心得区分“团队协同上下文”和“个人执行上下文”是高效协作的关键。kode:harness 管理后者并与前者通过故事ID等保持松耦合连接。问题AI有时还是会提出违反“非目标”的建议Direction Guard 失效了吗排查Direction Guard 的检查发生在AI生成完整建议之前。失效可能因为1) 非目标描述不够具体、可检测2) AI的提示词上下文被其他长篇对话稀释。解决首先优化project-brief.md中的非目标描述。例如将“避免过度设计”改为“禁止引入当前故事不需要的设计模式如工厂模式、观察者模式”。其次定期清理与当前任务无关的对话历史或开启新的聊天会话以确保核心上下文状态文件位于提示词最前端。心得Direction Guard 是一个基于规则和上下文的过滤器其效果与规则的质量和上下文的“新鲜度”直接相关。把它看作一个需要定期维护的“规则引擎”。5.3 集成与扩展问题我们团队使用Confluence和Figma进行设计如何集成到管道排查kode:harness 的 Crew Artifact Integration 目前主要支持放置在项目docs/目录下的Markdown、文本或图像文件。解决可以建立一个轻量级的同步流程。例如将Confluence页面的核心内容目标、用户故事、验收标准导出为Markdown文件放入docs/PM/目录。将Figma的架构图导出为图片并附上一个简短的architecture-notes.md说明文件放入docs/Architecture/。然后运行bootstrap技能并指定crew模式。心得集成的关键在于提取机器可读的核心信息而不是完美的格式。一份包含关键决策和接口定义的纯文本摘要比一个精美的、但AI难以解析的PDF更有用。问题我们使用的IDE不在官方支持列表里怎么办排查kode:harness 支持6种IDEVS Code, Cursor, Claude Code, Windsurf, Codex, Antigravity其本质是为这些IDE的AI助手提供特定格式的提示词文件。解决查看已支持IDE的配置格式位于项目.github/,.cursor/等目录。大多数AI IDE都支持某种形式的全局或项目级指令文件。你可以尝试模仿现有格式为你使用的IDE如JetBrains IDE with AI Assistant创建对应的配置文件。核心是确保“导航分发器”核心规则和技能/代理的路径能被你的AI读取。心得框架的核心是那套状态文件和工作流逻辑。IDE配置只是“适配器”。理解原理后为新的AI编码环境制作适配器是可行的。6. 实操配置、维护与进阶技巧6.1 安装与健康检查安装过程非常简单但正确的模式选择很重要。# 对于个人项目或尝试 npx kodevibe/harness init # 对于团队项目务必使用团队模式 npx kodevibe/harness init --team安装后务必运行健康检查命令这能避免后续很多奇怪的问题。# 检查文件是否安装完整 npx kodevibe/harness doctor # 验证状态文件内容是否有效非空模板 npx kodevibe/harness validate技巧在CI/CD流水线中加入harness validate作为检查步骤可以防止包含无效或空状态文件的代码被合并。6.2 IDE特定配置对于大型项目尤其是使用管道并集成了大量外部设计文档时AI的上下文长度可能成为瓶颈。你可能需要调整IDE的AI设置。VS Code Copilot在.vscode/settings.json中增加chat.agent.maxRequests: 100。这增加了Copilot Agent在一次任务中可以执行的步骤数对于复杂的bootstrap或pivot操作很有必要。Cursor / Claude Code / Windsurf这些环境通常能自动管理上下文但如果你在复杂任务中遇到中断可以尝试在对话中明确要求AI“逐步执行”或“分阶段完成”。6.3 状态文件的版本控制策略虽然docs/下的共享状态文件被Git管理但需要明智地处理合并冲突。精细化提交鼓励将状态文件的更新与相关的代码变更放在同一个提交中。例如“添加用户认证模块”的提交应同时包含认证代码、features.md的更新和dependency-map.md的更新。这使得变更集在逻辑上完整回滚也一致。合并冲突解决当project-brief.md或dependency-map.md发生冲突时不要简单地选择“我们的”或“他们的”。必须人工审查冲突内容理解背后的方向分歧。解决冲突后运行harness validate确保文件结构正确。如果冲突解决实质性地改变了项目方向考虑运行一次pivot技能来正式记录这次变更决策。6.4 定制化技能与代理kode:harness 的技能和代理是存储在项目本地目录中的Markdown文件。这意味着你可以根据团队需求进行定制。添加团队特定技能例如如果你的团队有“发布清单”检查你可以在.github/skills/或其他对应IDE目录下创建一个release-checklist.md文件按照现有技能的格式编写步骤。然后在project-brief.md中引用它或修改导航分发器的规则来包含它。调整代理行为例如你觉得reviewer代理对测试覆盖率的要求不够可以直接编辑.github/agents/reviewer.agent.md文件在审查清单中加入更严格的检查项。重要提醒对核心技能和代理的修改尤其是涉及“铁律”的需要在团队内达成一致并考虑通过Git分支策略来管理这些“框架定制”的变更。6.5 性能与规模化考量一个常见的顾虑是让AI在每次交互前都读取多个状态文件会不会拖慢响应速度实测影响状态文件总大小约17K tokens对于现代LLM来说这只是上下文窗口的一小部分。增加的延迟主要在于网络传输和模型处理上下文的时间通常在实际体验中并不明显。收益权衡这点微小的延迟换来的是AI行为的一致性和方向正确性避免了因方向错误而导致的重构或调试成本从投入产出比上看是极高的。超大型项目对于极其庞大的单体仓库dependency-map.md和features.md可能会膨胀。此时可以考虑按子系统或模块拆分这些文件并通过一个索引文件来组织。kode:harness 本身是文件系统驱动的这种结构调整是可行的但需要同步更新所有技能和代理中引用这些文件的路径逻辑。将kode:harness引入团队起初可能会感觉增加了流程步骤。但它的价值在于将隐性的、依赖于个人经验的“开发纪律”变成了显性的、可版本控制、可AI强化的“工程规范”。它不取代你的项目管理工具也不取代你的代码审查流程而是在AI这个新的、强大的但不可预测的“团队成员”与现有工程实践之间架起了一座可靠桥梁。最终它让团队能够放心地规模化使用AI真正实现“让每个开发者的AI都朝着同一个项目方向前进”。