AI-инженерия и Harness: Как перейти от наивного вайбкодинга к надежным агентным системам в продакшене

🎯 О чём этот конспект: Разбор фундаментального сдвига в IT-индустрии от написания кода вручную к проектированию управляющей среды (Harness) для AI-агентов. Рассматриваются причины, почему дешевая генерация кода не ускорила выпуск сложных продуктов (Verification Tax), ключевые ограничения LLM и 6 архитектурных слоев (Context, Tools/MCP, Memory, Evals, Observability, Guardrails), превращающих вероятностные нейросети в надежных исполнителей.

👤 Кому будет полезно: Вайбкодерам, AI-инженерам, тимлидам, техлидам и фаундерам, которые создают продукты с помощью Cursor, Claude Code, Windsurf или кастомных агентных пайплайнов и сталкиваются с деградацией контекста, галлюцинациями и сложностью поддержки кодовой базы.

✨ Что получите: Четкое архитектурное руководство по подготовке проекта к AI-Native разработке: от базовой настройки CLAUDE.md и AGENTS.md до внедрения системы автоматической верификации (Evals), контекст-инжиниринга и протокола MCP.

1. Парадокс скорости: Verification Tax и почему дешевый код тормозит релизы

Контекст: С развитием моделей (Claude Opus, Codex, Gemini Flash) написание кода перестало быть дефицитным навыком — нейросети решают более 70% реальных задач из GitHub Issues по бенчмаркам (SWE-bench). Однако общая скорость вывода продуктов на рынок не выросла, а стоимость готовых решений увеличилась. Причина кроется в вероятностной природе LLM: модель генерирует не готовое решение, а вероятностного кандидата. Возникает феномен Verification Tax (налог на верификацию) и Verification Debt (долг по ревью), когда проверка огромных диффов кода отнимает больше времени, чем классическое написание руками.

Тайминг: ▶ 00:28, ▶ 04:55, ▶ 13:28, ▶ 14:28

Выгода: Понимание узкого горлышка разработки позволяет прекратить бездумную генерацию сотен строк кода и выстроить процесс ревью и фильтрации изменений, экономя до 80% времени инженеров на разборе ложных решений.

Как применить:

• Шаг 1: Отказ от наивного AI-процесса — Не отправляйте агенту размытые промпты с ожиданием готового PR на 20 файлов. Разбейте фичу на атомарные спецификации с жесткими границами изменений.
• Шаг 2: Внедрение промежуточной спецификации — Перед тем как давать команду на написание кода, потребуйте от агента составить технический план и согласовать контракт изменений.
• Шаг 3: Автоматизация первого слоя проверки — Настройте линтеры, проверку типов (TypeScript/Pyright) и автотесты на каждый шаг агента до того, как код попадет на глаза человеку.

# Промпт для генерации спецификации перед кодингом
Ты действуешь как AI-разработчик. Не пиши код сразу.
1. Проанализируй задачу и сформируй краткую техническую спецификацию (Technical Spec).
2. Перечисли точный список файлов, которые потребуется создать или изменить (не более 3-4 файлов за итерацию).
3. Опиши возможные сайд-эффекты для смежных модулей.
4. Дождись моего подтверждения перед внесением правок в кодовую базу.

Результат: Снижение объема "мусорного" кода в диффах и устранение перегрузки инженеров проверкой неподходящих реализаций.

2. Айсберг разработки: Разница между MVP на 1 промпт и реальным продуктом

Контекст: Хайп вокруг вайбкодинга создает иллюзию, что рабочий сервис можно поднять за 1–2 промпта. Это справедливо для демок, лендингов или простых ботов, где кодовая база минимальна, а контекст легко помещается в одно окно диалога. Однако настоящий софт — это айсберг: видимая верхушка (UI и базовый код) опирается на подводную часть (миграции БД, обратная совместимость, роли и доступы, бизнес-правила, обработка краевых случаев и исторические решения). Значительная часть этих знаний децентрализована — она хранится в головах тимлидов, трекерах Jira, вики Confluence или закрытых чатах.

Тайминг: ▶ 05:58, ▶ 07:48, ▶ 08:45

