Агентная инженерия: практическое руководство по AI-разработке

AI-агенты уже пишут продакшен-код. Инструменты вроде Claude Code, Cursor и Windsurf используются в реальных проектах, генерируя тысячи строк, которые проходят ревью и деплоятся в прод. Но между «попросить модель написать функцию» и «выстроить процесс, в котором AI стабильно генерирует качественный код» — пропасть.

Агентная инженерия (Agentic Engineering) — дисциплина, которая закрывает эту пропасть. Она отвечает на вопрос: как проектировать процессы, инструменты и контекст так, чтобы AI-агент работал предсказуемо. Не как генератор случайных сниппетов, а как управляемый участник команды.

В этой статье — конкретные техники и рекомендации: от промптинга до мульти-агентных пайплайнов. Принципы универсальны. CLAUDE.md — для Claude Code, .cursorrules — для Cursor, .github/copilot-instructions.md — для Copilot. Выбирайте среду под свои задачи.

Статья выходит в преддверии хакатона Dev-to-Dev: Agentic Engineering Challenge (26 февраля — 1 марта, онлайн) — как раз тот формат, где все эти подходы можно обкатать на практике.

---

1. Промпт-инженерия: шесть приёмов, которые реально работают при генерации кода

Промпт — это не пожелание. Это спецификация. Чем меньше модель додумывает — тем предсказуемее результат.

1.1. Контекст-фрейм: начни с ограничений, а не с задачи

Модель не знает ваш проект. Первые строки промпта — это рамка.

Плохо: «Напиши функцию валидации формы».

Хорошо: «Проект: Next.js 15, TypeScript strict, Zod, Prisma + PostgreSQL. Не используй any. Не добавляй зависимости. Напиши Zod-схему регистрации: email, пароль (мин. 8, 1 цифра, 1 спецсимвол), подтверждение пароля».

Один абзац контекста экономит три итерации переписывания.

1.2. Пример входа-выхода вместо описания словами

Плохо: «Функция проверки email, возвращает объект с результатом и причиной».

Хорошо: покажите конкретные примеры. user@domain.com → valid: true. test@ → valid: false, причина: нет домена. Пустая строка → valid: false, причина: пустой ввод.

Два-три примера задают формат точнее, чем абзац требований. Модель копирует паттерн, а не интерпретирует описание.

1.3. Negative prompting: скажите, чего НЕ делать

«Рефакторни processOrder. НЕ меняй сигнатуру. НЕ добавляй зависимости. НЕ трогай /src/core/. Сохрани совместимость с тестами».

Каждое «не» сужает пространство решений. Без ограничений модель может переписать полпроекта, «улучшая» то, что трогать не надо.

1.4. Chunking: одна задача — один промпт

Плохо: «Напиши CRUD API с авторизацией, валидацией и тестами».

Хорошо: разбейте на шаги. Сначала типы данных (User, CreateUserInput), потом сервисы (createUser, getUser), потом обработку ошибок, потом API-роуты. Каждый шаг — отдельный промпт. Ревьюите результат, двигаетесь дальше.

Chunking решает фундаментальную проблему: при большом объёме задачи модель теряет фокус и начинает «срезать углы» — упрощает типы, забывает edge cases, генерирует шаблонный код.

1.5. Spec-first: контракт до реализации

Не просите «напиши API». Опишите, как оно выглядит снаружи: POST /api/orders, тело запроса (productId, quantity, coupon), варианты ответов — 201 Created, 400 невалидное количество, 404 товар не найден, 409 нет в наличии, авторизация через JWT.

Когда контракт определён, реализация становится механической задачей. А механические задачи — именно то, что модель делает лучше всего.

1.6. Привязка к реальности: запрет галлюцинаций

Модели выдумывают методы и пакеты, которых не существует. Решение — дать фрагмент реальной схемы или документации прямо в промпте: «Prisma. Используй ТОЛЬКО findUnique/findFirst/findMany для чтения, create/update/upsert/delete для записи. НЕ используй raw SQL. Если не уверен в методе — спроси». И приложите кусок Prisma-схемы.

