メインコンテンツへ移動
AIチュートリアル

kybesで予測可能なAI生成バックエンドを構築する

このチュートリアルでは、kybesがYAMLデータベーススキーマを一貫性のあるC#、Python、TypeScript、Javaモデルに変換する方法を説明します。Claude Codeプラグインのインストール、プロジェクトの設定、テーブルとクエリの定義、生成されたリポジトリの利用、安全なカスタムメソッドの追加、フックとCIチェックによるアーキテクチャの適用までを学びます。

約15分で読了
kybesで予測可能なAI生成バックエンドを構築する

kybesの機能

kybesは、YAMLデータベーススキーマから予測可能なバックエンドコードを生成するClaude Codeプラグインです。C#、Python、TypeScript、Javaの各プロジェクトで、フォルダー、ファイル名、リポジトリメソッド、バリデーション、ページネーション、トランザクション、インデックス、テストを標準化します。

AIエージェントにアーキテクチャドキュメントを記憶させる代わりに、kybesは決定論的な生成、専用エージェント、フォルダー固有のルール、フック、CIチェックによってアーキテクチャを強制します。同じスキーマから、プロジェクト間でバイト単位まで同一の生成物が作られます。

中心となるルールはシンプルです。スキーマを唯一の正しい情報源とし、生成ファイルは手動で編集せず、カスタム動作はテーブルに関連付けられたモデルファイルに記述します。

生成される構造の仕組み

kybesは各テーブルに対して、2つのモデル層を作成します。

  • model/generated/<Table>には、生成されたエンティティ、CRUD操作、リレーション、宣言済みクエリ、カーソルページネーション、バリデーションが含まれます。これらのファイルは再生成されるため、編集しないでください。
  • model/<Table>はカスタムメソッドを安全に配置する場所です。C#ではpartialクラスを使用し、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を1回実行するだけで済みます。

要件を確認する

フックとジェネレーターには、標準ライブラリのみを使用する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。8行以上の重複ブロックの検出を含みます。
  • 生成された出力が最新であることを確認するgen --check。
  • モデルテストとASILごとのカバレッジしきい値を確認するverify.py。
  • プロジェクト独自のテストコマンド。

同じチェックがCIでも--strict付きで実行されます。ルールは.claude/kybes.config.jsonでblock、warn、またはoffとして設定できます。エージェントはこの設定ファイルを変更してはいけません。

トランザクション、ページネーション、インデックスを安全に使用する

kybesは、スキーマのデフォルト順序と許可されたソート可能な列からカーソルページネーションを生成します。これにより、キーセット方式のページリクエストと、項目および次のカーソルを含むページが生成されます。カーソル形式はサポートされている言語間で共有されるため、異なるサービスやクライアント間の相互運用に役立ちます。

トランザクションでは、テーブルごとの分離レベルと、シリアライズ失敗やデッドロックに対する自動リトライ処理を備えたUnit of Workを使用します。宣言されたアクセスパスを分析して最適なインデックスを判断し、不足しているインデックスを作成して、冗長なインデックスを通知します。必要に応じて、前方一致検索では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、リレーション、カスケード、一意制約、ページネーションの境界ケース、クエリ演算子、Unit of Workの動作を対象とします。

生成される単体テストは、各スキーマから要件とテストケースを導出します。検証ワークフローには、同値クラス、境界値、エラー推測、ASIL CおよびD向けのMC/DC、トレーサビリティ、テーブルごとのカバレッジゲートが含まれます。また、生成されたPostgreSQL DDLが正しく解析できることと、あるサポート対象言語で生成されたカーソルを他の言語が受け入れられることも確認します。

安全性が重要な開発では、kybesはソフトウェアユニットレベルでISO 26262-6の一部を自動化しますが、完全な安全計画、ハザード分析、ツール認定、独立レビュー、組織的な認証プロセスに代わるものではありません。

まとめ

kybesは、予測可能なAI生成バックエンドのためのスキーマファーストワークフローを提供します。テーブル、リレーション、クエリ、ページネーション、テナンシールールを一度定義すれば、決定論的なジェネレーターが言語別のモデル、インデックス、DDL、バリデーション、テストを作成します。その後、カスタム動作を承認済みのモデル層に配置します。

Claude Codeエージェント、書き込み時フック、重複コード検出、生成された検証、厳格なCIチェックにより、コードベースとAIコンテキストが拡大してもプロジェクトの一貫性が保たれます。詳しいリファレンス資料については、プロジェクトのドキュメントとソースリポジトリを参照してください。