Выгода: Предотвращение архитектурного краха проектов при масштабировании за пределы 1-2 сессий чата.

Как применить:

• Шаг 1: Оцифровка неявных знаний в репозиторий — Перенесите архитектурные договоренности и краевые случаи из чатов и трекеров в текстовые файлы внутри репозитория (Architecture Decision Records — ADR).
• Шаг 2: Создание карты зависимостей — Опишите критические модули и контракты в едином файле архитектуры, к которому агент обращается перед началом работы.
• Шаг 3: Фиксация краевых случаев (Edge Cases) — Для каждого бизнес-правила заведите тест или пункт в документации, запрещающий агенту ломать историческую логику.

# docs/architecture/ADR-001-auth-flow.md
 
---
 
## Статус: Принято
 
---
 
## Контекст:
Исторически авторизация пользователей разделена на два контура: B2C (через Auth0) и B2B (через SAML SSO).
 
 
---
 
## Ограничения для AI-агентов:
1. Запрещено объединять схемы таблиц `User` и `EnterpriseUser`.
2. Поле `tenant_id` обязательно для всех запросов в контуре `/api/v1/enterprise/*`.
3. Не модифицировать middleware `src/middleware/auth.ts` без запуска E2E-тестов `tests/e2e/auth.spec.ts`.

Результат: Агент получает доступ к скрытому контексту проекта и перестает ломать неявные зависимости при генерации новых фичей.

3. Пять фундаментальных ограничений LLM при работе с кодом

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

1. Деградация контекстного окна: Даже при окне в 1M+ токенов модель начинает галлюцинировать при перегрузке лишними данными.
2. Вероятностный выход: Ответ модели никогда не является 100% истиной; она может выдумывать несуществующие API, URL или игнорировать требования.
3. Отсутствие памяти: Каждая новая сессия начинается с нуля («чистый лист»).
4. Отсутствие нативных инструментов: LLM сама по себе не может запускать код, делать PR, ходить по SSH или тестировать UI.
5. Преждевременное завершение задач: При длинных итерациях модели склонны бросать задачу на полпути или объявлять ее выполненной без фактической проверки.

Тайминг: ▶ 08:53, ▶ 09:67, ▶ 10:53, ▶ 11:21, ▶ 11:54

Выгода: Исключение иллюзий относительно автономности моделей и переход к проектированию защитных механизмов.

Как применить:

• Шаг 1: Внедрение итеративного чек-листа — Заставляйте модель разбивать сложную задачу на чек-лист и обновлять статус каждого шага (ToDo / In Progress / Done) перед переходом к следующему.
• Шаг 2: Использование жестких инструкций завершения — Запретите агенту помечать задачу завершенной без предоставления лога успешного прохождения тестов.
• Шаг 3: Сброс сессий с передачей артефактов — Не держите длинные диалоги на 50+ сообщений; фиксируйте прогресс в файл состояния (STATE.md) и перезапускайте сессию с чистым контекстом.

# Промпт для принудительного итеративного выполнения задачи
Работай строго по следующему протоколу:
1. Создай чек-лист подзадач в формате Markdown.
2. Выполняй строго по одной подзадаче за раз.
3. После каждого изменения запускай проверку: `npm run type-check && npm test`.
4. Если тесты упали — исправь ошибку перед переходом к следующему шагу.
5. Задачу разрешено считать выполненной ТОЛЬКО после того, как все тесты прошли зелёным и статус всех пунктов чек-листа равен [x].

Результат: Устранение ситуаций, когда агент «забывает» дописать код, выдает псевдорешения или теряет фокус в середине комплексного рефакторинга.

4. Архитектура Harness: 6 слоев управляющей среды вокруг AI-модели

Контекст: Harness — это управляющая инженерная инфраструктура вокруг LLM, которая превращает вероятностную модель в предсказуемого и повторяемого программного исполнителя. Модель выступает лишь сменным вычислительным процессором, а качество работы определяется обвязкой. Полный Harness состоит из 6 слоев:

