예측 가능한 AI 생성 백엔드를 kybes로 구축하기

kybes의 기능

kybes는 YAML 데이터베이스 스키마에서 예측 가능한 백엔드 코드를 생성하는 Claude Code 플러그인입니다. C#, Python, TypeScript, Java 프로젝트 전반에서 폴더, 파일 이름, 리포지토리 메서드, 유효성 검사, 페이지 매김, 트랜잭션, 인덱스, 테스트를 표준화합니다.

AI 에이전트에게 아키텍처 문서를 기억하도록 요청하는 대신, kybes는 결정적 생성, 전용 에이전트, 폴더별 규칙, 훅, CI 검사를 통해 아키텍처를 강제합니다. 동일한 스키마는 프로젝트 전반에서 바이트 단위로 동일한 생성 결과를 만듭니다.

핵심 규칙은 간단합니다. 스키마가 단일 진실 공급원이며, 생성된 파일은 수동으로 편집하지 않고, 사용자 지정 동작은 해당 테이블과 연결된 모델 파일에 작성합니다.

생성된 구조의 작동 방식

kybes는 각 테이블에 두 개의 모델 계층을 생성합니다.

• model/generated/<Table>에는 생성된 엔터티, CRUD 작업, 관계, 선언된 쿼리, 커서 페이지 매김, 유효성 검사가 포함됩니다. 이 파일은 다시 생성되므로 편집해서는 안 됩니다.
• model/<Table>은 사용자 지정 메서드를 작성하는 안전한 위치입니다. C#에서는 partial 클래스를 사용하고, Python, TypeScript, Java에서는 서브클래스 기반 방식을 사용합니다.

일반적인 프로젝트에는 생성된 JSON 스키마, 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: 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 컨텍스트가 커져도 프로젝트의 일관성을 유지할 수 있습니다. 더 자세한 참고 자료는 프로젝트의 문서와 소스 저장소에서 확인할 수 있습니다.