Developing AI Agents plugin

---
name: developing-ai-agents
description: Use when designing, implementing, reviewing, debugging, or evaluating an AI agent or the environment that steers one - a skill, system prompt, CLAUDE.md or AGENTS.md, hook, tool or MCP server, subagent - especially for context engineering, tool interfaces, Harness reliability, memory, evaluation, post-training, continual evolution or self-evolution, asynchronous or realtime interaction, computer use, or multi-agent coordination. Do not use for ordinary non-agent application code. Not for AI infrastructure — GPU and serving capacity sizing, training clusters, or serving cost per token on given hardware (use designing-ai-infra); the agent's own logic, prompts, tools and memory, and its context, token use, cost and latency as design and eval concerns, stay here.
---

# Разработка AI-агентов

Проектируй агента как проверяемую систему, а не как «промпт плюс мощная модель». Опирайся на русское издание книги Bojie Li «AI-агенты изнутри: принципы проектирования и инженерная практика» и на факты из текущего проекта.

## Рабочий контракт

1. Сначала изучи реальные требования, код, конфигурацию, трассы, метрики и ограничения. Не называй гипотезу причиной без доказательств.
2. Разделяй:
   - **evidence** — что подтверждено кодом, логом, тестом или измерением;
   - **inference** — наиболее вероятное объяснение;
   - **unknown** — что еще нужно измерить.
3. Начинай ответ с решения или диагноза. После него дай минимальную архитектуру, порядок реализации, проверки и риски.
4. Для review или diagnosis оставайся read-only, пока пользователь явно не попросит изменить систему. Для реализации соблюдай инструкции репозитория и TDD.
5. Книжные принципы считай устойчивыми инженерными эвристиками. Актуальность моделей, SDK, API, протоколов, цен, лимитов и поддержки провайдеров проверяй по первичным текущим источникам.
6. По умолчанию укладывай архитектурный ответ в 1200 слов. Расширяй его только по явному запросу; если деталей больше, приоритизируй решения, contracts и проверки, а не полный checklist.

## С чего начать: маршрут по задаче

| Запрос выглядит как | Начни с | Добери при необходимости |
|---|---|---|
| спроектировать агента с нуля | [playbooks/design-agent.md](references/playbooks/design-agent.md) | [templates/agent-design.md](references/templates/agent-design.md), [patterns.md](references/patterns.md) |
| разобрать trace, найти причину сбоя | [playbooks/diagnose-trace.md](references/playbooks/diagnose-trace.md) | [templates/trace-diagnosis.md](references/templates/trace-diagnosis.md), [antipatterns.md](references/antipatterns.md) |
| review существующей агентной системы | [playbooks/harness-review.md](references/playbooks/harness-review.md) | [templates/harness-spec.md](references/templates/harness-spec.md) |
| построить или починить evals | [playbooks/build-evals.md](references/playbooks/build-evals.md) | [templates/eval-plan.md](references/templates/eval-plan.md) |
| память, RAG, самоулучшение | [playbooks/memory-design.md](references/playbooks/memory-design.md) | [templates/memory-policy.md](references/templates/memory-policy.md) |
| голос, realtime, асинхронность, Computer Use | [playbooks/realtime-latency.md](references/playbooks/realtime-latency.md) | [chapters/ch06](references/chapters/ch06-interaction.md) |
| один агент или несколько | [playbooks/multi-agent-choice.md](references/playbooks/multi-agent-choice.md) | [chapters/ch10](references/chapters/ch10-multi-agent.md) |
| контракт инструмента, права, песочница | [templates/tool-contract.md](references/templates/tool-contract.md) | [chapters/ch04](references/chapters/ch04-tools.md) |
| симптом известен, причина нет | [antipatterns.md](references/antipatterns.md) | playbook по нужной области |
| что говорит книга по теме | [source-map.md](references/source-map.md) | нужный конспект главы |
| спорный вопрос проектирования, похожий на «вопрос для размышления» | [chapters/ch12](references/chapters/ch12-reference-answers.md) | ответ в `references/source-book/reference-answers.md` |

Загружай только релевантные файлы. Не помещай всю книгу в контекст одновременно.

## Основная модель

> **AI-агент = LLM + контекст + инструменты**

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