1. Context Engineering: Подача минимально достаточных и точных данных.
2. Tools & MCP: Расширение возможностей агента через интерфейсы (терминал, браузер, БД, API).
3. Memory & State: Сохранение принятых решений между сессиями.
4. Evals (Оценка агента): Проверка логики работы самой модели, а не только кода.
5. Observability & Tracing: Логирование промптов, вызовов инструментов и ретраев.
6. Guardrails & Approvals: Ограничения, изолированные песочницы (Sandboxes) и шлюзы одобрения человеком.

Тайминг: ▶ 15:58, ▶ 16:40, ▶ 17:90, ▶ 27:31

Выгода: Возможность переходить с дорогих топовых моделей на быстрые и дешевые (например, с Opus на DeepSeek/Kimi/GLM) без потери качества генерации за счет зрелой инфраструктуры, экономя до 70-90% затрат на токены.

Как применить:

• Шаг 1: Создание базового Harness — Создайте в корне проекта файлы правил (CLAUDE.md, AGENTS.md или .cursorrules), содержащие стек, команды сборки, стиль кода и архитектурные запреты.
• Шаг 2: Организация изоляции (Sandbox) — Запускайте агентов в отдельных git-ветках или Docker-контейнерах с доступом только к тестовой БД.
• Шаг 3: Настройка Human-in-the-loop шлюза — Заблокируйте для агента прямой мердж в main, применение миграций в прод и удаление файлов без ручного подтверждения (Approval).

# Пример базового Harness-файла: CLAUDE.md
# Инструкции для AI-агента
 
 
---
 
## Стек и окружение
- Node.js v20+, TypeScript, Next.js (App Router), Prisma, PostgreSQL.
- Команда сборки: `npm run build`
- Команда тестов: `npm test`
- Команда проверки типов: `npx tsc --noEmit`
 
 
---
 
## Архитектурные правила
- Все серверные мутации выполнять строго через Server Actions в папке `src/actions/`.
- Никогда не использовать `any` в TypeScript.
- Не изменять схему в `prisma/schema.prisma` без предварительного создания плана миграции.
 
 
---
 
## Guardrails (Ограничения)
- ЗАПРЕЩЕНО читать файлы: `.env`, `.env.production`, `secrets/*`.
- ЗАПРЕЩЕНО выполнять команды: `git push --force`, `rm -rf`, `prisma migrate deploy`.
- Любые изменения базы данных согласовывать с пользователем.

Результат: Предсказуемое поведение агента в проекте, защита продакшена от несанкционированных действий и стандартизация среды выполнения.

5. Контекст-инжиниринг и RAG: Принцип минимально достаточного контекста

Контекст: Распространенная ошибка — попытка «запихнуть весь проект в один промпт». Качественный контекст строится на обратном принципе: собрать в окне модели минимально необходимое количество информации, достаточное для решения конкретной подзадачи. Для этого используются методы семантического поиска, графы зависимостей (Dependency Graph), поиск по символам/файлам (Grep) и RAG-пайплайны, которые извлекают только релевантные куски документации и кода.

Тайминг: ▶ 09:18, ▶ 19:33, ▶ 20:63

Выгода: Снижение затрат на токены в 3–5 раз, уменьшение галлюцинаций модели на 60% и исключение конфликтов противоречивых инструкций.

Как применить:

• Шаг 1: Модульная организация документации — Разбейте общую документацию проекта на узконаправленные файлы в папке .docs/ (например, .docs/database.md, .docs/api-contracts.md, .docs/ui-kit.md).
• Шаг 2: Точечная загрузка контекста — Подключайте к сессии только те файлы, которые относятся к текущей задаче, вместо сканирования всего репозитория.
• Шаг 3: Использование встроенных инструментов поиска — Настройте агента на использование grep_search и file_search по конкретным сигнатурам функций вместо чтения полных файлов.

# Шаблон запроса с минимально достаточным контекстом
Задача: Реализовать эндпоинт отмены подписки пользователя.
 
Контекст:
- Схема данных: @docs/database.md (секция Subscription)
- Сервис биллинга: @src/services/billing.ts (только интерфейс IBillingService)
- Обработка ошибок: @src/utils/errors.ts
 
Не сканируй фронтенд-модули и директорию /tests/e2e/. Используй только указанные файлы.

Результат: Модель фокусируется строго на релевантном коде, не перегружает контекст и принимает решения с высокой точностью.

