Developing AI Agents

Плагин для Claude Code и Codex с одним скиллом, который помогает проектировать, чинить и оценивать AI-агентов. Скилл опирается на книгу Bojie Li «AI-агенты изнутри: принципы проектирования и инженерная практика» (вторая редакция) — её русский текст входит в плагин.

Скилл пригодится, если вы:

• решаете, нужен ли здесь агент или хватит одного вызова модели либо обычного workflow;
• проектируете агента и хотите заранее понять, где он сломается и как это проверить;
• разбираете, почему агент зацикливается, теряет контекст или повторяет вызовы инструментов;
• выбираете между одним агентом и несколькими;
• хотите проверить, улучшили ли результат новый промпт, модель или инструмент.

Для обычного приложения без агентного цикла он не нужен.

Установка

Claude Code:

claude plugin marketplace add ilkruglov/developing-ai-agents-skill
claude plugin install developing-ai-agents@developing-ai-agents-skill

Codex:

codex plugin marketplace add ilkruglov/developing-ai-agents-skill
codex plugin add developing-ai-agents@developing-ai-agents-skill

Обновление:

claude plugin marketplace update developing-ai-agents-skill
claude plugin update developing-ai-agents@developing-ai-agents-skill

codex plugin marketplace upgrade developing-ai-agents-skill
codex plugin add developing-ai-agents@developing-ai-agents-skill

После установки или обновления начните новую сессию.

Как пользоваться

Опишите задачу обычным текстом — скилл подключится сам. Например:

Нужен агент, который разбирает споры по счетам. Какая архитектура минимально достаточна и где ограничить его права?
Агент после сжатия контекста забывает ограничения и повторяет одну команду. Вот trace — найди причину.
Мы поменяли промпт, успех вырос с 72 до 76 %. Это улучшение или шум?
Стоит ли делить задачу между тремя агентами или хватит одного?
Составь план оценки агента: набор задач, метрики и условие выпуска.

Вызвать явно тоже можно: в Claude Code — /developing-ai-agents:developing-ai-agents <задача>, в Codex — Используй $developing-ai-agents, чтобы <задача>.

Что вы получите

• Решение или диагноз в первых строках, затем архитектура, порядок реализации, проверки и риски.
• Минимальную архитектуру: самый простой вариант, который закрывает задачу, и места, где он может отказать.
• Факты отдельно от выводов. Подтверждённое кодом, логом или trace отделено от объяснений и от того, что ещё нужно измерить или сверить с текущей документацией провайдера.
• План проверки: какие задачи прогнать, какие метрики смотреть и при каком результате изменение можно выпускать.
• Ссылки на книгу со строками — чтобы проверить, откуда взят принцип.

Если данных мало, скилл предложит, что добавить в логирование и какой эксперимент поставить, и не выдаст гипотезу за причину. При ревью и разборе сбоя он ничего не меняет в системе, пока вы не попросите. Ответ по умолчанию — до 1200 слов; подробнее — по просьбе.

Что внутри

• пошаговые процедуры: проектирование, разбор trace, ревью, оценка, память, голос и realtime, выбор между одним агентом и несколькими;
• шаблоны документов с заполненными примерами: дизайн агента, спецификация Harness, контракт инструмента, план оценки, политика памяти, разбор trace;
• каталог типичных сбоев по симптомам и 16 паттернов «сбой → механизм → проверка»;
• конспекты всех глав книги с проверенными цитатами и полный текст книги.

Насколько это помогает

На 32 задачах по проектированию, разбору сбоев, оценке и заполнению документов ответы со скиллом выполнили 96 % критериев против 84 % у той же модели без скилла. В 13 задачах ответ со скиллом набрал больше критериев, в 19 — столько же, меньше — ни в одной. Без скилла модель пропускала, например, проверку фактического состояния после таймаута и сравнение с одиночным агентом при равном бюджете.

Ограничения замера: один прогон; одна модель (opus) писала ответы, переписывала критерии и оценивала; оценщик мог узнать ответ со скиллом по ссылкам на книгу; в шести задачах на заполнение документа шаблон был только у скилла; ответы со скиллом длиннее (медиана около 1070 слов против 890); задачи написаны в этом же проекте. Критерии перед оценкой переписаны, чтобы не проверять словарь скилла. Замер сделан на версии 0.7.3 в сентябре 2026. Метод и разбор — в benchmarks/v6/benchmark.md.

В последнем замере в Claude Code скилл сработал на 20 из 20 запросов про агентов и ни на одном из 22 посторонних, в том числе на 4 про GPU (по одному прогону на запрос).

Соседний скилл

Как сократить контекст, расход токенов, стоимость и задержку самого агента — вопрос к этому скиллу. Сколько это стоит на конкретном железе или по тарифам API, сколько нужно GPU и какой будет задержка модели на заданном железе — к designing-ai-infra. Оба скилла можно установить вместе.

Для разработчиков

python3 scripts/validate.py
python3 -m unittest discover -s tests
claude plugin validate . --strict

scripts/validate.py проверяет, что каждая цитата из книги дословна и стоит в нужном разделе, а ссылки на строки книги не сдвинулись. После намеренной правки ссылок на книгу обновите фиксацию якорей: python3 scripts/build_source_lock.py.

Источники и лицензия

• Автор книги: Bojie Li.
• Оригинал: bojieli/ai-agent-book.
• Русский перевод: ilkruglov/ai-agent-book, «Русский перевод: community edition». Русское издание содержит помеченные редакционные уточнения: отступления от текста автора отмечены строкой «Уточнение русского издания» с исходной формулировкой автора и источником.

Версии исходных материалов — в SOURCE.json, уведомление об авторстве — в NOTICE. Лицензия Apache 2.0, см. LICENSE.