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

> Практическое руководство по подготовке технической документации так, чтобы её надёжно понимали языковые модели и агенты — Markdown-версии страниц, llms.txt, структура, примеры и MCP-доступ.

Источник: https://llmdocs.ru/wiki/docs-for-ai/ · обновлено 2026-11-09 · лицензия CC BY-SA 4.0

- **Цель**: документация, которую одинаково хорошо читают люди и языковые модели
- **Форматы**: Markdown-копии страниц, llms.txt, llms-full.txt
- **Доступ для агентов**: MCP-серверы документации, поиск, API
- **Принципы**: самодостаточные разделы, явный контекст, проверяемые примеры, актуальность
- **Связанные подходы**: Diátaxis, docs-as-code, RAG
**Документация для ИИ** — набор практик, которые делают техническую документацию удобной не только для людей, но и для [языковых моделей](https://llmdocs.ru/wiki/llm.md) и [агентов](https://llmdocs.ru/wiki/ai-agent.md). Всё больше разработчиков узнают, как пользоваться библиотекой или API, не со страницы сайта, а из ответа ассистента или [агента для кода](https://llmdocs.ru/wiki/coding-agents.md), который сам ищет и читает документацию. Если документация плохо доступна моделям, они опираются на устаревшие знания из обучающих данных и чаще ошибаются.

Хорошая новость: почти всё, что помогает моделям, помогает и людям — ясная структура, полные примеры, явный контекст.

## Почему модели читают документацию иначе

- **Нет навигации и вёрстки.** Модель получает текст страницы — часто вместе с меню, рекламой, скриптами и куками, — и всё это тратит [контекст](https://llmdocs.ru/wiki/context-window.md).
- **Фрагменты без окружения.** Системы [RAG](https://llmdocs.ru/wiki/rag.md) режут документы на фрагменты, и фрагмент «Затем вызовите `init()` с этим параметром» без заголовка и соседних абзацев теряет смысл.
- **Буквальность.** Модель воспроизведёт пример кода дословно — включая устаревший импорт или пропущенный шаг.
- **Знания из обучения.** Модель «помнит» старые версии API и смешивает их с новыми, если документация не говорит явно, что изменилось.

## Форматы для машин

### Markdown-версии страниц

Публикуйте рядом с каждой HTML-страницей её чистую версию в [Markdown](https://llmdocs.ru/wiki/markdown.md) — например, по тому же адресу с расширением `.md`. Markdown сохраняет структуру (заголовки, списки, таблицы, код с указанием языка) и при этом в несколько раз компактнее HTML (см. [Markdown как формат для LLM](https://llmdocs.ru/wiki/markdown-for-llm.md)). Генераторы статических сайтов легко выдают обе версии из одного источника ([Статический сайт и генераторы (SSG)](https://llmdocs.ru/wiki/static-site-generators.md)).

### llms.txt

Файл [llms.txt](https://llmdocs.ru/wiki/llms-txt.md) в корне сайта — карта документации для моделей: название проекта, краткое описание и список ключевых страниц со ссылками на Markdown-версии и пояснением в одну строку.[1] Часто рядом кладут `llms-full.txt` — всю документацию одним файлом для загрузки в контекст целиком.

```markdown
# Acme SDK

> Python-библиотека для работы с API платёжного сервиса Acme.

## Документация
- [Быстрый старт](https://docs.acme.dev/quickstart.md): установка и первый платёж
- [Аутентификация](https://docs.acme.dev/auth.md): ключи API и OAuth
- [Ошибки](https://docs.acme.dev/errors.md): коды ошибок и повторы

## Optional
- [История изменений](https://docs.acme.dev/changelog.md)
```

### Доступ для агентов

Агенты всё чаще получают документацию не по ссылке, а через инструменты: MCP-сервер документации даёт поиск и чтение страниц по запросу ([Model Context Protocol (MCP)](https://llmdocs.ru/wiki/mcp.md)).[4] Так агент берёт только нужный раздел актуальной версии, не загружая весь сайт.

## Как писать

1. **Самодостаточные разделы.** Каждый раздел должен быть понятен без чтения предыдущих: повторите в начале, о каком продукте и версии идёт речь, а не полагайтесь на «как описано выше». Это напрямую улучшает поиск по фрагментам; та же идея лежит в основе подхода Contextual Retrieval, где к каждому фрагменту добавляется краткий контекст документа.[3]
2. **Описательные заголовки.** «Повтор запросов при ошибке 429» вместо «Дополнительно». Заголовок — главный сигнал для поиска и нарезки на фрагменты ([Чанкинг документов](https://llmdocs.ru/wiki/chunking.md)).
3. **Полные, проверяемые примеры.** Код с импортами, установкой зависимостей и ожидаемым выводом; примеры прогоняются в CI, чтобы не устаревали.
4. **Явные версии и изменения.** Указывайте, с какой версии доступна функция, что устарело и чем заменить. Страница миграции «было → стало» особенно ценна для моделей с устаревшими знаниями.
5. **Однозначные определения.** Термины определяются один раз и используются единообразно; синонимы для одного понятия путают и людей, и модели.[5]
6. **Типы документов не смешиваются.** Разделение на обучающие материалы, практические инструкции, справочник и объяснения (подход Diátaxis) помогает и человеку, и модели найти нужный вид информации.[2]
7. **Ограничения и ошибки.** Пишите, чего библиотека *не* умеет и какие ошибки бывают, — иначе модель додумает.

## Технические детали

- Чистый CommonMark с таблицами и блоками кода с указанием языка; без нестандартных расширений, которые превращаются в мусор вне вашего сайта.[6]
- Стабильные URL и редиректы со старых адресов — модели и поисковые индексы помнят старые ссылки.
- Не закрывайте документацию от ботов без необходимости: проверьте `robots.txt` и защиту от ботов, которые могут блокировать агентов (см. [robots.txt и sitemap](https://llmdocs.ru/wiki/robots-sitemap.md)).
- Справочник API — из машиночитаемого описания (OpenAPI), чтобы он не расходился с реальностью.
- Дата обновления и версия на каждой странице.

## Как проверить

Лучший тест — спросить модель. Подайте ей Markdown-версию раздела или подключите MCP-сервер и попросите решить типичную задачу пользователя: установить библиотеку, сделать первый запрос, обработать ошибку. Ошибки модели показывают, где документация неполна или двусмысленна. Набор таких задач можно запускать регулярно как тесты документации (см. [Оценка LLM (evals)](https://llmdocs.ru/wiki/llm-evals.md)).

## Пример

Эта вики устроена по описанным принципам: каждая статья хранится в Markdown с метаданными, сайт публикует HTML и Markdown-копии всех страниц, файлы `llms.txt` и `llms-full.txt`, а статьи написаны как самодостаточные разделы со ссылками на первоисточники. Похожий подход используют справочники [tldr-pages](https://llmdocs.ru/wiki/tldr-pages.md) — короткие страницы единого формата с проверяемыми примерами.

## См. также

- [llms.txt](https://llmdocs.ru/wiki/llms-txt.md)
- [Markdown как формат для LLM](https://llmdocs.ru/wiki/markdown-for-llm.md)
- [RAG (генерация с дополнением поиском)](https://llmdocs.ru/wiki/rag.md)
- [Model Context Protocol (MCP)](https://llmdocs.ru/wiki/mcp.md)
- [Статический сайт и генераторы (SSG)](https://llmdocs.ru/wiki/static-site-generators.md)

## Источники

1. [llms.txt — предложение стандарта (Jeremy Howard, 2024)](https://llmstxt.org/)
2. [Diátaxis — систематический подход к технической документации](https://diataxis.fr/)
3. [Anthropic — Introducing Contextual Retrieval (2024)](https://www.anthropic.com/news/contextual-retrieval)
4. [Model Context Protocol — Specification](https://modelcontextprotocol.io/specification)
5. [Google developer documentation style guide](https://developers.google.com/style)
6. [CommonMark Spec](https://spec.commonmark.org/)