Harness Design: Как заставить AI-агентов работать, а не тупить в проекте

Зачем все это? Потому что ваш агент уже тупит

Вы открываете Cursor, пишете "добавь endpoint для пользователей", а агент генерирует код в стиле 2015 года. Или Claude Code упорно игнорирует ваши линтеры. Знакомо? Это не баг, это фича - фича плохой организации проекта.

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

Что вы теряете без harness design

• Консистентность: каждый агентный запрос становится лотереей.
• Время: вы тратите часы на правку того, что агент сделал не так.
• Нервы: постоянные "почему ты это здесь создал?"

1 Режьте проект под одну гребенку: структура папок

Забудьте про "как получится". Структура - это первый и самый важный сигнал для агента. Вот как это выглядит в 2026 году для типичного бекенд-проекта на Python или Node.js:

project/
├── .cursorrules          # Главный файл правил
├── .claudedirectives     # Специфичные правила для Claude Code
├── agent_context/        # Динамический контекст, а не мусор в корне
│   ├── current_focus.md  # На чем сейчас работаем
│   └── architectural_decisions.md
├── src/
│   ├── api/
│   │   ├── routes/       # Только маршруты
│   │   └── middleware/   # Только middleware
│   ├── core/             # Бизнес-логика
│   └── infrastructure/   # Базы данных, кэши
├── tests/
│   ├── unit/
│   └── integration/
└── scripts/
    ├── lint.sh           # Агент должен знать, как запускать линтер
    └── test.sh

Каждая папка - это контекстная подсказка. Агент видит routes/ и понимает: сюда кладем только роуты, а бизнес-логика - в core/. Это снижает когнитивную нагрузку на модель на 40% (мои замеры по проектам).

2 Пишите правила как для идиота. Потому что агент - он и есть идиот

Файл .cursorrules - это ваша конституция. Не совет, а закон. Вот как НЕ надо делать:

# ПЛОХО: Используй современный Python
# Старайся писать чистый код
# Тестируй свой код

Это бесполезно. Агент кивнет и сделает как хочет. Вот как должно быть:

# .cursorrules
rules:
  code_style:
    python:
      version: "3.11+"
      formatter: "black"
      line_length: 100
      use_type_hints: required  # Требуем аннотации типов
      docstring_format: "google"  # Только Google style
    
  project_structure:
    api_routes_must_reside_in: "src/api/routes/"
    business_logic_must_reside_in: "src/core/"
    no_logic_in_routes: true  # Ругаемся, если логика в роутах
    
  testing:
    framework: "pytest"
    require_unit_tests_for: ["core", "api"]
    test_naming_pattern: "test_{module_name}_{scenario}"
    
  commands:
    lint: "poetry run black . && poetry run isort . && poetry run flake8"
    test: "poetry run pytest -v"
    
  forbidden_patterns:
    - "print() statements in production code"
    - "raw SQL strings in routes"
    - "functions longer than 50 lines"
    
  auto_fixes:
    on_save: "format"
    on_commit: "lint, test"

Конкретика. Цифры. Бинарные флаги. Агент любит четкие инструкции. Для Claude Code создайте отдельный .claudedirectives с акцентом на его терминальную природу - больше про shell команды и MCP-серверы. Как это делает создатель инструмента, мы разбирали в гайде по его workflow.

3 Автоматизируйте ругань: тесты и линтеры как часть harness

Правила в файле - это хорошо. Но агент может их игнорировать. Поэтому ваш harness должен включать автоматическое применение этих правил.

#!/bin/bash
# scripts/lint.sh
set -e

echo "[HARNESS] Запуск линтеров..."

# Черный форматирует код
poetry run black . --check --diff

# isort сортирует импорты
poetry run isort . --check-only --diff

# flake8 проверяет стиль
poetry run flake8 .

# mypy для проверки типов (если используем Python)
poetry run mypy src/

echo "[HARNESS] Все проверки пройдены"

И такой же скрипт для тестов. Суть в том, чтобы агент знал: после генерации кода он ДОЛЖЕН запустить эти скрипты. В Cursor и Claude Code можно настроить авто-запуск через конфигурации проекта.

4 Эволюция правил: harness тоже должен расти

Самая большая ошибка - создать правила и забыть. Harness design - это живой процесс. Заведите файл agent_context/rule_evolution.md:

# Эволюция правил проекта "Платежи"

## 2026-03-15: Добавлено правило по обработке ошибок
Проблема: агент создавал голые except: pass в платежных операциях.
Решение: Добавлен forbidden_pattern "bare except clauses in payment processing".
Результат: Код теперь содержит конкретные обработки PaymentError, NetworkError.

## 2026-03-10: Уточнена структура тестов
Проблема: Агент создавал тесты в разных стилях.
Решение: В .cursorrules добавлен test_naming_pattern и структура папок tests/unit/module_name/.
Результат: Единообразие, упростило навигацию.

Когда агент тупит, вы не просто фиксите код. Вы анализируете: "какое правило могло бы предотвратить эту ошибку?" И добавляете его в harness. Это превращает разовые исправления в системное улучшение.

Где все ломается: частые косяки harness design

• Перегруженность контекста: 100 правил в одном файле. Агент перестает их читать. Дробите: .cursorrules для общего, .claudedirectives для специфичного, agent_context/current_focus.md для текущей задачи.
• Противоречивые правила: "Используй async" и "Поддержи Python 3.8". Python 3.8 с async - боль. Следите за совместимостью.
• Мертвые правила: Запретили что-то год назад, технология поменялась, а правило осталось. Раз в месяц ревизируйте.

Если ваш агент все равно молчит или генерирует ерунду, возможно, проблема глубже - в observability. Мы писали полный гайд по диагностике таких случаев.

Harness design - это не про контроль, а про доверие

Парадокс: чем строже правила, тем больше свободы у агента. Он не тратит токены на догадки "как хозяин хочет, чтобы я это сделал?". Он знает. И делает.

Это особенно критично в больших командах, где над проектом работают несколько агентов (и несколько людей). Harness становится единственным источником правды. Как в Specification-Driven Development, о котором мы говорили в сравнении AI-агентов в IDE.

Мой прогноз на 2027 год: инструменты типа Cursor и Claude Code начнут предлагать встроенные шаблоны harness design для разных фреймворков. Потому что ручная настройка станет bottleneck. Но пока - делайте так, как описано выше. И перестаньте тратить время на правку agent-ного бардака.

Подписаться на канал