Xây dựng backend do AI tạo ra có tính nhất quán với kybes

kybes làm gì

kybes là một plugin Claude Code dùng để tạo mã backend có tính nhất quán từ các lược đồ cơ sở dữ liệu YAML. Plugin chuẩn hóa thư mục, tên tệp, phương thức repository, việc xác thực, phân trang, giao dịch, chỉ mục và các bài kiểm thử trên các dự án C#, Python, TypeScript và Java.

Thay vì yêu cầu một tác nhân AI ghi nhớ tài liệu kiến trúc, kybes thực thi kiến trúc thông qua việc tạo mã mang tính xác định, các tác nhân chuyên dụng, quy tắc riêng cho từng thư mục, hook và kiểm tra CI. Cùng một lược đồ sẽ tạo ra đầu ra giống hệt từng byte giữa các dự án.

Quy tắc cốt lõi rất đơn giản: lược đồ là nguồn sự thật duy nhất, không chỉnh sửa thủ công các tệp đã tạo và đặt hành vi tùy chỉnh trong tệp model liên kết với bảng tương ứng.

Cấu trúc được tạo hoạt động như thế nào

Với mỗi bảng, kybes tạo hai lớp model:

• model/generated/<Table> chứa entity được tạo, các thao tác CRUD, quan hệ, truy vấn đã khai báo, phân trang bằng cursor và xác thực. Các tệp này được tạo lại và không nên chỉnh sửa.
• model/<Table> là vị trí an toàn để đặt các phương thức tùy chỉnh. C# sử dụng partial class, còn Python, TypeScript và Java sử dụng cách tiếp cận dựa trên subclass.

Một dự án điển hình cũng bao gồm JSON Schema được tạo, DDL PostgreSQL, phân tích chỉ mục, chỉ mục các tệp model và các artifact xác minh được tạo tự động.

Cài đặt kybes

Cài đặt qua Claude Code

Từ Claude Code, thêm marketplace và cài đặt plugin:

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

Trong dự án đích, yêu cầu Claude Code thiết lập kybes trong dự án này. Skill kybes:kybes-init sẽ hỏi các ngôn ngữ model bạn cần và tạo cấu hình, quy tắc đường dẫn, hướng dẫn CLAUDE.md, scaffold tùy chọn và workflow CI.

Các hook vẫn không hoạt động trong những repository chưa được khởi tạo.

Cài đặt từ dòng lệnh

Bạn cũng có thể clone repository và chạy trình cài đặt:

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

Trình cài đặt có tính lặp an toàn. Sau khi clone một dự án đã được cấu hình, các thành viên trong nhóm chỉ cần chạy tools/kybes/setup.sh một lần.

Kiểm tra yêu cầu

Các hook và trình tạo mã yêu cầu python3 chỉ với thư viện chuẩn. Các runtime được tạo yêu cầu các dependency tương ứng của từng ngôn ngữ:

• C#: net8.0, Entity Framework Core 8 và một provider như Npgsql.
• Python: Python 3.9 trở lên và SQLAlchemy 2.
• TypeScript: TypeORM, reflect-metadata và các tùy chọn trình biên dịch experimentalDecorators cùng emitDecoratorMetadata được bật.
• Java: Jakarta Persistence 3.1, Hibernate 6.2 trở lên và Jackson cho các cột json.

Định nghĩa lược đồ cơ sở dữ liệu

Tạo một tệp YAML trong schemas/db. Ví dụ sau định nghĩa một bảng đơn hàng với số đơn hàng duy nhất, quan hệ bắt buộc với khách hàng, một truy vấn đã khai báo và phân trang bằng cursor có thể sắp xếp:

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]

Lưu tệp với tên schemas/db/Ordini.yaml. Thay đổi lược đồ sẽ kích hoạt việc tạo lại cho các ngôn ngữ đã cấu hình, cập nhật chỉ mục model và tính toán lại các đề xuất về chỉ mục.

Sử dụng API được tạo