6. Инструменты и протокол MCP (Model Context Protocol)

Контекст: LLM в базе работает только с текстом. Чтобы агент мог оперировать реальным проектом, ему нужны инструменты (Tools). MCP (Model Context Protocol) от Anthropic — это открытый стандарт («USB-C для искусственного интеллекта»), стандартизирующий подключение моделей к внешним источникам данных: файловой системе, GitHub, базам данных, логам, Sentry или браузеру. Если функционал специфичен только для одного внутреннего скрипта, достаточно обернуть его в локальный Tool, но для универсальной интеграции с сервисами компании стандартом становится MCP.

Тайминг: ▶ 21:16, ▶ 21:40, ▶ 22:12, ▶ 22:74

Выгода: Агент получает возможность самостоятельно проверять состояние БД, делать запросы к API, анализировать ошибки в логах и валидировать результат без ручного копирования данных человеком.

Как применить:

• Шаг 1: Установка MCP-серверов в агентскую среду — Настройте конфигурацию MCP в вашем клиенте (Claude Code, Cursor, Windsurf).
• Шаг 2: Подключение сервера базы данных — Добавьте доступ агента к локальной/стейджинг БД в режиме Read-Only для проверки схемы и реальных данных.
• Шаг 3: Подключение инструментов анализа логов — Интегрируйте MCP для чтения логов сборки и трейсов ошибок.

Результат: Агент получает прямой доступ к инфраструктуре проекта по безопасному протоколу, исключая ошибки в SQL-запросах и типах данных.

7. Тестирование агентов: Evals против классических Software-тестов

Контекст: В классической разработке софтверные тесты (Unit, Integration, E2E) проверяют работоспособность написанного продукта. В AI-Native разработке появляется дополнительный слой — Evals (оценка работы агента). Эвалы тестируют не софт, а систему, которая создает софт: понял ли агент задачу, нашел ли правильную документацию, вызвал ли нужный MCP-инструмент, соблюдал ли последовательность шагов и не сломалось ли его поведение при смене модели (например, при переходе с Claude 3.7 на DeepSeek V3).

Тайминг: ▶ 24:40, ▶ 25:06, ▶ 25:38

Выгода: Гарантия стабильности агентных пайплайнов и возможность безболезненно менять LLM-провайдеров без риска деградации качества автоматизации.

Как применить:

• Шаг 1: Фиксация тестовых сценариев для агента — Сформируйте набор стандартных задач (Golden Dataset), на которых вы оцениваете качество работы агента (например: «найти эндпоинт X, обновить схему Y, запустить тесты»).
• Шаг 2: Проверка вызова инструментов (Tool Call Accuracy) — Убедитесь, что агент вызывает нужные MCP-методы с корректными параметрами.
• Шаг 3: Автоматизированный запуск прогона моделей — Перед переводом пайплайна на более дешевую модель прогоните бенчмарк эвалов и проверьте процент успешного выполнения задач.

# Пример спецификации Evals-теста для AI-агента
eval_case:
  id: "add-user-field-validation"
  task_prompt: "Добавь валидацию поля phoneNumber в схему регистрации пользователя."
  expected_actions:
    - action: "file_read"
      target: "src/schemas/user.ts"
    - action: "tool_call"
      name: "run_linter"
    - action: "file_write"
      target: "src/schemas/user.ts"
  assert_outputs:
    - check: "regex_match"
      file: "src/schemas/user.ts"
      pattern: "z\\.string\\(\\)\\.regex\\(/\\^\\\\\\+?[1-9]/"
    - check: "command_success"
      command: "npm test tests/schemas/user.test.ts"

Результат: Прозрачная метрика качества работы AI-агентов на реальной кодовой базе проекта при обновлении промптов или смене LLM.

8. Модель зрелости проектов: Stanford AI Engineering Practices Benchmark

Контекст: Стэнфордский бенчмарк зрелости AI-инженерии классифицирует проекты по 5 уровням (от L0 до L4) на основе реального анализа репозиториев (наличие агентов, версионирование промптов, оркестрация, workflow):

