Большую часть документации к SDK пишут для человека, который читает её во вторник в два часа дня. Но всё чаще первым её читает ИИ-ассистент для кода, и у него другая задача: ему нужна уверенность, а текст уверенности не даёт.
Раньше я решал это так: публиковал весь справочник по SDK одним текстовым файлом, чтобы ассистент забирал его за один запрос. Идея была разумной, но со временем себя не оправдала. Сплошной текст остаётся текстом: ассистент читает его, сжимает, а через несколько сотен строк пишет имя метода, которого в файле никогда не было. К тому же документ, который ведут параллельно с кодом, со временем расходится с ним, а этого справочник как раз не может себе позволить.
Его заменили две вещи, и обе строже.
Справочник — это типы
@kookee/sdk поставляется с объявлениями типов TypeScript. Установите пакет, и справочник окажется на диске, в контексте ассистента, в форме, которую нельзя запомнить неправильно:
npm install @kookee/sdkТеперь промпт короткий, потому что точность живёт в типах, а не в промпте:
Сделайте блог на пакете
@kookee/sdk, он уже установлен. Страница списка (/blog) с фильтром по тегам, поиском и пагинацией и страница поста (/blog/:slug) с отрендеренным HTML и эмодзи-реакциями. Next.js App Router, загрузка данных в серверных компонентах. Ключ читайте изprocess.env.KOOKEE_API_KEY.
Ассистент пишет kookee.blog.list({ page, limit, tags, search, locale }), потому что такова сигнатура, а не потому, что вспомнил абзац. А когда я меняю метод, объявления меняются в том же релизе: второго документа, который можно забыть обновить, нет. Это и был главный довод против текстового файла: он мог ошибаться, а справочник, который может ошибаться, хуже, чем его отсутствие, потому что ему доверяют.
Структура ответа, под которую он пишет код, та же, что получаете вы:
const response = await kookee.blog.list({ page: 1, limit: 10, tags: ['engineering'] });
response.data; // BlogEntryListItem[]
response.total; // 25
response.totalPages; // 3Если вы хотите вставить готовые страницы, а не генерировать их, в @kookee/react есть компоненты блога с серверным рендерингом: подробнее в статье Блог на готовых React-компонентах.
Вторая половина — контент
Типы говорят ассистенту, что он может вызвать. О том, что лежит в вашем проекте, они не говорят ничего, а половина ошибок первой интеграции берётся именно оттуда: slug категории, которой нет, поле, которое код никогда не читает, пустая страница, за которой оказывается пустой проект.
Поэтому подключите ассистента к настоящим данным:
claude mcp add --transport http kookee https://api.kookee.dev/api/mcp \
--header "Authorization: Bearer $KOOKEE_MCP_TOKEN"Теперь промпт выглядит иначе. Вместо «Сделайте страницу журнала изменений» получается:
Прочитайте мои записи журнала изменений, потом сделайте страницу, которая выводит их с учётом их настоящей структуры.
И он действительно их читает. Он обнаруживает, что тип релиза лежит в массиве fields, а не в самой записи, что у двух записей не указана версия, что категории у вас названы по одному принципу, а теги по другому. Страница, которую он пишет, подходит к вашим данным, а не к общему примеру. А ещё он умеет записывать, так что если заметит, что чего-то не хватает, может сам это исправить.
Что ещё понадобится
Проект Kookee хотя бы с одним опубликованным постом. Пустой проект даёт пустую страницу, и её трудно отличить от бага.
API-ключ для приложения из Подключения → API-ключи. Он видит только опубликованный контент, поэтому его безопасно держать в клиентском бандле.
Личный MCP-токен из Подключения → MCP-сервер, если хотите, чтобы ассистент читал ваш настоящий контент. Для этого хватит доступа Только чтение. И всё же не кладите токен в код: он читает ваши черновики.
Не только блог
Та же схема работает для каждого раздела:
Сделайте центр помощи с навигацией по категориям, семантическим поиском и страницами статей.
Сделайте страницу журнала изменений с группировкой по типу релиза и эмодзи-реакциями.
Делайте их по одному. Три сразу дают дифф, который никто не просматривает внимательно, и так в продакшен уходит баг в коде, который выглядел правильно.
Общая мысль: не просите ассистента помнить ваш API, дайте ему то, что нельзя запомнить неправильно. Типы и сами данные.