Лучшая защита от галлюцинаций — реальный контекст. Чем больше конкретных фрагментов кода, типов и схем вы даёте модели, тем меньше она выдумывает.

Все шесть приёмов сводятся к одному принципу: промпт — это спецификация, а не пожелание.

---

2. CLAUDE.md: онбординг-документ для AI-агента

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

Что это такое

CLAUDE.md — это не документация и не README. Это онбординг для AI-агента. Точно так же, как вы вводите нового разработчика в проект — объясняете архитектуру, показываете паттерны, предупреждаете о граблях — вы делаете это для модели. Один раз. Дальше агент читает этот файл перед каждой задачей и работает в рамках ваших правил.

Claude Code автоматически загружает CLAUDE.md при старте сессии. Cursor использует аналогичный механизм через .cursorrules, Windsurf — .windsurfrules. Принцип одинаковый, формат файла отличается.

Структура из пяти секций

Проект — краткое описание, стек, архитектура. Одним абзацем: «SaaS-платформа. Next.js 15, Prisma, PostgreSQL, мультисхемная архитектура».

Структура директорий — где что лежит. src/app/api/ — роуты, src/models/ — схемы, src/components/ — компоненты. Агент должен знать, куда класть новый файл.

Паттерны кода — один-два примера типичного эндпоинта или компонента. Не описание, а реальный фрагмент. Модель копирует стиль из примера.

Правила — что делать всегда: async/await вместо промисов, валидация через Zod, формат ошибок, согласование новых зависимостей.

Запрещено — что не делать никогда: any в TypeScript, console.log в продакшене, прямые SQL-запросы, изменение ядра без явного указания.

Три ошибки, которые убивают эффективность

Слишком длинный. Больше 1000 строк сложно поддерживать в актуальном состоянии. Чем больше правил — тем чаще они противоречат друг другу, и модель начинает выбирать между конфликтующими инструкциями. Держите документ компактным.

Слишком абстрактный. «Пиши чистый код» — бесполезно. «Каждый API-эндпоинт возвращает { data, error, meta } — вот пример» — работает. Без реальных фрагментов кода CLAUDE.md превращается в корпоративную миссию на стене.

Устаревший. Переименовали директорию, сменили ORM, обновили фреймворк — а CLAUDE.md описывает прошлую архитектуру. Агент будет генерировать код для проекта, которого больше нет.

Практический совет

Начните с 50 строк. Запустите агента, посмотрите, где он ошибается. Добавьте правило. Снова ошибся — добавьте пример. Через неделю у вас будет рабочий документ, выросший из реальных проблем. CLAUDE.md — живой артефакт, не высеченный в камне манифест.

---

3. Model Context Protocol: как устроен мост между агентом и реальным миром

Промпт и CLAUDE.md дают агенту знания о проекте. Но чтобы агент мог действовать — создавать задачи, отправлять письма, запрашивать данные из базы — ему нужен протокол взаимодействия с внешним миром. Это Model Context Protocol (MCP).

Архитектура: три роли

Host — приложение, в котором живёт агент: Claude Code, Cursor, Windsurf. Client — компонент внутри хоста, который держит соединение с конкретным сервером. Server — отдельный процесс, предоставляющий возможности: доступ к файлам, базам данных, API-сервисам.

Один Host содержит несколько Client, каждый Client подключён к одному Server. Host видит инструменты всех серверов и сам решает, какой вызвать.

Три примитива

Tools — функции, которые агент вызывает: создать задачу, выполнить SQL-запрос, отправить письмо. Это основной примитив; 90% серверов используют только tools.

Resources — данные для чтения без побочных эффектов: файлы, конфиги, состояние системы. Resources нужны, когда агенту важно увидеть текущее состояние перед принятием решения.

Prompts — шаблоны для типовых сценариев. Используются реже, но полезны для стандартизации повторяющихся задач.

Транспорт и протокол