• L0 (No observable AI): Код пишется исключительно руками, AI не задействован.
• L1 (Opportunistic Prompting): Хаотичное использование промптов отдельными разработчиками, промпты складируются без структуры.
• L2 (Systematized Prompting): Промпты и правила версионируются в git, есть общие правила для всей команды (CLAUDE.md, .cursorrules).
• L3 (Agent Backend Development): Создание переиспользуемых специализированных субагентов под типовые задачи (рефакторинг, тесты, документация).
• L4 (Orchestrated Agentic Workflows): Мультиагентные системы под управлением общего оркестратора, автономно решающие сложные бизнес-задачи.

Тайминг: ▶ 30:58, ▶ 31:17, ▶ 31:48, ▶ 31:65

Выгода: Понимание текущей зрелости проекта и пошаговый роадмап перехода от уровня персонального копирования промптов к системной корпоративной AI-разработке.

Как применить:

• Шаг 1: Переход с L1 на L2 — Создайте папку .ai/ или .prompts/ в корне проекта и закоммитьте системные инструкции, шаблоны задач и правила архитектуры в Git.
• Шаг 2: Переход с L2 на L3 — Выделите типовые повторяющиеся задачи (написание Unit-тестов, генерация Swagger-документации, миграции Prisma) в отдельные скрипты вызова агентов.
• Шаг 3: Переход с L3 на L4 — Свяжите агентов в последовательный пайплайн: Агент-Аналитик (готовит спеку) -> Агент-Кодер (пишет код) -> Агент-Тестировщик (проверяет Evals и софтверные тесты) -> Ревьюер (готовит summary для человека).

# Структура репозитория уровня L2-L3
├── .ai/
│   ├── rules/
│   │   ├── frontend.md
│   │   └── backend.md
│   ├── agents/
│   │   ├── test-generator.prompt.md
│   │   └── api-doc-updater.prompt.md
│   └── state/
│       └── session-history.json
├── CLAUDE.md
└── AGENTS.md

Результат: Повышение уровня зрелости репозитория, обеспечивающее стабильную командную работу с AI без конфликтов стилей и подходов.

9. Роль AI-инженера и защита от схлопывания финансовых пузырей

Контекст: AI-инженер — это специалист, который проектирует среду (Harness), контекст, память, инструменты и ограничения для LLM, связывая классическую кодовую базу с вероятностной моделью. Даже если финансовый пузырь вокруг AI-стартапов лопнет (по аналогии с доткомами 2000 года или криптовалютами), технология генерации кода никуда не исчезнет. Открытые модели (Open Weights) вроде Qwen (32B/72B), DeepSeek или Kimi уже работают локально или на собственных серверах компаний на уровне закрытых флагманов. Инженерия не умирает — ее объект смещается с написания строк кода на проектирование систем, которые пишут, тестируют и поддерживают софт под контролем человека.

Тайминг: ▶ 17:92, ▶ 32:04, ▶ 33:49, ▶ 34:11, ▶ 34:61, ▶ 36:38, ▶ 37:01

Выгода: Инвестиции в фундаментальные навыки архитектуры, безопасности, API и Harness защищают карьеру разработчика от любых колебаний рынка LLM и закрытия коммерческих API.

Как применить:

• Шаг 1: Абстрагирование провайдера моделей — Не завязывайте кодовую базу на уникальные фичи одного вендора. Используйте прокси-слой или открытые стандарты (OpenAI-compatible API, LiteLLM, Ollama, vLLM).
• Шаг 2: Тестирование локальных моделей с открытыми весами — Разверните локально модель класса Qwen 2.5 Coder 32B через Ollama и проверьте работу вашего базового Harness на ней.
• Шаг 3: Фокус на архитектурных дисциплинах — Развивайте навыки проектирования распределенных систем, моделирования баз данных и CI/CD — именно они определяют качество сборки Harness.

# Запуск локальной open-source модели для кодинга через Ollama
ollama run qwen2.5-coder:32b
 
# Проверка OpenAI-совместимого эндпоинта для интеграции в Harness
curl http://localhost:11434/v1/chat/completions \
  -H "Content-Type: application/json" \
  -d '{
    "model": "qwen2.5-coder:32b",
    "messages": [{"role": "user", "content": "Напиши TypeScript функцию валидации JWT"}]
  }'

