Исполняемые навыки для агентов лучше документации

57% команд документации не отслеживают, приводит ли их документация к каким-либо бизнес-результатам. 88% говорят, что документация важна для решений о покупке. (GitBook State of Docs 2026.) При этом почти половина всего трафика сайтов документации теперь приходит от AI-агентов — которые не могут сказать вам, нашли ли они то, что им было нужно (Mintlify).

Аудитория документации изменилась. Формат — нет.

Автор изменился

На протяжении десятилетий процесс был простым: человек писал спецификацию, затем реализовывал код в соответствии с ней. Документация была источником истины.

Этот порядок перевернулся. AI-агенты генерируют код и документацию одновременно, в формате, предназначенном для потребления другими агентами. Спецификация и реализация теперь — один и тот же артефакт.

graph TD
  subgraph era1 ["До 2025"]
      direction LR
      A["Разработчик пишет документацию"] --> B["Разработчик реализует код"]
  end
  subgraph era2 ["2023–2026"]
      direction LR
      C["AI-агент генерирует код"] --> D["AI-агент обновляет документацию"]
  end
  subgraph era3 ["2026+"]
      direction LR
      E["AI-агент генерирует документацию + код"] --> F["Другой агент потребляет навыки"]
  end
  B -.-> C
  D -.-> E

Первое поколение документации, ориентированной на агентов — OpenWiki, Mintlify, AGENTS.md — решило реальную проблему: агентам нужен контекст о незнакомых кодовых базах. Но решение породило новую проблему: генерация человекочитаемых сводок кода для агента, который и так умеет читать код. Посредник избыточен, но требует обслуживания.

Текущие подходы не работают

Современная экосистема документации предлагает четыре подхода. Каждый проваливается по-своему.

graph LR
  A["Традиционная документация"] -->|"Написана для людей"| B["Её никто не читает"]
  B --> C["Устаревшая, не поддерживается"]

  D["Документация из кода"] -->|"Сгенерирована для агентов"| E["Агенты могут читать код напрямую"]
  E --> F["Лишний посредник"]

  G["Спецификации"] -->|"Всеобъемлющие спецификации"| H["Размывание контекста снижает производительность"]
  H --> I["Контрпродуктивно"]

Chroma исследовал 18 LLM в июле 2025 и обнаружил, что «производительность модели значительно варьируется при изменении длины входных данных, даже на простых задачах» — явление, которое они назвали размыванием контекста (Chroma Technical Report). Руководство Anthropic по контекст-инженерии (сентябрь 2025) описывает ту же проблему: «У LLM есть «бюджет внимания», который они расходуют при парсинге больших объёмов контекста. Каждый новый токен истощает этот бюджет» (Anthropic).

ThoughtWorks Technology Radar Vol 34 (апрель 2026) отметил разбухание инструкций для агентов как «Осторожно»: «Контекстные файлы вроде AGENTS.md и CLAUDE.md склонны накапливаться со временем… Инструкции становятся длинными и иногда противоречат друг другу. Модели уделяют меньше внимания контенту, погребённому в середине длинных контекстов» (ThoughtWorks).

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

Проблема не в том, что документация плохо написана. Проблема в том, что каждая страница документации дублирует код, который лежит рядом.

Документация из кода решает проблему «почему» — сооснователь Mintlify Хан Ван: «Код только говорит, что было сделано, но не почему.» Но решение вносит устаревание, обслуживание и стоимость токенов. Каждая страница документации — производная от кода рядом. Для агента, который может прочитать код, производная избыточна.

ThoughtWorks Technology Radar Vol 34 оценил контекст-инженерию как «Принять» и прогрессивное раскрытие контекста как «Попробовать» — рекомендация: «Начните с лёгкого индекса того, что доступно, позвольте агенту определить, что актуально, и подгружайте только необходимое» (ThoughtWorks).

Навыки вместо документации

Альтернатива генерации документации — генерация навыков.

graph TD
  subgraph trad ["Традиционная документация"]
      direction LR
      A1["Человек пишет"] --> A2["Markdown-файл"]
      A2 --> A3["Агент читает как контекст"]
  end
  subgraph code ["Документация из кода"]
      direction LR
      B1["Код существует"] --> B2["Агент генерирует markdown"]
      B2 --> B3["Другой агент читает markdown"]
  end
  subgraph skill ["Навыки"]
      direction LR
      C1["Эксперт общается"] --> C2["Агент генерирует навык"]
      C2 --> C3["Человек проверяет"]
      C3 --> C4["Песочница VM выполняет"]
  end
  A3 -.-> B1
  B3 -.-> C1

Навыки используют ту же упаковку, что и документация — markdown, YAML frontmatter, структурированные ссылки. Но их потребители — агенты, а не люди. Ключевое отличие: они содержат исполняемые TypeScript-функции, которые запускаются в песочнице VM на каждое входящее сообщение клиента.

Владелец спа пишет: «наша глубокая тканевая массаж стоит $90 за 60 минут, $120 за 90 минут, и мы предлагаем скидку 10% для членов клуба.» Платформа генерирует функцию quoteOrder(), которая возвращает $108 за бронирование на 90 минут для члена клуба. Каждый раз.

export function quoteOrder(order: Order): QuoteResult {
  const item = order.items[0];
  const base = offerings[item.service].durations[item.duration];
  const memberDiscount = order.member ? 0.9 : 1.0;
  return { total: base * memberDiscount };
}

