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

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

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

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

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.

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

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

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/ormotel.txt — интеграция с OpenTelemetry.

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

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

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:

$ 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). Манифест сказал это раньше компилятора.

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

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

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

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

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

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

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

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

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

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

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