Với lược đồ mẫu, kybes tạo các khả năng repository tương đương ở từng ngôn ngữ. Cách đặt tên tuân theo quy ước của ngôn ngữ đích:

• Đọc theo khóa: GetByIdAsync trong C#, get_by_id trong Python và getById trong TypeScript hoặc Java.
• Phân trang bằng cursor: ListPageAsync, list_page hoặc listPage.
• Tra cứu theo cột duy nhất: FindByNumeroAsync, find_by_numero hoặc findByNumero.
• Tra cứu theo khóa ngoại: ListByClienteIdAsync, list_by_cliente_id hoặc listByClienteId.
• Truy vấn đã khai báo: ListDelClienteDalAsync, list_del_cliente_dal hoặc listDelClienteDal.

API được tạo cũng cung cấp các thao tác tạo, cập nhật và xóa có xác thực, các accessor quan hệ và các trang dựa trên cursor được biểu diễn bằng một request cùng một page chứa các item và cursor tiếp theo.

Khai báo truy vấn thay vì viết truy cập dữ liệu trong handler

Đặt các điều kiện truy vấn được hỗ trợ trong lược đồ thay vì import ORM hoặc driver cơ sở dữ liệu vào Lambda, service hoặc controller. kybes hỗ trợ các toán tử gồm eq, ne, lt, lte, gt, gte, in, prefix và is_null.

Trình tạo mã tạo phương thức repository và phân tích đường dẫn truy cập của phương thức đó. Trong ví dụ này, các điều kiện khóa ngoại và ngày dẫn đến một chỉ mục trên (ClienteId, Data). Quyết định này được ghi lại trong db/generated/indexes.md.

Thêm hành vi tùy chỉnh cho model

Khi các phương thức được tạo tự động không đủ, hãy thêm phương thức tùy chỉnh vào tệp model không được tạo tự động, chẳng hạn như model/Fornitori.py hoặc tệp tương đương đối với ngôn ngữ đã chọn. Không chỉnh sửa phần triển khai được tạo tự động.

Phương thức tùy chỉnh không được trùng với tên phương thức được tạo tự động. Ngoài ra, cần có một bài kiểm thử được truy vết trong tests/custom/ trước khi hoàn tất công việc. Định dạng mã định danh kiểm thử dự kiến là TC-<Table>-….

Giữ quyền truy cập dữ liệu bên trong tầng model. Handler nên gọi một phương thức model được tạo tự động hoặc tùy chỉnh, không tự tạo truy vấn SQLAlchemy, Entity Framework, TypeORM hoặc Hibernate.

Hiểu các cơ chế bảo vệ của kybes

Các hook của kybes chạy xuyên suốt quy trình phát triển. Trước khi ghi, chúng có thể chặn việc import ORM hoặc trình điều khiển cơ sở dữ liệu bên ngoài model, chỉnh sửa các tệp được tạo tự động, các thư mục model không hợp lệ, xung đột phương thức và thông tin bí mật ở dạng văn bản thuần.

Sau khi ghi schema, kybes có thể tạo lại model, chạy linter và báo cáo các vấn đề về kiến trúc. Trước khi hoàn tất, agent chính và mọi subagent phải vượt qua kiểm tra kiến trúc, kiểm tra generator, script xác minh và các lệnh kiểm thử của dự án.

Các bước kiểm tra mặc định trước khi dừng bao gồm:

• arch_check, bao gồm phát hiện các khối trùng lặp từ tám dòng trở lên.
• gen --check để xác nhận đầu ra được tạo tự động là hiện hành.
• verify.py cho các bài kiểm thử model và ngưỡng độ bao phủ theo ASIL.
• Các lệnh kiểm thử riêng của dự án.

Các kiểm tra tương tự cũng chạy trong CI với --strict. Có thể cấu hình quy tắc thành block, warn hoặc off trong .claude/kybes.config.json. Agent không được phép chỉnh sửa tệp cấu hình này.

Sử dụng giao dịch, phân trang và chỉ mục an toàn