Результат хранится в структурированных каталогах навыков:

/sales-assistant/skills/
  offerings/
    skill.md              # YAML frontmatter + инструкции
    reference.md          # Структурированный каталог продуктов
    schema/
      schema.json         # JSON Schema (источник истины)
      schema.ts           # TypeScript-типы (производные)
  pricing-rules/
    skill.md
    reference.md          # Правила ценообразования в структурированном markdown
    scripts/
      function.js         # quoteOrder(order) -> QuoteResult

Процесс работы

graph LR
  A["Эксперт описывает бизнес-правило"] -->|"На естественном языке"| B["Агент генерирует навык"]
  B --> C{"Человек проверяет"}
  C -->|"Одобряет"| D["Навык версионируется в MongoDB"]
  C -->|"Редактирует"| E["Изменяется и повторно одобряется"]
  D --> F["Загружается в рантайме"]
  F --> G["Песочница VM выполняет"]
  G --> H["Детерминированный результат с аудит-трейлом"]

Проверка человеком: всё ещё необходима

Навыки пишутся для агентов, но люди проверяют их перед запуском. Каждое изменение навыка проходит через ворота одобрения. Владелец бизнеса видит сгенерированный код, может его отредактировать или отклонить.

Это решает две задачи. Во-первых, эксперт по предметной области подтверждает, что навык соответствует его замыслу — он описал правило на естественном языке, а теперь видит исполняемую версию. Во-вторых, одобрение человеком создаёт аудит-трейл для соответствия нормативам.

Навыки человекочитаемы, чтобы проверка была возможна. Роль человека — суждение, а не авторство.

Валидация рынком

ThoughtWorks Technology Radar Vol 34 оценил два связанных паттерна:

• Agent Skills как «Попробовать»: «Агенты загружают навыки только при необходимости на основе их описаний, что снижает потребление токенов и предотвращает исчерпание контекстного окна и такие проблемы, как разбухание инструкций для агентов» (ThoughtWorks).
• Прогрессивное раскрытие контекста как «Попробовать»: «Вместо того чтобы перегружать агента инструкциями заранее, вы даёте ему лёгкую фазу обнаружения, в которой он выбирает то, что ему нужно, на основе запроса пользователя, загружая детальную информацию в контекстное окно только тогда, когда она становится актуальной» (ThoughtWorks).

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

graph LR
  A["Агент получает задачу"] --> B{"Индекс"}
  B -->|"цены"| C["Навык pricing-rules"]
  B -->|"расписание"| D["Навык scheduling"]
  B -->|"валидация"| E["Навык validation"]
  C --> F["Выполнить"]
  D --> F
  E --> F
  F --> G["Детерминированный вывод"]

Что использовать когда

Что меняется

Документация не устарела. Markdown работает для людей. Но когда AI-агенты — ваш основной читатель, самый полезный формат — это не текст о коде, а код.

Навыки превращают бизнес-правила в исполняемые функции. Агенты загружают их, выполняют и возвращают детерминированные результаты. Люди проверяют вместо написания. Система перегенерирует навыки при изменении правил.

Сдвиг — от описания поведения к его кодированию.

Рекомендуемое чтение

• OpenWiki vs QuotyAI — два проекта LangChain DeepAgents, две архитектуры
• Спецификации vs Код-первый vs Chat-to-Code — три философии обучения AI вашему бизнесу
• Детерминизм как инфраструктура — зачем AI-платформам детерминированное исполнение
• Open Knowledge Format vs Agent Skills — почему детерминированное исполнение лучше статических файлов знаний

Часто задаваемые вопросы

Если агенты умеют читать код, зачем им вообще документация? Стоимость токенов. Чтение 5 исходных файлов стоит тысячи токенов. Хорошо структурированный файл навыка стоит меньше и содержит только то, что нужно агенту. Прогрессивное раскрытие контекста означает, что агент загружает навыки по мере необходимости, а не всё сразу (ThoughtWorks).

Чем навык отличается от документации? Документация описывает, что делает код. Навыки — это код: исполняемый, версионированный, валидируемый и запускаемый в песочнице VM на каждый запрос. Страница документации говорит агенту: «цены работают так». Навык даёт агенту функцию quoteOrder(), которая возвращает $108.

Почему бы просто не использовать AGENTS.md или CLAUDE.md? Это статические файлы, написанные человеком, которые со временем устаревают. ThoughtWorks оценил разбухание инструкций для агентов как «Осторожно»: «Инструкции становятся длинными и иногда противоречат друг другу. Модели уделяют меньше внимания контенту, погребённому в середине длинных контекстов» (ThoughtWorks).

Неужели «навыки для агентов» — это просто документация с лишними шагами? Нет. Документация — это пассивный контекст. Навыки — это активное исполнение. Страница документации говорит агенту: «цены работают так». Навык даёт агенту функцию quoteOrder(), которая запускается и возвращает $108. Разница та же, что между чтением о функции и её вызовом.

Кто поддерживает навыки, когда меняются бизнес-правила? Владелец бизнеса описывает изменение на естественном языке. Система автоматически перегенерирует все затронутые навыки. Владелец одобряет. Обновлять документацию не нужно — устаревших страниц не будет.

Tags: documentation agent-skills context-engineering ai-agents coding-agents context-rot deterministic-ai progressive-context-disclosure agent-instruction-bloat