Два варианта транспорта. stdio — для локальных серверов: хост запускает процесс и общается через stdin/stdout. Просто, быстро, без сети. Streamable HTTP — для удалённых серверов: HTTP-запросы + стриминг через Server-Sent Events. Подходит для облачных деплоев. (Streamable HTTP заменил устаревший SSE-транспорт — в старых туториалах можно встретить SSE, но новые серверы пишут на Streamable HTTP.)

Под капотом — JSON-RPC 2.0. Каждый вызов инструмента — пара запрос/ответ. Всё типизировано через JSON Schema — модель точно знает, какие аргументы передать.

Как агент выбирает инструмент

При подключении сервер отдаёт список: имя, описание, схема параметров. Модель читает name и description каждого инструмента и решает, какой подходит. Принципиальный момент: описание инструмента — это промпт для модели, а не комментарий для человека.

Описание «работает с данными» бесполезно. Описание «Возвращает список открытых задач проекта. Принимает статус фильтрации. Если задач нет — пустой массив» — работает. Плохое описание = tool не будет вызван, даже если он делает именно то, что нужно.

Практика: строим MCP-сервер за 5 шагов

Шаг 1. Инициализация. npx @modelcontextprotocol/create-server todo-server — готовая структура проекта: index.ts, tsconfig, зависимости.

Шаг 2. Tools. У каждого tool четыре составляющих: имя (add_todo), описание на естественном языке, схема параметров через Zod и обработчик — async-функция. Критически важно: у каждого параметра .describe(). Агент читает именно эти описания.

Шаг 3. Resources. Текущее состояние данных в JSON — чтение без побочных эффектов.

Шаг 4. Подключение. В .mcp.json добавляете сервер: имя и команду запуска. Перезапуск IDE — агент видит tools.

Шаг 5. Отладка. npx @modelcontextprotocol/inspector — визуальный клиент, показывающий то, что видит агент: список tools, параметры, описания. Можно вызвать любой tool вручную.

Три грабли

Абстрактные описания. «Работает с задачами» — агент не поймёт. «Добавляет задачу в TODO-список. Принимает название и приоритет. Возвращает ID» — поймёт сразу.

Нет error handling. Когда tool падает с необработанным исключением, агент получает stack trace и пытается его «починить» — обычно делая хуже. Оборачивайте в try/catch и возвращайте понятное сообщение.

Переусложнённые параметры. Tool с 10 обязательными полями — лабиринт. Агент запутается и начнёт галлюцинировать значения. Лучше пять простых tools, чем один универсальный.

Экосистема

MCP отвязывает инструмент от модели. Написали сервер один раз — он работает с Claude, GPT, Gemini, с любой моделью, поддерживающей протокол. Каталог готовых серверов: github.com/modelcontextprotocol/servers. Спецификация: spec.modelcontextprotocol.io.

---

4. Git Worktrees: параллельная работа с AI без конфликтов

Одна из неочевидных проблем AI-разработки: агент занят долгой задачей в одной ветке, а вам нужно параллельно делать что-то в другой. Переключать ветки нельзя — агент работает с файлами. Клонировать репозиторий заново — долго и неудобно. Решение — git worktrees.

Что это такое

Git worktree — это дополнительная рабочая копия того же репозитория, привязанная к другой ветке. Один .git, несколько директорий с кодом. Каждая может быть открыта в своей сессии AI-агента одновременно.

Зачем это AI-разработчику

Параллельные сессии. Агент пишет фичу в feature/auth — вы открываете вторую сессию Claude Code в worktree на feature/api и работаете одновременно. Никаких конфликтов, никаких git stash.

Изолированные эксперименты. Хотите попробовать радикальный рефакторинг? Создайте worktree, дайте агенту задачу. Если результат не понравился — просто удалите директорию. Основная ветка не тронута.

Code review. Нужно проверить чужой PR? Worktree на ветку PR — и агент ревьюит код, пока ваша основная работа не прерывается.

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

Создать worktree:

git worktree add ../my-project-feature feature/new-api

Теперь в ../my-project-feature — полная копия проекта на ветке feature/new-api. Открываете там отдельную сессию Claude Code — и работаете параллельно с основной.

Список всех worktrees:

git worktree list

Удалить, когда больше не нужен:

