Newshot

Kibi——面向 AI 编程代理的需求框架

Translation(model translation, not the source's own text)

开源 · 在你的仓库中运行

说清软件该做什么。你的 agent 不会忘记为什么。

Kibi 是面向 AI coding agent 的需求框架。它把代码背后的推理(你在对话中达成的意图、假设和取舍)作为需求记录在你的仓库里,将需求与代码和测试关联起来,并让之后每一个 agent 都遵守它们。

  • 保留每次变更背后的原因,而不只是变更本身
  • 在 agent 修改代码之前,先向它展示这些推理
  • 拒绝与旧规则相矛盾的新规则
  • 报告哪些需求真正被测试覆盖

        Set up Kibi (https://github.com/Looted/kibi) in this repository, then bootstrap its knowledge base.

1. Install: confirm Node.js 22+ is available. With the package manager this repository already uses, add kibi-core, kibi-cli and kibi-mcp as dev dependencies. Do not skip optional dependencies; the bundled SWI-Prolog runtime is one.
2. Initialize: run every `kibi` command through the package manager's local runner (npm: `npm exec -- kibi <command>`). Run `kibi init`; if it reports a problem, run `kibi doctor` and fix what it names. If this platform has no bundled SWI-Prolog, tell me what to install and stop.
3. Connect: register the project-local `kibi-mcp` server for the agent host you are running in, following https://looted.github.io/kibi/guide/connect-an-agent.html. Prefer project-scoped configuration, and ask me before installing a plugin or changing global settings. Until the kb_* tools are visible to you, use Kibi's CLI JSON routes instead.
4. Bootstrap: run `kibi skills load kibi-bootstrap --format markdown` and follow that skill exactly. It starts by asking me where product intent lives outside the code (issue trackers, wikis, specs) and which sources to trust; read them through the connectors you have and cite them. Show me the complete plan and its hash, and write nothing until I approve it.
5. Verify: run `kibi check` and `kibi status`, fix anything they report, and summarize what was added. Do not commit; I will review the changes.
      

每一行都是一条驶向闸门的需求。只有新鲜的端到端证据才能让它通过。

  • 已通过闸门
  • 等待证据
  • 矛盾

为你已在使用的 agent 提供的插件

  • + 任何 MCP 客户端或 CLI

01问题

代码展示软件做了什么,却不展示它必须持续做到什么。

在源码里,每一行看起来都一样刻意。来之不易的取舍、业务规则、临时假设、捷径和被遗忘的遗留物,读起来全都一样。区别存在于当初做出决定的对话中,而那段对话已经消失了。于是下一个 agent 要么“清理掉”某个决定,要么小心翼翼地保留一个意外。


        export const TRIAL_DAYS = 14;
      

一个取舍:试用期越短转化越好,我们接受更高的流失率。


        export function canCheckout(cart) {
  return cart.total > 0;
}
      

一条业务规则:绝不对空购物车收费。


        export const MAX_SEATS = 50;
      

一个假设:在企业版定价出现之前成立。当这一区域被改动时重新审视。


        export function chargeWithRetry(order) {
  return retry(() => charge(order), { attempts: 5 });
}
      

一个捷径:支付提供商丢弃 webhook。后续 agent 可以带着证据重做它。


        export function legacyDiscount(user) {
  return user.createdAt < CUTOFF ? 0.1 : 0;
}
      

没有人记录原因。Kibi 要求 agent 在修改代码之前先写下它的作用。

五段代码。没有原因,其中任何一段都可能是决定,也可能是错误。有了 Kibi,原因被写下来,与代码关联,并在 agent 编辑这些行之前展示给它。

  • 01 原因比对话活得更久 没有对话中说“我们会用 X 来留住用户”。代码里只写了 X,下一个 agent 无法分辨这是权衡还是错误。有 Kibi每条需求都以提出者的原话记录它为何存在,决策保留其权衡取舍。当你陈述一条规则时,agent 会用一次 kb_record 调用把它记录下来,包含你的理由、你的原话以及实现它的代码,并立刻得知某次提交是否会通过。它们存放在每个分支上代码旁边的 .kb/ 里,Kibi 会标记出那些没有说明原因的需求。

原因比对话活得更久

对话中说“我们会用 X 来留住用户”。代码里只写了 X,下一个 agent 无法分辨这是权衡还是错误。

每条需求都以提出者的原话记录它为何存在,决策保留其权衡取舍。当你陈述一条规则时,agent 会用一次 kb_record 调用把它记录下来,包含你的理由、你的原话以及实现它的代码,并立刻得知某次提交是否会通过。它们存放在每个分支上代码旁边的 .kb/ 里,Kibi 会标记出那些没有说明原因的需求。

  • 02 决策不再被推翻 没有agent 重写了一条它从不知道存在的规则。有 Kibi在编辑文件之前,agent 会看到该代码所实现的需求、它必须始终保持成立的内容、它为何存在,以及其背后的决策。

决策不再被推翻

agent 重写了一条它从不知道存在的规则。

在编辑文件之前,agent 会看到该代码所实现的需求、它必须始终保持成立的内容、它为何存在,以及其背后的决策。

  • 03 冲突在写代码之前就被发现 没有相隔一周的两条提示互相矛盾,却没有人注意到。有 Kibi与现有规则相矛盾的规则会被拒绝,并同时指明两者,由你决定哪一条胜出。

冲突在写代码之前就被发现

相隔一周的两条提示互相矛盾,却没有人注意到。

与现有规则相矛盾的规则会被拒绝,并同时指明两者,由你决定哪一条胜出。

  • 04 “完成”意味着经过测试,而不是声称 没有CI 通过并不能说明在这个提交上哪些产品行为仍然有效。有 Kibi健康报告会显示哪些需求有最新的端到端证据,哪些仅凭某人的口头说法,以及哪些存在缺口。

“完成”意味着经过测试,而不是声称

CI 通过并不能说明在这个提交上哪些产品行为仍然有效。

健康报告会显示哪些需求有最新的端到端证据,哪些仅凭某人的口头说法,以及哪些存在缺口。

02为什么不是一个记忆文件

记忆负责记住。Kibi 负责强制执行。

笔记文件和记忆服务帮助 agent 回忆事情。Kibi 把意图及其理由变成规则,这些规则与代码关联、会检查矛盾、在编辑时呈现在 agent 面前,并有证据支撑。

看 Kibi 检查 agent 的工作

简化自 Kibi 在每种情况下报告的内容。

03它如何工作

从提示到证明,在同一条轨道上

Kibi 在每个阶段都把意图与工作保持绑定,而在最后一个阶段上它很保守。

  • 意图你说一次用平实的语言提示所需行为,就像你平时那样做。那句话始终是源头。

你说一次

用平实的语言提示所需行为,就像你平时那样做。那句话始终是源头。

  • 需求agent 把它写下来需求、场景和带类型的事实落到代码旁边的 .kb/ 中,并引用它们来自的工单或页面。

agent 把它写下来

需求、场景和带类型的事实落到代码旁边的 .kb/ 中,并引用它们来自的工单或页面。

  • 强制执行每一次编辑都会听到它在 agent 编辑实现某项需求的代码之前,Hooks 会指出该需求。检查会标记出矛盾和没有追溯来源的代码。

每一次编辑都会听到它

在 agent 编辑实现某项需求的代码之前,Hooks 会指出该需求。检查会标记出矛盾和没有追溯来源的代码。

  • 证据测试留下凭据声称满足某项需求的测试会记录证据,并绑定到它所运行的确切代码快照。

测试会留下凭据

一个声称验证某条需求的测试,会记录与其运行时所依据的确切代码快照绑定的证据。

  • 只有新证据才能通过。过期的凭据和通过的单元测试都无法通过这道关卡。Proved 只保留给检查器针对每一个用例都确立的声称。

只有新证据才能通过

过期的凭据和通过的单元测试都无法通过这道关卡。Proved 只保留给检查器针对每一个用例都确立的声称。

你实际要做的事

三件事,没有一件是填写需求表单。

  • › 当有人离开页面时,草稿编辑必须保存。为 REQ-draft-autosave 提议一个计划…… 01 陈述行为 像你平时那样写提示词。“当有人离开页面时,草稿编辑必须保存。”你不需要填写需求表单。

陈述行为

像你平时那样写提示词。“当有人离开页面时,草稿编辑必须保存。”你不需要填写需求表单。

  • plan REQ-draft-autosave + requirement · scenario · fact firm 批准 纠正 02 批准真正的决策 智能体在写入项目知识之前会先提议一个计划。你来批准它,或者纠正产品层面的判断。根据你的提示词编译出的计划要么完整落地,要么完全不落地,而记账工作留给智能体。

批准真正的决策

智能体在写入项目知识之前会先提议一个计划。你来批准它,或者纠正产品层面的判断。根据你的提示词编译出的计划要么完整落地,要么完全不落地,而记账工作留给智能体。

  • proved checker, every case tested fresh end-to-end asserted a person stands behind it unverified only an agent does 03 阅读结果 健康报告会指明哪些已被测试、哪些仍有缺口、哪些自相矛盾,并为每条需求标注 proved、tested、asserted 或 unverified。一次绿色的测试运行是另一回事。当 pre-commit 钩子拒绝没有需求归属的新代码时,它会针对每个声明打印一个区块,附上已拥有该文件其余部分的需求,以及一个可直接运行、能将其关联起来的输入,而绝不会自行挑选。

阅读结果

健康报告会指明哪些已被测试、哪些仍有缺口、哪些自相矛盾,并为每条需求标注 proved、tested、asserted 或 unverified。一次绿色的测试运行是另一回事。当 pre-commit 钩子拒绝没有需求归属的新代码时,它会针对每个声明打印一个区块,附上已拥有该文件其余部分的需求,以及一个可直接运行、能将其关联起来的输入,而绝不会自行挑选。

将 Kibi 添加到代码仓库

Kibi 由你的编码智能体驱动,因此推荐的安装方式是一段提示词。你的智能体会安装各个包、运行 kibi init、将自身连接到 Kibi、在你批准的计划背后引导建立知识库,然后补充场景、谓词以及计划在正常工作流中无法写入的声称,并在第二个你批准的计划中提议如何为你的测试运行器进行证明运行。包管理器标签页是手动路径;重新运行 kibi init 会补全缺失的目录和 schema 文件,同时保留现有的知识和 schema 文件。它不会凭空编造产品做什么。

智能体首先会询问你的产品意图存放在哪里,例如问题追踪系统、wiki 和规格文档,以及哪些来源可信。引导计划中的每条需求都会引用它来源的工单或页面,在你批准该计划之前不会写入任何内容。当某个声称与同一主题上已有的某条需求相邻、而 Kibi 无法在逻辑上检查它时,计划会点名那条需求,以便智能体对两者进行比较,对于计划留给智能体撰写的声称也是如此。计划如何构建、应用以及在中断后如何恢复,详见 MCP 参考。

文章标题:Kibi——面向 AI 编码代理的需求框架

正文: bootstrap 记录的是决定每个行为的代码,而不是每一条声明。pre-commit 钩子只根据提交新增或修改的声明来评判该提交,因此代理做出的正确改动绝不会因为并非由它造成的缺口而被拒绝;kibi check 会把未记录的其余部分计为不阻塞的 symbol debt(可用 kibi check --symbol-debt 列出),随着提交触及那部分代码,它会逐渐缩小。


        Set up Kibi (https://github.com/Looted/kibi) in this repository, then bootstrap its knowledge base.

1. Install: confirm Node.js 22+ is available. With the package manager this repository already uses, add kibi-core, kibi-cli and kibi-mcp as dev dependencies. Do not skip optional dependencies; the bundled SWI-Prolog runtime is one.
2. Initialize: run every `kibi` command through the package manager's local runner (npm: `npm exec -- kibi <command>`). Run `kibi init`; if it reports a problem, run `kibi doctor` and fix what it names. If this platform has no bundled SWI-Prolog, tell me what to install and stop.
3. Connect: register the project-local `kibi-mcp` server for the agent host you are running in, following https://looted.github.io/kibi/guide/connect-an-agent.html. Prefer project-scoped configuration, and ask me before installing a plugin or changing global settings. Until the kb_* tools are visible to you, use Kibi's CLI JSON routes instead.
4. Bootstrap: run `kibi skills load kibi-bootstrap --format markdown` and follow that skill exactly. It starts by asking me where product intent lives outside the code (issue trackers, wikis, specs) and which sources to trust; read them through the connectors you have and cite them. Show me the complete plan and its hash, and write nothing until I approve it.
5. Verify: run `kibi check` and `kibi status`, fix anything they report, and summarize what was added. Do not commit; I will review the changes.
      

        npm install --save-dev kibi-core kibi-cli kibi-mcp
npm exec -- kibi init
      

        pnpm add -D kibi-core kibi-cli kibi-mcp
pnpm exec kibi init
      

        yarn add -D kibi-core kibi-cli kibi-mcp
yarn exec kibi init
      

需要 Node.js 22+。SWI-Prolog 在 Linux(x64、arm64)和 macOS 上是捆绑的;其他平台需要 PATH 中有 swipl(SWI-Prolog 9.0+)。系统安装的 swipl 仅作为回退;设置 KIBI_SWIPL=system 可优先使用它。Bun 命令和各平台的安装方法见安装指南。每个发行版只有一个版本号,例如 Kibi 2026.11.0,它对应一组确切的包;kibi --version 和 kibi doctor 会显示它(release versions),当有更新的版本发布时,CLI 每天会提示一次(update notices)。Kibi 会发送匿名使用统计;查看发送了哪些内容以及如何关闭。

接下来去哪里

在仓库上使用 Kibi

安装它,连接你已经在用的代理,并学会如何阅读第一份健康报告。面向发出提示的人,而不是面向代理。

  • 什么是 Kibi?
  • 连接你的编码代理
  • 阅读健康报告
  • 阅读你所依赖的仓库的 KB

查阅确切的约定

命令、工具 schema、实体字段,以及 Kibi 实际运行的检查。刻意保持枯燥,并且与仓库使用相同的文件渲染。

  • CLI 参考
  • 实体 schema
  • 错误参考

人们最先问的问题

简短的回答。长回答在指南里。

不会。你描述行为。你的代理把它转化为需求、场景、测试以及到代码的链接。当产品决策确实存在歧义时,你才介入。

不会。保留你现有的 tracker。在 bootstrap 期间,代理会询问哪些 tracker、wiki 和 spec 承载了你的产品意图,通过它自己的连接器读取它们,并引用每条需求背后的工单或页面。然后 Kibi 把该决策连接到实现它的代码,并连接到代码仍然在执行它的证据。

TypeScript 和 JavaScript 开箱即用。为 Python、Go、Rust、Java、C#、PHP、C、C++、Bash、Ruby、SWI-Prolog 和 Terraform/HCL 添加可选的 kibi-plugin-treesitter 包。它离线运行,语法版本固定,每种语言都是一个小的 kibi-lang-* 包,只有用到时才安装。生成的文件不计入任何包,也不需要需求链接,除非 KB 使用了它们,而且你可以拒绝任何包。代码和源码证明直接读取 TypeScript、JavaScript、Python 和 SWI-Prolog,并通过插件读取 Go、Java、C#、Rust、PHP、C 和 Bash 文件的导入、调用和环境读取,以及 PHP、C 和 Terraform/HCL 文件的属性值,无需编译它们。设置见插件参考。

部分可以,且仅在你主动启用时。实验性的 kibi-plugin-ui 包(当 /kibi-bootstrap 发现 React 或 Angular 组件时会提供它)会让 kb_check 要求每个组件都实现一条设计需求,并标记出丢失了标记其约定模式的类名或测试 id 的组件。这能抓住把时间线改写成卡片的 agent。它看不到像素、颜色或间距;那些仍然交给你的 linter。详情见插件参考。

可以。kb_search 接受一个普通问题,并在返回排序匹配的同时,返回管辖该主题的当前需求及其各自的内容、记录的缘由(以及由谁、何时给出),以及其关联的事实、场景、测试和 ADR(附每条决策的摘录)。对于每条需求,它还会报告任何点名它的矛盾或不可行情景发现、豁免它的已批准例外,以及检查无法判定的内容,并说明答案来自哪个分支和 KB 快照。在一个从未编译过存储的新分支上,答案会说明这一点并指向 kibi sync,而不是静默返回空结果。被取代和已退役的需求单独列出,以免被当作当前策略阅读,而没有任何需求拥有的顶级匹配会被明确指出,而不会被更低排名的需求所包装。没有发现并不等于证明:完整的一致性和证明状态仍来自 kb_check(它还会说明评估了多少条规则、比较了多少对事实)和 kb_coverage。答案默认十行,在 Claude Code 上只发送一次,作为结构化内容加一段简短文本摘要,而不是在文本中再放一份 JSON 副本。

可以。kb_query 直接询问已建模的事实,无需 agent 编写 Prolog:{predicate: "permission_rule", where: {actor: "admin"}} 返回每条规则及其 allow 或 deny 效果,{predicate: "has_role", where: {user: "alice"}, distinct: "role"} 统计用户的角色数,{subjectKey: "user.role_assignment", propertyKey: "max_roles"} 返回一个限制及其运算符和值。{factKind: "predicate_schema"} 列出项目建模的谓词和参数名,未知参数名会连同已声明的参数名一起返回,空答案会列出确实存在的值,每个答案都会指明下一次要发起的调用。kb_search 链接到需求的事实带有相同的类型化声明和询问它的查询,而 {id, includeBody: true} 返回需求作者撰写的主体,以便纠正其中过时的句子。

可以。带 dryRun: true 的 kb_upsert 会执行与真实写入相同的校验,包括针对某条需求(requirement)的矛盾检查;配合 plannedFacts 时,它会把 kb_model 规划出的事实暂存起来,因此,如果一条 allow 规则与同一 actor、action、resource 上已存储的 deny 相矛盾,那么两者在写入之前就会被拒绝,并指出冲突所在。kb_model 还会将这样的 grounding 作为一个 hash-bound plan 返回:其矛盾分析基于当前知识库计算,存在冲突时该 plan 会被置为 blocked,而干净的 plan 会在一次 kb_apply_plan 调用中写入该事实及其链接,要么全部成功,要么全部不做。kb_delete 同样接受 dryRun: true,删除一个 authored 实体时会先返回一个 hash-bound plan,其中包含应用该删除的确切 kb_apply_plan 调用。

使用 Claude Code、Cursor、Codex、ZCode 或 OpenCode 插件时,编辑前钩子(OpenCode:编辑提示)会在做出更改之前,指明该文件实现了哪条需求、它必须保持为真的内容(来自其链接的事实)、它为何存在(其记录的原因,或未记录任何原因),以及其背后的决策(其 ADR)。使用 Claude Code 插件时,这还覆盖 agent 通过 shell 命令所做的编辑,这些编辑会在命令运行后立即获得相同的上下文。被取代或已退役的需求不会作为当前需求显示。每次编辑后,该钩子会请求带 changed: true 的 kb_check,从而在暂存任何内容之前,给出 pre-commit 钩子对截至目前所有已更改内容将给出的判定,并将每个发现标记为是否阻塞提交。限定于已更改文件的 kb_check 还会指出某个没有需求归属的文件中任何已更改的函数,因此 agent 无需被要求就会记录它现在的行为;它会引用已更改代码所实现的每条需求的陈述和 firmness,并以“no structural violations”而不是“no violations”开头,因为它从不将代码与需求的文字描述进行比较;对于没有链接符号的文件,钩子和检查都会指出标题与该文件路径中的词共享的需求,因此“nothing linked”不会被理解为“no rule applies”;它还会报告它能够判定的冲突,例如针对同一 actor、action 和 resource 的 allow 与 deny,并在分析不完整时说明这一点,而不是称其为干净。一个场景如果假设了当前需求所禁止的内容,无论是其自身假设还是仅与其其他假设组合后才构成禁止,都会被标记并阻止证明。条件性需求也算数:“checkout may happen only when the cart total is positive”会变成一条带类型的规则,而总金额为零的结账场景会被标记,除非有人为其批准了例外。

对于读取,可以。在一个没有单一分支指向的提交上,例如对某个 SHA 的 CI checkout 或 bisect,search、query、status、check、coverage 和 graph 会从基于该 checkout 编译出的只读快照给出答案,并且每个答案都会说明这一点。在你检出某个分支或设置 KIBI_BRANCH 之前,写入会被拒绝。详情见 CLI reference。

每个实体都可以记录其来源:由人类、agent、migration 或 import 写入,以及由谁批准。来自你的 agent 的新实体会被标记为 agent 写入。kb_check 会列出没有任何人批准的 agent 写入的需求、只有 agent 记录了批准的例外,以及没有说明其存在原因的需求。Kibi 无法确认某件事得到了某个人的批准。它会向你显示仍然需要你审查的内容。

需求与 ADR 还会记录它们的决定有多坚定。你陈述的规则是坚定的,并指向你的原话;只有另一个坚定的决定才能替换它,因此 agent 被告知要先询问你,并且 agent 不能就地改写它,除非它引用你的新原话。Kibi 检查引用是否存在,而不是检查你是否真的写了它。你委派的选择,或 agent 做出的选择,是默认的:后续 agent 在有证据时可以替换它,并且每次替换都必须说明为什么改变。猜测是探索性的。没有坚定程度的规则被视为坚定的,除非是 agent 写的,而 bootstrap 会把它从你的文档中导入的规则标记为坚定的。当你的请求与任何已记录的规则冲突时,agent 会指出该规则并在更改前询问。搜索结果和编辑钩子会显示哪个是哪个。

一个需求只有在声称验证它的测试对当前代码拥有新鲜的端到端证据时,才算被测试。通过的单元测试、覆盖率百分比或旧回执都不算数。唯一的例外是仅命名一个 UI 模式的需求,例如“此列表在两个视图中都是线点时间线”:带新回执的隔离组件测试就能覆盖它,因为渲染该组件就能展示需求所说的一切。新鲜度根据仓库相对路径和文件内容计算,因此 CI 和你自己对同一提交的检出在什么被测试上是一致的。测试抽样用例,所以已测试不等于已证明:Kibi 将已证明保留给检查器为每个用例建立的声明,并带有第二个程序可以重新检查的证书。证书证明类型涵盖枚举域、类型级检查、算术和求解器约束、规则、状态机(包括永远无法到达的状态和每条路径都必须经过的状态)、模式,以及项目自身的路由、数据库 schema、配置和代码引用,这些由 Kibi 自己读取。没有当前测试检查的需求,当有人为其背书时是已断言,当只有 agent 为其背书时是未验证。

不。kibi init 创建目录和 Git 钩子;它不碰不是它写的钩子,并且在使用 lefthook、husky 或 pre-commit 框架时,它不安装任何钩子,而是打印要添加的配置(kibi init --print-hook all --format lefthook)。它还会通过 AGENTS.md 让全新克隆中的 agent 了解 Kibi,从 package.json 的 prepare 脚本再次安装钩子,并在首次查询时编译克隆的存储。它提交的内容是你和 agent 编写的内容:符号行位置由每次同步派生到一个被 gitignore 的缓存中,因此并行分支不会因它们发生冲突。它不推断行为。检查证明被编码的内容。缺失的知识保持可见。

此仓库发布自己的报告

每次推送到默认分支都会重新发布 Kibi 自身的需求健康状况:有多少当前需求被完整地端到端测试,哪些仅依赖某人的话,哪些互相矛盾,以及哪些证据已经过期。

从一个提示开始。

将设置提示粘贴到你的 agent 中,批准它向你展示的计划,并阅读你的第一份健康报告。

提示意图。Kibi 让 agent 记住它——并证明实现。

The translation is machine-generated and individual terms may be off. Nothing is rewritten or cut; the original is authoritative.

Published by HN AI
This site only summarises and aggregates; copyright stays with the original author. Headlines and summaries follow the source — where they differ, the original wins.
Read the original ↗