使用 kybes 构建可预测的 AI 生成后端

kybes 的功能

kybes 是一个 Claude Code 插件，可根据 YAML 数据库架构生成可预测的后端代码。它在 C#、Python、TypeScript 和 Java 项目中统一文件夹、文件名、仓储方法、验证、分页、事务、索引和测试。

kybes 不要求 AI 代理记住架构文档，而是通过确定性生成、专用代理、文件夹级规则、钩子和 CI 检查来强制执行架构。同一个架构会在不同项目中生成字节级完全一致的输出。

核心规则很简单：架构是唯一事实来源，生成文件不得手动编辑，自定义行为应放在与其表关联的模型文件中。

生成结构的工作方式

对于每个表，kybes 会创建两层模型：

• model/generated/<Table> 包含生成的实体、CRUD 操作、关系、声明式查询、游标分页和验证。这些文件会被重新生成，不应编辑。
• model/<Table> 是放置自定义方法的安全位置。C# 使用分部类，而 Python、TypeScript 和 Java 使用基于子类的方式。

典型项目还会包含生成的 JSON Schema、PostgreSQL DDL、索引分析、模型文件索引以及生成的验证产物。

安装 kybes

通过 Claude Code 安装

在 Claude Code 中添加市场并安装插件：

/plugin marketplace add ivandilelio/kybes
/plugin install kybes@kybes

在目标项目中，请 Claude Code 在此项目中设置 kybes。kybes:kybes-init 技能会询问你需要哪些模型语言，并创建配置、路径规则、CLAUDE.md 指令、可选脚手架和 CI 工作流。

尚未初始化的仓库中，钩子会保持停用状态。

从命令行安装

你也可以克隆仓库并运行安装程序：

git clone https://github.com/ivandilelio/kybes
kybes/install.sh --target /path/to/project --scaffold --examples \
  --model-langs csharp,python,typescript,java

安装程序具有幂等性。队友克隆已配置的项目后，只需运行一次 tools/kybes/setup.sh。

检查要求

钩子和生成器只需要带标准库的 python3。生成的运行时需要相应语言的依赖：

• C#： net8.0、Entity Framework Core 8，以及 Npgsql 等提供程序。
• Python： Python 3.9 或更高版本，以及 SQLAlchemy 2。
• TypeScript： TypeORM、reflect-metadata，并启用 experimentalDecorators 和 emitDecoratorMetadata 编译器选项。
• Java： Jakarta Persistence 3.1、Hibernate 6.2 或更高版本，以及用于 json 列的 Jackson。

定义数据库架构

在 schemas/db 下创建 YAML 文件。以下示例定义了一个订单表，其中包含唯一订单号、必填客户关系、声明式查询以及可排序的游标分页：

table: Ordini
columns:
  - { name: Id, type: uuid, primary_key: true }
  - { name: Numero, type: string, length: 20, required: true, unique: true }
  - { name: ClienteId, type: uuid, required: true }
  - { name: Data, type: date, required: true }
relations:
  - { name: Cliente, kind: many_to_one, target: Clienti, foreign_key: ClienteId }
queries:
  - name: DelClienteDal
    where: [ClienteId, { column: Data, op: gte, param: DaData }]
    order_by: [{ column: Data, dir: desc }]
pagination:
  default_order: [{ column: Data, dir: desc }]
  sortable: [Data, Numero]

将文件保存为 schemas/db/Ordini.yaml。架构发生变化时，会为已配置的语言触发重新生成、更新模型索引，并重新计算索引建议。

使用生成的 API

对于示例架构，kybes 会在每种语言中生成等效的仓储功能。命名遵循目标语言的约定：

• 按键读取：C# 中为 GetByIdAsync，Python 中为 get_by_id，TypeScript 或 Java 中为 getById。
• 游标分页：ListPageAsync、list_page 或 listPage。
• 按唯一列查询：FindByNumeroAsync、find_by_numero 或 findByNumero。
• 按外键查询：ListByClienteIdAsync、list_by_cliente_id 或 listByClienteId。
• 声明式查询：ListDelClienteDalAsync、list_del_cliente_dal 或 listDelClienteDal。

生成的 API 还提供经过验证的创建、更新和删除操作、关系访问器，以及基于游标的分页。分页由请求和包含项目及下一个游标的页面表示。

声明查询，而不是在处理程序中编写数据访问代码

将支持的查询条件放入架构中，而不是在 Lambda、服务或控制器中导入 ORM 或数据库驱动程序。kybes 支持包括 eq、ne、lt、lte、gt、gte、in、prefix 和 is_null 在内的运算符。