git worktree remove ../my-project-feature

Worktrees в Claude Code

В Claude Code есть встроенная поддержка worktrees. При запуске подзадач через Task tool можно указать isolation: "worktree" — агент автоматически создаст временный worktree, выполнит задачу в изолированной копии репозитория, и вернёт результат. Если изменения не нужны — worktree удалится сам. Если нужны — вы получите путь и ветку для мёрджа.

Это особенно полезно для мульти-агентных воркфлоу: каждый агент работает в своём worktree, никто не мешает друг другу.

Практический паттерн

Типичная структура для AI-разработки:

~/projects/
├── my-app/              # основная ветка (main)
├── my-app-feature-auth/ # worktree: feature/auth (сессия агента 1)
├── my-app-feature-api/  # worktree: feature/api (сессия агента 2)
└── my-app-hotfix/       # worktree: hotfix/urgent (ручная работа)

Все четыре директории — один репозиторий, один .git. Коммиты видны везде. Ветки мёрджатся как обычно.

---

5. Паттерны ошибок AI-генерируемого кода

Код компилируется, линтер молчит, тесты зелёные. А потом — метод, которого не существует, пакет-призрак из npm и SQL-инъекция в единственном эндпоинте. AI-генерация порождает не больше багов, чем ручной код, но паттерны другие. Знание паттернов — половина решения.

5.1. Галлюцинации API

Модель уверенно вызывает метод, которого нет в библиотеке. Классика из Prisma: AI пишет prisma.user.findByEmail("test@example.com") — выглядит логично, но такого метода не существует. Правильно — findUnique с параметром where: { email }. Модель «помнит» паттерны из тысяч ORM и микширует их.

Strict TypeScript ловит это на этапе компиляции. Без строгих типов — уедет в прод.

5.2. Устаревший синтаксис

AI обучен на миллионах репозиториев, значительная часть — legacy. componentDidMount вместо useEffect. var вместо const/let. new Buffer() вместо Buffer.from(). В открытых репозиториях deprecated-кода накоплено за десятилетия, и модели неизбежно на нём обучаются.

Лечение — явно указать в CLAUDE.md: «React только хуки. Node.js >= 20. Не используй deprecated API».

5.3. Security-дыры

Модель не различает trusted и untrusted input. Типичный случай: AI подставляет пользовательский ввод прямо в SQL-строку — классическая SQL-инъекция. Правильно — параметризованные запросы.

То же с XSS (innerHTML = userInput), path traversal (fs.readFile(userInput)), command injection (exec(userInput)). AI оптимизирует на «работает», а не на «безопасно». Безопасность — отдельная задача, которую нужно явно ставить.

5.4. Happy path only

AI отлично пишет основной сценарий, но систематически забывает: null / undefined — что если пользователь не найден? Пустой массив — items[0].name упадёт с TypeError. Сетевые таймауты — fetch без AbortController и таймаута может висеть минутами, блокируя ресурсы. Race conditions — два запроса обновляют один ресурс.

Модель пишет код для идеального мира. Пользователи живут в неидеальном.

5.5. Phantom dependencies

AI импортирует пакет, которого нет в npm. Например, json-schema-validator-pro — название правдоподобно, но пакет не существует. AI его выдумал.

Это не просто ошибка сборки. Исследования показывают, что AI-модели стабильно генерируют одни и те же несуществующие имена пакетов. Атакующие регистрируют такие имена и заливают вредоносный код — dependency confusion на AI-галлюцинациях. Каждый незнакомый import — npm info перед установкой.

Как ловить систематически

• Strict TypeScript + ESLint — ловит галлюцинации API и deprecated-паттерны на этапе компиляции. Первая линия обороны, бесплатная.
• AI vs AI — один агент пишет, другой ревьюит с промптом «найди уязвимости и edge cases». Но важно: тесты — отдельным запросом, по спецификации, а не по коду. Если AI неверно понял задачу — и код, и тесты, написанные вместе, будут «согласованно» неправильными.
• npm audit + npm info — проверка зависимостей на существование и уязвимости.
• CLAUDE.md с запрещёнными паттернами — явный список «не делай так» снижает повторение ошибок на порядок.

