Лучшие практики

Описание ссылки — контекст для LLM. От него зависит, загрузит ли модель страницу.

❌ Плохо:

- [Docs](https://example.com/docs): Документация
- [API](https://example.com/api): API
- [Guide](https://example.com/guide): Гайд

✅ Хорошо:

- [Quick Start](https://example.com/docs/start): Установка, конфигурация и первый запуск за 5 минут
- [REST API](https://example.com/api/rest): Аутентификация, эндпоинты, примеры запросов и ответов
- [Migration Guide](https://example.com/docs/migrate): Обновление с v2 на v3, breaking changes

Правила описаний:

• Конкретность — что именно найдёт LLM на странице
• Ключевые слова — термины, по которым LLM будет искать
• Уникальность — каждое описание отличается от других
• Длина — 10-20 слов, достаточно для понимания контекста

При большом количестве ссылок (ориентир — более 50) эффективность падает. LLM должна просканировать весь файл — чем больше ссылок, тем больше «разбавлен» каждый ресурс. Точный порог зависит от модели и контекстного окна.

Оптимальная структура:

• 3-6 секций
• 5-15 ссылок на секцию
• 20-50 ссылок всего

Для сравнения: средний сайт документации — 500K+ токенов в HTML. llms.txt даёт ту же структурную информацию в 1-4K токенов. Экономия контекста: 99%+.

❌ 12 секций по 2-3 ссылки — плохо. Визуальный шум без пользы.

✅ 4-6 секций с логической группировкой.

❌  - [Auth](https://example.com/auth)
✅  - [Auth](https://example.com/auth): OAuth 2.0, JWT-токены, управление сессиями

Без описания LLM не знает, стоит ли загружать страницу.

Ссылки на несуществующие страницы — хуже, чем отсутствие llms.txt. LLM «тратит» обращение на 404.

Не включайте в llms.txt то, что не должно быть публичным:

• /admin/, /internal/
• Staging-URL
• Страницы за аутентификацией

llms.txt ведёт на удалённые или перенесённые страницы. Регенерируйте файл при изменении структуры сайта.

sitemap.xml — полный список всех URL для поисковых краулеров. llms.txt — курированный набор ключевых страниц с описаниями. Это разные инструменты для разных задач.

Не включайте в llms.txt:

• Internal/admin URL
• Staging/dev-среды
• API-ключи и credentials
• Приватную документацию
• URLs с токенами аутентификации

llms.txt — публичный файл. Всё, что вы туда добавляете, видит весь интернет.

Перед публикацией проверьте:

• Заголовок H1 — название проекта
• Blockquote — краткое описание (1-2 предложения)
• Все ссылки рабочие (нет 404)
• Каждая ссылка имеет описание
• Нет дублирующихся ссылок
• Нет internal/admin URL
• Секция Optional — только второстепенные ресурсы
• Размер файла < 8K токенов

#!/bin/bash
# validate-llms-txt.sh — проверка llms.txt

FILE="${1:-llms.txt}"

echo "Validating: $FILE"
echo "---"

# H1 check
if grep -q '^# ' "$FILE"; then
  echo "✓ H1 title found"
else
  echo "✗ Missing H1 title"
fi

# Blockquote check
if grep -q '^> ' "$FILE"; then
  echo "✓ Blockquote found"
else
  echo "⚠ No blockquote (recommended)"
fi

# Link count
LINKS=$(grep -c '^\- \[' "$FILE")
echo "  Links: $LINKS"

# Links without descriptions
NO_DESC=$(grep '^\- \[' "$FILE" | grep -cv ':')
if [ "$NO_DESC" -gt 0 ]; then
  echo "⚠ $NO_DESC links without descriptions"
else
  echo "✓ All links have descriptions"
fi

# Check for broken URLs
echo "Checking URLs..."
grep -oP 'https?://[^\)]+' "$FILE" | while read -r url; do
  STATUS=$(curl -s -o /dev/null -w "%{http_code}" --max-time 5 "$url")
  if [ "$STATUS" != "200" ]; then
    echo "  ✗ $STATUS $url"
  fi
done

echo "---"
echo "Done."

• Добавлена/удалена страница документации
• Изменена структура сайта
• Переехали URL (redirect)
• Крупный релиз продукта

Для фреймворков с плагинами (Astro, MkDocs, Nuxt) — llms.txt генерируется автоматически при каждом билде.

Для остальных — добавьте шаг в CI/CD:

name: Update llms.txt
on:
  push:
    paths: ['docs/**']
jobs:
  update:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - run: npx llmstxt gen https://example.com/sitemap.xml > public/llms.txt
      - run: |
          git add public/llms.txt
          git diff --staged --quiet || git commit -m "Update llms.txt"
          git push

Периодически проверяйте ссылки в llms.txt. Используйте скрипт из чеклиста выше или инструменты вроде linkchecker.