生成器会创建仓储方法并分析其访问路径。在此示例中，外键和日期条件会生成针对 (ClienteId, Data) 的索引。该决策记录在 db/generated/indexes.md 中。

添加自定义模型行为

当生成的方法不够用时，请将自定义方法添加到非生成的模型文件中，例如 model/Fornitori.py，或所选语言对应的等效文件。不要编辑生成的实现。

自定义方法不得与生成的方法名冲突。在工作完成前，还必须在 tests/custom/ 中添加可追踪的测试。预期的测试标识符格式为 TC-<Table>-…。

将数据访问保留在模型层中。处理程序应调用生成的模型方法或自定义模型方法，而不是自行创建 SQLAlchemy、Entity Framework、TypeORM 或 Hibernate 查询。

了解 kybes 防护规则

kybes 钩子会贯穿整个开发工作流。在写入之前，它们可以阻止模型之外的 ORM 或数据库驱动导入、对生成文件的编辑、无效的模型文件夹、方法冲突以及明文密钥。

架构写入后，kybes 可以重新生成模型、运行代码检查器并报告架构问题。在完成之前，主代理和每个子代理都必须通过架构检查、生成器检查、验证脚本和项目测试命令。

默认的停止门检查包括：

• arch_check，包括检测重复的、长度达到八行或以上的代码块。
• gen --check，用于确认生成的输出是最新的。
• verify.py，用于模型测试和各 ASIL 级别的覆盖率阈值检查。
• 项目自身的测试命令。

同样的检查也会在 CI 中通过 --strict 运行。可以在 .claude/kybes.config.json 中将规则配置为 block、warn 或 off。代理不得修改此配置文件。

安全使用事务、分页和索引

kybes 根据架构的默认排序和允许排序的列生成游标分页。这会生成基于键集的分页请求，以及包含项目和下一个游标的页面。游标格式在受支持的语言之间共享，有助于不同服务和客户端实现互操作。

事务使用工作单元，并支持按表设置隔离级别，以及针对序列化失败和死锁的自动重试处理。系统会分析声明的访问路径以确定理想索引；缺失的索引会被创建，多余的索引会被标记。在适用的情况下，前缀搜索可以使用 PostgreSQL 的 varchar_pattern_ops。

配置多租户

可以使用以下支持的策略之一按表配置多租户：

• 租户列：所有生成的方法都会进行过滤，唯一约束也会按租户限定范围。
• PostgreSQL 行级安全。
• 每个租户使用一个架构。
• 每个租户使用一个数据库。

租户会绑定到 ORM 会话，kybes 会针对所配置的策略生成隔离测试。

查看生成的项目布局

完成配置的项目遵循可预测的结构：

your-project/
├── schemas/db/<Table>.yaml
├── schemas/generated/json/<Table>.schema.json
├── libs/db-models/<language>/…/model/
│   ├── <Table>.{cs,py,ts} | <Table>Repository.java
│   └── generated/
├── libs/db-models/<language>/tests/
│   ├── generated/
│   └── custom/
├── docs/generated/verification/
├── db/generated/ddl/postgres/_all.sql
├── services/<context>/{functions,ms}/
├── jobs/
├── libs/utils/
├── libs/errors/
├── frontend/
├── infra/
├── MODEL_INDEX.md
└── .claude/kybes.config.json

generated/ 文件夹下的所有内容都属于 kybes。其他模型文件、自定义测试、架构文件和应用代码则由团队根据已配置的规则维护。

验证结果

仓库包含针对生成代码、钩子、SQL 和跨语言行为的验证。测试涵盖 CRUD、关系、级联、唯一约束、分页边界情况、查询运算符和工作单元行为。

生成的单元测试会从每个架构中提取需求和测试用例。验证工作流包括等价类、边界值、错误猜测、ASIL C 和 D 的 MC/DC、可追踪性，以及按表设置的覆盖率门槛。仓库还会检查生成的 PostgreSQL DDL 是否能正确解析，以及一种受支持语言生成的游标是否能被其他语言接受。

对于安全关键型工作，kybes 会在软件单元级别自动化 ISO 26262-6 的部分流程，但它不能替代完整的安全计划、危害分析、工具鉴定、独立审查或组织认证流程。

结语

kybes 为可预测的 AI 生成后端提供了架构优先的工作流。只需定义一次表、关系、查询、分页和租户规则；让确定性生成器创建特定语言的模型、索引、DDL、验证和测试；然后将自定义行为放入获批准的模型层。

借助 Claude Code 代理、写入时钩子、重复代码检测、生成式验证和严格的 CI 检查，即使代码库和 AI 上下文不断扩大，项目仍能保持一致。如需更深入的参考资料，请浏览项目的 文档和源代码仓库。