Как удержать AI coding agents от галлюцинаций: Harness Engineering
AI coding agents вроде Claude Code и Devin умеют рефакторить модули и открывать pull request — но в «голом» репозитории без границ они быстро уходят в scope drift и «process theater». Гайд Harness Engineering на Dev.to предлагает другой путь: вместо универсальных промптов — структурный harness внутри проекта, вдохновлённый coding-практиками Andrej Karpathy.
Три поломки агента, когда репозиторий «голый»
Типичные сбои coding agents в workspace без учётных правил автор называет тремя именами. Context window pollution — в контекст попадает лишний шум, и агент опирается на нерелевантные фрагменты. Agent amnesia — потеря нити между шагами: агент забывает, что уже проверял или менял. Scope drift — уход за пределы задачи: вместо точечного bug-fix агент переподключает половину проекта.
На практике картина хуже. Простой рефакторинг может растянуться в шестичасовой цикл: агент удаляет несвязанные тесты, трогает чужие модули и застревает в бесконечных промежуточных шагах без проверяемого результата. Именно от таких галлюцинаций и «театра процесса» harness и должен защищать — не обещая процентов accuracy, а задавая физические границы работы агента.
Agent Harness: контрольный слой вместо монолитного промпта
Agent Harness — не ещё один system prompt на две тысячи слов. По определению из гайда, это структурированный локальный контрольный слой внутри репозитория, который направляет и верифицирует работу coding agent. Вместо монолитной инструкции в чат автор предлагает встроить в workspace лёгкую систему учёта и feedback loops, которые агент видит при каждом заходе в проект.
Точка входа — файл AGENTS.md: глобальный роутер с Priority Kernel (ограничения ответов, English defaults, local-first поведение). Остальные правила разнесены по специализированным markdown-файлам в репозитории MasihMoafi/harnesses-I-use:
| Файл | Роль в harness |
|---|---|
CODEX_CODING_GUIDELINES.md |
Хирургические правила кодинга по мотивам Karpathy |
TERMINAL_AND_GIT_RULES.md |
Безопасная навигация в терминале и жёсткий git scope |
SESSION_HANDOFF_RULES.md |
Передача state между сессиями агента |
ARTIFACT_RULES.md |
Проверяемые визуальные и математические артефакты |
abbn.md |
Словарь сокращений для экономии токенов (ctu, fmy, ver) |
Суть в том, что агент читает не абстрактное «будь осторожен», а конкретные файлы рядом с кодом. Harness становится частью репозитория — и частью контекст-инжиниринга на уровне проекта, а не разового промпта.
Правила harness по мотивам Karpathy
Связь с Andrej Karpathy автор проводит через open-source education repos micrograd и makemore: минимум bloat, воспроизводимые математические baselines, отказ от over-engineering. На этом фоне в harness выделяются три core rules:
- Surgical Changes — трогать только запрошенные строки; без drive-by рефакторинга соседнего кода.
- Verifiable Outcomes — до заявления о готовности фичи агент запускает локальный скрипт верификации baseline, компилирует код и прикладывает raw terminal output к записи сессии как физическое доказательство.
- Harness Simplification — каждое правило считается overhead; по мере «умнения» моделей правила нужно тестировать и удалять избыточные.
Практические ограничения из TERMINAL_AND_GIT_RULES.md иллюстрируют второй принцип. Агенту запрещён широкий захват изменений:
# never
git add -A
Для операций с root вместо raw CLI password prompts предлагается Ubuntu pkexec. SOCKS/HTTP proxy и явный git scope — не паранойя, а способ не дать агенту «улететь» в соседние каталоги. Harness здесь работает как набор физических рельс, а не как пожелание в чате.
Кейс Sensor Fault Diagnosis: от датасета до отчёта
Чтобы показать harness в деле, автор приводит case study Sensor Fault Diagnosis — сравнительный ML-проект, собранный с этим набором правил. Пайплайн включает синтетический sensor dataset, обучение Gaussian Naive Bayes с mapping conditional probabilities, PyTorch MLP, сравнение loss-функций (Binary Cross-Entropy, micrograd-style Max-Margin (Hinge) loss, makemore-style Cross-Entropy loss), экспорт ROC curves и decision boundaries, генерацию publication-grade LaTeX/HTML research paper.
С harness coding agent завершил весь pipeline и написал финальный отчёт автономно. Без harness, по словам автора, тот же агент раздул бы репозиторий decorative dashboard scripts или fake performance metrics — harness «держал его grounded». Количественных бенчмарков прироста accuracy в материале нет; акцент на качественном контрасте поведения агента с ограничениями и без.
С чего начать свой repository harness
Вывод гайда сформулирован жёстко: вместо наращивания длинных system prompts стоит строить repository harnesses — markdown-правила, роутинг через AGENTS.md, жёсткий terminal/git scope и требование верифицируемых артефактов. Шаблоны лежат в MasihMoafi/harnesses-I-use; дополнительный контекст — на сайте автора masihmoafi.tech.
Для команд, которые уже пускают Claude Code, Devin или open-source агентов в production-репозитории, это смена фокуса. Точность coding agent, по логике материала, растёт не от очередного «будь аккуратнее», а от структуры workspace: правила handoff между сессиями, словарь сокращений для короткой коммуникации, локальная верификация HTML-layout, MathML для формул, инспекция PDF. Harness Engineering — дисциплина репозитория, в которой агенту нечего галлюцинировать: каждый шаг должен оставить проверяемый след в терминале или артефакте.
Источники
- Masih Moafi — «How to Keep AI Coding Agents from Hallucinating: A Guide to Harness Engineering» (Dev.to, 14 июня 2026): Dev.to
- Шаблоны harness: репозиторий MasihMoafi/harnesses-I-use (ссылка в теле статьи на Dev.to)
- Сайт автора: masihmoafi.tech (упомянут в гайде)