# Документация для агентов

> Документация в виде обычного текста и порождённый список символов — для кодовых ассистентов.

Source: https://ormgo.vercel.app/ru/docs/agents/
Symbols: https://ormgo.vercel.app/api/orm.txt — the generated list of every exported name.

---
## Что доступно

Всё, что есть на этом сайте, публикуется и обычным текстом: кодовый ассистент
получает один URL и то, что за ним лежит, — а за страницей иначе лежит
React-приложение.

| URL | Что это |
| --- | --- |
| [`/llms.txt`](/llms.txt) | Указатель. Каждая страница — одной строкой, с описанием. |
| [`/llms-full.txt`](/llms-full.txt) | Вся английская документация целиком, в порядке навигации. Один запрос. |
| [`/llms-full.ru.txt`](/llms-full.ru.txt) | То же на русском. |
| [`/api/orm.txt`](/api/orm.txt) | Каждый экспортированный символ библиотеки. |
| `…/<страница>.md` | Любая страница как её исходный markdown. |

Последнее — суффикс, а не отдельный сайт. Допишите `.md` к адресу страницы и
получите тот markdown, из которого она отрисована:

```text
https://ormgo.vercel.app/en/docs/projections/      the page
https://ormgo.vercel.app/en/docs/projections.md    its source
```

Каждая отрисованная страница к тому же объявляет свой markdown ссылкой
`rel="alternate"`, так что инструменту, который такие ссылки ищет, не нужно
заранее знать соглашение.

## Начинать стоит со списка символов

Если читать один файл — читайте [`/api/orm.txt`](/api/orm.txt).

Каждая строка кода, написанная под библиотеку, — это догадка о том, какие имена
существуют, и дорого обходятся именно правдоподобные догадки. `orm.Returning`
выглядит как функция — а это обобщённый тип. `EqCol` выглядит как очевидный
способ сравнить две колонки. `Users.Table()` выглядит как то, что есть у любой
ORM. Ничего из этого здесь нет, и по форме запроса это не видно до тех пор, пока
не скажет компилятор.

`orm.txt` порождается из самих пакетов тем же инструментом, которым CI сравнивает
публичный API, поэтому он исчерпывающий, а не выборочный:

```text
package github.com/AlexAli29/orm
const BoundEmpty BoundKind = 0
func Project12[E any, T1 any, ...](...)
method (*ViewRepo) Query() *Query[E]
```

Правило, которое из этого следует, достаточно короткое, чтобы отдать его
ассистенту как есть: **если имени нет в `orm.txt` — его не существует.**
Правдоподобие тут ничего не меняет, а проверка — это поиск, а не сборка.

Два меньших манифеста покрывают пакеты, которые не являются самой ORM:
[`/api/ormtest-postgres.txt`](/api/ormtest-postgres.txt) — тестовые помощники, а
[`/api/ormotel.txt`](/api/ormotel.txt) — интеграция с OpenTelemetry.

## Как направить инструмент

Большинство ассистентов читают файл с инструкциями проекта — `CLAUDE.md`,
`AGENTS.md`, правило Cursor. Трёх строк в таком файле достаточно:

```text
This project uses github.com/AlexAli29/orm.

Docs:    https://ormgo.vercel.app/llms.txt
Symbols: https://ormgo.vercel.app/api/orm.txt

Before using any orm.* name, confirm it appears in api/orm.txt. If it is not
there it does not exist, however plausible it looks. Do not guess at method
names on generated columns — the generator decides them, and the manifest
lists them.
```

По умолчанию лучше указывать на `llms.txt`, а не на `llms-full.txt`: указатель
маленький и позволяет ассистенту забрать ровно ту страницу, которая нужна,
вместо того чтобы носить с собой весь справочник. `llms-full.txt` пригодится,
когда инструмент не умеет ходить по ссылкам или когда проще заплатить один раз
за всё сразу.

## Что порождается и когда

Ничего по этим адресам не написано руками. Список страниц — это навигация самого
сайта, текст — тот же markdown, из которого рендерятся страницы, а манифесты
копируются из репозитория, где CI перегенерирует и сравнивает их при каждом
изменении публичного API.

Отсюда следствие, которое стоит сказать прямо: текстовая документация не может
отстать от сайта, потому что собирается из него в том же шаге. Она может быть
настолько же свежей, насколько свеж деплой, — та же гарантия, что и у HTML.

## Разобранные примеры

### Проверить имя до того, как его использовать

Вопрос, который ассистенту стоит задать перед тем, как написать `orm.Something`:

```text
$ curl -s https://ormgo.vercel.app/api/orm.txt | grep '^type Returning'
type Returning[E any, R any] struct
```

Это тип, причём с двумя параметрами, — значит, вызова `orm.Returning(Summaries)`
не существует, а добраться до него можно через `orm.UpdateReturning(upd, shape)`.
Манифест сказал это раньше компилятора.

### Забрать одну страницу вместо всего справочника

Ассистенту, которого попросили добавить материализованное представление, нужна
одна страница, а не тридцать:

```text
https://ormgo.vercel.app/en/docs/views.md
```

Файл начинается с заголовка страницы, её описания, канонического адреса и ссылки
на список символов, дальше идёт markdown — двадцатая часть того, во что обошёлся
бы весь справочник.

### Отдать ревьюеру всё сразу

Проходу по большому диффу нужен весь справочник в контексте и не нужны тридцать
запросов:

```text
https://ormgo.vercel.app/llms-full.txt
```

Один файл, все английские страницы, в порядке навигации.

### Работа на русском

Русская документация — перевод текста, а не кода: каждый пример побайтово
совпадает в обеих языковых версиях, и это проверяется тестом. Ассистент, читающий
`/llms-full.ru.txt`, получает русские объяснения того же Go, что и в английских
страницах:

```text
https://ormgo.vercel.app/llms.ru.txt
https://ormgo.vercel.app/llms-full.ru.txt
```