---

6. Мульти-агентные воркфлоу: разделяй и властвуй

Вы дали агенту задачу: спроектируй, напиши, покрой тестами, задокументируй. Контекст на 50 000 токенов, промпт на два экрана. Результат — каша. Проблема не в модели. Один агент не может быть архитектором, кодером, тестировщиком и техписом одновременно.

Чем уже задача — тем точнее результат. Мульти-агентный воркфлоу — это когда несколько агентов с разными ролями и контекстами решают одну задачу.

Паттерн 1: Pipeline (конвейер)

Architect → Coder → Reviewer → Tester. Каждый агент получает результат предыдущего. Architect создаёт спецификацию и интерфейсы. Coder реализует строго по спецификации. Reviewer ищет баги и security-проблемы. Tester пишет тесты.

Ключевое: каждый видит только свой кусок контекста. Изолированный контекст заставляет агента работать строго в своей роли.

Паттерн 2: Router + Specialists (маршрутизатор)

Router → [DB Agent | API Agent | UI Agent | DevOps Agent]. Router анализирует задачу и направляет к специалисту. «Добавь индекс в таблицу» — к DB Agent. «Сверстай форму» — к UI Agent. Каждый имеет свой системный промпт с узким контекстом: DB Agent знает схему базы, UI Agent — дизайн-систему. Когда задача затрагивает несколько областей — Router декомпозирует и отправляет подзадачи параллельно.

Паттерн 3: Adversarial (состязательный)

Generator ↔ Critic → итоговый результат. Generator пишет код. Critic ломает: edge cases, невалидные входы, race conditions. Generator исправляет. Цикл повторяется, пока Critic не примет.

Это формализация приёма «AI vs AI» из раздела про ошибки, но возведённая в архитектурный принцип. Две-три итерации находят баги, которые ручное ревью пропускает.

Реализация

В Claude Code мульти-агентность реализуется через Task tool — запуск подзадачи в чистом контексте. Подагент не видит историю основного разговора, а только то, что ему передали. Это и есть изоляция: подагент-тестировщик не знает, что «хотел» кодер, и тестирует непредвзято. Агенты обмениваются через файлы: Architect пишет spec.md, Coder читает spec.md и пишет код, Tester читает код и пишет тесты. Никакого общего контекста — только артефакты.

В сочетании с git worktrees это особенно мощно: каждый агент работает в изолированной копии репозитория, изменения мёрджатся только после ревью.

Когда это оверинжиниринг

Правило: если задача декомпозируется на роли — используйте мульти-агентный воркфлоу. Если нет — одного агента достаточно. Конвейер из четырёх агентов для функции на 10 строк — пустая трата контекста и времени.

---

Заключение

Агентная инженерия — это не про замену разработчика на AI. Это про изменение того, чем разработчик занимается. Вместо написания кода — проектирование архитектуры, формулирование спецификаций, настройка контекста и контроль качества.

Практический минимум, который стоит внедрить уже сейчас:

1. Промпт-инженерия — контекст, примеры, ограничения, спецификация. Перестать давать абстрактные задачи.
2. CLAUDE.md — 50 строк онбординга для агента. Расширять по мере обнаружения ошибок.
3. MCP — подключить готовые серверы для инструментов, которыми пользуетесь. Попробовать написать свой.
4. Git worktrees — параллельная работа нескольких агентов над одним проектом без конфликтов.
5. Защита от ошибок — strict TypeScript, тесты отдельно от кода, явные запреты.
6. Мульти-агентные воркфлоу — для задач, которые декомпозируются на роли.

Каждый из этих элементов работает сам по себе. Вместе они образуют систему, в которой AI-агент из непредсказуемого генератора сниппетов превращается в управляемого участника разработки.

Все эти подходы можно попробовать на практике на хакатоне Dev-to-Dev: Agentic Engineering Challenge — 26 февраля — 1 марта, онлайн, бесплатно. Как раз тот формат, где агентная инженерия проверяется делом.