docs: rewrite JsonRpcBundle docs, add SDK docs, move them under docs/api
uk/docs/api/json-rpc-bundle/developers/ai.md
новий файл +51
−0
1
+
# Правила для ШІ-асистентів
2
+
3
+
Claude Code, Codex, Cursor, Copilot та інші асистенти пишуть код краще, коли знають правила роботи з бібліотекою. Ми підготували файли інструкцій, які підключаються до вашого проєкту поруч із наявними правилами — без заміни вашого `AGENTS.md` чи `CLAUDE.md`.
4
+
5
+
## Файли
6
+
7
+
| Файл | Для чого | Завантажити |
8
+
| --- | --- | --- |
9
+
| `json-rpc-bundle.md` | Проєкти, що надають API через JsonRpcBundle: як агенту працювати з бібліотекою, правила для процедур, параметрів, результатів, помилок, кешу, версій і груп API, подій, відомі пастки, перевірка результату | <a href="/assets/ai/json-rpc-bundle/json-rpc-bundle.md" download="json-rpc-bundle.md">json-rpc-bundle.md</a> |
10
+
| `json-rpc-bundle-extensions.md` | Пакети-розширення бандла: точка входу через `RpcExecutor`, токени, групи й версії, маршрути, обмеження компіляції, вимоги до пакета | <a href="/assets/ai/json-rpc-bundle/json-rpc-bundle-extensions.md" download="json-rpc-bundle-extensions.md">json-rpc-bundle-extensions.md</a> |
11
+
| `ufo-code-style.md` | Необов'язково: стиль коду команди UFO-Tech — для проєктів, що його приймають | <a href="/assets/ai/json-rpc-bundle/ufo-code-style.md" download="ufo-code-style.md">ufo-code-style.md</a> |
12
+
13
+
Файли англійською: асистенти стабільніше виконують англомовні інструкції. Правила написано для версії бандла **10.4**.
14
+
15
+
## Як підключити
16
+
17
+
Покладіть файл у репозиторій, наприклад у `docs/ai/`:
18
+
19
+
```bash
20
+
mkdir -p docs/ai
21
+
curl -o docs/ai/json-rpc-bundle.md https://ufo-tech.space/assets/ai/json-rpc-bundle/json-rpc-bundle.md
22
+
```
23
+
24
+
і додайте посилання на нього у файл інструкцій, який уже є у вашому проєкті:
25
+
26
+
| Асистент | Що додати |
27
+
| --- | --- |
28
+
| Codex, Cursor, Zed та інші з підтримкою [AGENTS.md](https://agents.md) | у ваш `AGENTS.md` рядок: `When working with JSON-RPC procedures, follow docs/ai/json-rpc-bundle.md.` |
29
+
| Claude Code | у ваш `CLAUDE.md` рядок `@docs/ai/json-rpc-bundle.md` (імпорт) |
30
+
| GitHub Copilot | файл `.github/instructions/json-rpc-bundle.instructions.md` з вмістом правил і `applyTo` для каталогу процедур |
31
+
| Cursor (правила проєкту) | файл `.cursor/rules/json-rpc-bundle.mdc` з вмістом правил |
32
+
33
+
Ваші наявні правила лишаються головними: файл бандла не перевизначає стиль чи архітектуру проєкту, а лише описує роботу з бібліотекою.
34
+
35
+
## Що всередині
36
+
37
+
**Як агенту працювати** — на початку файлу:
38
+
39
+
* джерело правди — встановлений код бандла у `vendor/` і описи релізів у `vendor/ufo-tech/json-rpc-bundle/releases/`, а не пам'ять моделі;
40
+
* перевіряти встановлену версію; не вигадувати класи, атрибути, опції; про суперечність правил і коду — повідомляти;
41
+
* не змінювати публічні RPC-контракти без потреби (несумісні зміни — нова версія API) і не рефакторити поза задачею.
42
+
43
+
**Правила бібліотеки** — коротко, з посиланнями на документацію замість пояснень: тонкі процедури, DTO і декларативна валідація, формат результату, помилки, кеш, версії та групи API, події.
44
+
45
+
**Відомі пастки 10.4** — застарілі атрибути й події, `#[RPC\DTOCollection]` на методі, `ttl` для `#[RPC\Lock]`, особливості подій для Messenger і помилок HTTP (див. [Актуальні помилки](/docs/api/json-rpc-bundle/developers/known_issues/open)).
46
+
47
+
**Перевірка перед завершенням** — тести, виклик зміненого методу, схема в `GET /rpc`.
48
+
49
+
:::info subtitle="Чому це не документація"
50
+
Файл навмисно не пояснює, як працюють механізми, — для цього є документація, на яку він посилається. Так інструкція лишається короткою і не перетворюється на другу копію документації, яка з часом розійдеться з першою.
51
+
:::