kybes tạo phân trang bằng con trỏ dựa trên thứ tự mặc định của schema và các cột được phép sắp xếp. Cách này tạo ra một yêu cầu phân trang theo keyset và một trang chứa các mục cùng con trỏ tiếp theo. Định dạng con trỏ được dùng chung giữa các ngôn ngữ được hỗ trợ, giúp các dịch vụ và client khác nhau có thể tương tác với nhau.

Các giao dịch sử dụng Unit of Work với mức cô lập theo từng bảng và cơ chế tự động thử lại khi xảy ra lỗi tuần tự hóa hoặc deadlock. Các đường dẫn truy cập đã khai báo được phân tích để xác định chỉ mục phù hợp; chỉ mục còn thiếu sẽ được tạo và chỉ mục dư thừa sẽ được đánh dấu. Khi phù hợp, các tìm kiếm theo tiền tố có thể sử dụng varchar_pattern_ops của PostgreSQL.

Cấu hình đa thuê bao

Có thể cấu hình đa thuê bao cho từng bảng bằng một trong các chiến lược được hỗ trợ:

• Cột tenant, trong đó mọi phương thức được tạo tự động đều được lọc và các ràng buộc duy nhất được giới hạn theo từng tenant.
• Bảo mật cấp hàng của PostgreSQL.
• Một schema cho mỗi tenant.
• Một cơ sở dữ liệu cho mỗi tenant.

Tenant được gắn với phiên ORM và kybes tạo các bài kiểm thử cô lập cho chiến lược đã cấu hình.

Xem lại bố cục dự án được tạo tự động

Một dự án đã cấu hình tuân theo cấu trúc có thể dự đoán:

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

Mọi thứ bên trong thư mục generated/ đều thuộc về kybes. Các tệp model khác, kiểm thử tùy chỉnh, schema và mã ứng dụng do đội ngũ của bạn duy trì theo các quy tắc đã cấu hình.

Xác minh kết quả

Kho mã bao gồm các quy trình xác minh dành cho mã được tạo tự động, hook, SQL và hành vi liên ngôn ngữ. Các bài kiểm thử bao phủ CRUD, quan hệ, cascade, ràng buộc duy nhất, các trường hợp biên của phân trang, toán tử truy vấn và hành vi của Unit of Work.

Các bài kiểm thử đơn vị được tạo tự động sẽ suy ra yêu cầu và ca kiểm thử từ từng schema. Quy trình xác minh bao gồm các lớp tương đương, giá trị biên, dự đoán lỗi, MC/DC cho ASIL C và D, khả năng truy vết và các bước kiểm tra độ bao phủ theo từng bảng. Kho mã cũng kiểm tra rằng DDL PostgreSQL được tạo tự động có thể phân tích cú pháp chính xác và các con trỏ do một ngôn ngữ được hỗ trợ tạo ra có thể được các ngôn ngữ khác chấp nhận.

Đối với công việc quan trọng về an toàn, kybes tự động hóa một phần ISO 26262-6 ở cấp đơn vị phần mềm, nhưng không thay thế kế hoạch an toàn đầy đủ, phân tích mối nguy, đánh giá chất lượng công cụ, đánh giá độc lập hoặc quy trình chứng nhận của tổ chức.

Kết luận

kybes cung cấp quy trình schema-first cho các backend được AI tạo tự động với tính nhất quán cao. Chỉ cần định nghĩa bảng, quan hệ, truy vấn, phân trang và quy tắc thuê bao một lần; để generator xác định tạo các model, chỉ mục, DDL, cơ chế xác thực và bài kiểm thử theo từng ngôn ngữ; sau đó đặt hành vi tùy chỉnh trong tầng model được phê duyệt.

Với các agent Claude Code, hook tại thời điểm ghi, tính năng phát hiện mã trùng lặp, quy trình xác minh được tạo tự động và các bước kiểm tra CI nghiêm ngặt, dự án vẫn nhất quán ngay cả khi cơ sở mã và ngữ cảnh AI ngày càng lớn. Để xem tài liệu tham khảo chuyên sâu hơn, hãy khám phá tài liệu và kho mã nguồn của dự án.