kybes — Know Your Backend

kybes is a Claude Code plugin that makes AI-generated backends predictable. Every project gets the same folders, the same file names and the same data-access methods. There is no duplicated code, and every rule that can be checked automatically is enforced as a hook or a CI step, not left to a prompt.

After a million lines of generated code across different projects, you should still know without searching that src/model/Clienti.cs holds the CRUD, relations and custom queries of the Clienti table. kybes makes that true.

Asking an AI to "follow our architecture" works only some of the time. Instructions get lost when the context grows. Planners and subagents may never see them. Two runs of the same prompt produce two different layouts. kybes takes a different approach:

flowchart LR
    S["schemas/db/Clienti.yaml<br/>columns · relations · queries<br/>pagination · transactions<br/>tenancy · archive"] --> G{{"kybes generator<br/>deterministic"}}
    G --> CS["C# · EF Core 8<br/>model/Clienti.cs"]
    G --> PY["Python · SQLAlchemy 2<br/>model/Clienti.py"]
    G --> TS["TypeScript · TypeORM<br/>model/Clienti.ts"]
    G --> JV["Java · JPA / Hibernate 6<br/>model/ClientiRepository.java"]
    G --> JS["JSON Schema<br/>API Gateway validation"]
    G --> DDL["PostgreSQL DDL<br/>+ index analysis"]
    G --> JOB["archive & TTL jobs<br/>Parquet · K8s · Athena"]
    G --> IDX["MODEL_INDEX.md<br/>where everything is"]

For each table, every language gets two files:

• model/generated/<Table> holds the entity, CRUD, relations, declared queries, cursor pagination and validation. It is regenerated and nobody edits it.
• model/<Table> is the only place for custom methods of that table. In C# it is a partial class; in the other languages it is a subclass.

sequenceDiagram
    autonumber
    actor Dev as You
    participant A as kybes:architect
    participant I as kybes:implementer
    participant H as kybes hooks
    participant R as kybes:reviewer
    Dev->>A: "Add suppliers, linked to products"
    A-->>Dev: plan — schema changes, runtimes, reused & new methods
    Dev->>I: implement task 1
    I->>H: Write schemas/db/Fornitori.yaml
    H-->>I: ✓ model regenerated in 4 languages, index updated
    I->>H: Write a query with SQLAlchemy inside a Lambda
    H-->>I: ✗ denied — data access only through the model
    I->>H: Write custom method in model/Fornitori.py
    H-->>I: ✓ allowed (name doesn't collide with generated methods)
    I->>R: done
    R-->>Dev: independent review against the checklist
    Note over H: Stop gate: arch_check + gen --check + tests must pass,<br/>otherwise the agent cannot finish

# schemas/db/Ordini.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]

The generator also creates the index (ClienteId, Data) that covers both listByClienteId and DelClienteDal, and records the decision in db/generated/indexes.md.

Every rule can be set to block, warn or off in .claude/kybes.config.json, a file the agent is not allowed to modify.

your-project/
├── schemas/
│   ├── db/<Table>.yaml                  ← yours: the single source of truth
│   ├── openapi.yaml                     ← yours: custom endpoints (one operationId each)
│   └── generated/                       ← JSON Schemas, merged openapi.yaml
├── libs/db-models/<language>/…/model/
│   ├── <Table>.{cs,py,ts} | <Table>Repository.java   ← yours: custom methods only
│   └── generated/                       ← generator only
├── libs/db-models/<language>/…/api/generated/   ← REST API: controllers, router, validation, adapters
├── libs/db-models/<language>/tests/
│   ├── generated/                       ← ISO 26262-6 unit tests, generator only
│   └── custom/                          ← yours: tests of your custom methods
├── docs/generated/verification/         ← requirements, test specs, traceability, coverage policy
├── db/generated/ddl/postgres/_all.sql   ← DDL, indexes.md
├── db/generated/{athena,synapse}/       ← queries over the Parquet archive
├── jobs/generated/<table>-archive/      ← job config + Kubernetes manifest (CronJob, KEDA, Deployment)
├── jobs/generated/_engine/              ← archive & TTL job engine with its tests and Dockerfile
├── services/<context>/{functions,ms}/   ← Lambda / Kubernetes handlers
├── jobs/  libs/utils/  libs/errors/  frontend/  infra/
├── MODEL_INDEX.md                       ← tables → files → methods
└── .claude/kybes.config.json

The rule: everything under a generated/ folder belongs to the generator; everything else is yours.

From Claude Code (marketplace):

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

Then, inside a project, ask Claude "set up kybes in this project". This runs the kybes:kybes-init skill, which asks for the model languages and creates the configuration, path rules, the CLAUDE.md block, an optional scaffold and the CI workflow. The hooks stay inactive in repositories that have not been set up.

From the command line:

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

The installer is idempotent. Teammates run tools/kybes/setup.sh once after cloning the project.

tests/run.sh installs kybes into throw-away projects and checks the generated code:

The detailed documentation is in Italian, in docs/:

• architecture
• folder map
• schema reference
• generator
• queries & indexes
• pagination
• transactions
• guardrails
• multi-tenancy
• archive & retention
• REST APIs
• MongoDB
• unit verification (ISO 26262-6)
• configuration
• roadmap
• developing the kit

kybes automates the part of ISO 26262-6 that can be automated at software-unit level: requirement-based test derivation, structural coverage criteria per ASIL, and bidirectional traceability. Compliance is still a property of your whole development process (safety plan, hazard analysis, tool qualification, independent reviews), and certification remains your organisation's step.

Ivan Di Lelio · Meta Innovation

MIT: free to use, modify and redistribute, including commercially, as long as the copyright notice is kept.