Результат: Независимость проектов от коммерческих API (OpenAI/Anthropic) и полная готовность инфраструктуры к работе на автономных локальных мощностях.

AI-инженерия и Harness: ответы на частые вопросы

В: Почему генерация кода с помощью AI не делает разработку готового продукта мгновенной? О: Потому что код — это лишь верхний слой продукта. Настоящая сложность заключается в подводной части: учете исторических решений, обратной совместимости, интеграции сервисов, правах доступа и бизнес-правилах. Кроме того, быстрый вероятностный код создает большой объем работы по проверке (Verification Tax), который требует глубокой экспертизы человека.

В: Что такое Harness простыми словами? О: Harness (управляющая среда) — это весь инженерный обвяз вокруг нейросети: правила (CLAUDE.md), инструменты (MCP), базы знаний (RAG), долгосрочная память, тесты (Evals), логирование и ограничения (Guardrails). Он превращает вероятностный чат-бот в стабильного программного агента.

В: Зачем нужен протокол MCP, если можно просто передать код в промпте? О: MCP стандартизирует подключение агента к внешнему миру. Вместо ручного копирования данных агент через MCP сам безопасно обращается к файлам проекта, базе данных, Git-репозиторию, логам или внешним API, получая актуальное состояние системы на лету.

В: В чем разница между классическими тестами и Evals? О: Классические тесты (Unit/E2E) проверяют, работает ли сам софт (программа). Evals проверяют, насколько качественно работает агент, создающий этот софт: правильные ли инструменты он вызвал, следовал ли инструкциям, нашел ли нужные документы и не ухудшилось ли его качество при переключении на другую модель.

В: Нужно ли учить математику и Machine Learning, чтобы стать AI-инженером? О: Нет. AI-инженер в современной парадигме — это софтверный практик и архитектор, который строит инфраструктуру, промпты, пайплайны и интеграции вокруг готовых LLM. Для этого требуются сильные классические навыки (TypeScript/Python, базы данных, API, CI/CD, архитектура систем), а не обучение весов с нуля.

В: Что будет с AI-разработкой, если вендоры вроде OpenAI или Anthropic закроются? О: Технология останется на рынке. В открытом доступе уже есть мощные модели с открытыми весами (Open Weights), такие как Qwen 2.5 Coder, DeepSeek и Kimi. При наличии качественного Harness компании могут запускать эти модели на своих серверах без потери производительности.

В: С чего начать создание Harness в своем репозитории прямо сегодня? О: Начните с создания файла CLAUDE.md (или AGENTS.md) в корне проекта. Опишите в нем стек, команды сборки/тестов, архитектурные ограничения и жесткий запрет на изменение критических файлов (.env, миграции БД) без подтверждения человеком.

AI-инженерия и Harness: инструменты и ссылки из видео

• SWE-bench (GitHub Issues Benchmark) — бенчмарк оценки решения реальных инженерных задач моделями искусственного интеллекта — https://www.swebench.com/ (упомянут в видео).
• Anthropic Research: Building Effective Context Windows — исследование по анатомии и конструированию эффективного контекстного окна — упомянуто в видео.
• Anthropic Research: Effective Harness for Long-Running Agents — исследование по проектированию управляющей среды (Harness) и чек-листов для агентных систем — упомянуто в видео.
• Stanford AI Engineering Practices Benchmark — классификация зрелости внедрения AI в репозиториях от L0 до L4 — упомянуто в видео.
• METR (Model Evaluation and Threat Research) — исследовательская организация по оценке автономности моделей — упомянута в видео.
• Практикум «AI-инженер: Собери свою собственную Agentic-систему» — авторская программа по разработке агентных систем на TypeScript — упомянута автором в видео.
• Отель «Шинрин-йоку» (Shinrin-Yoku) — загородный отель под Санкт-Петербургом, локация съемок видео — упомянут в видео.

Конспект создан на основе видео «Почему программисты теперь не пишут код? Архитектура Harness, AI-инженеры и новый подход в IT» канала [Владилен Минин]. Все права на оригинальный материал принадлежат авторам. Источник: https://www.youtube.com/watch?v=WT0yDhfOjaA