Вайбкодинг без бардака: правила, которые действительно экономят часы

В одной ветке Threads автор попросил вайбкодеров поделиться промптами, репозиториями, MCP-серверами и другими находками, которые экономят время. Самые содержательные ответы оказались удивительно приземлёнными. Люди советовали вести документацию, понимать архитектуру, фиксировать изменения в Git и заставлять агента проверять результат в браузере.

Короткую версию этих советов я уже собрал в материале «Вайбкодинг без разрушений: 10 правил рабочего процесса». Здесь разберём следующий уровень: как превратить отдельные правила в рабочий контур, который можно положить в новый проект и начать использовать сегодня.

Цель такого контура проста. Модель должна понимать, куда движется проект, видеть границы текущей задачи и доказывать результат проверками. Человек при этом сохраняет возможность остановить эксперимент, разобраться в изменениях и вернуться к рабочему состоянию.

Бардак начинается до первой строки кода

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

Перед первым промптом зафиксируйте пять строк:

ПОЛЬЗОВАТЕЛЬ: кто получит результат
ПРОБЛЕМА: что сейчас мешает этому человеку
РЕЗУЛЬТАТ: что он сможет сделать после изменения
ПРОВЕРКА: по какому наблюдаемому признаку результат принят
НЕ ДЕЛАЕМ: что сознательно не входит в эту итерацию

Если неизвестно, кому нужен продукт, сначала проверяйте спрос: разговором с будущими пользователями, ручным прототипом, демонстрацией или попыткой продажи. Маленький трекер может быть нормальным рыночным зондом. Полугодовая разработка без обратной связи остаётся дорогой догадкой, даже когда большую часть кода написал ИИ.

Оставьте модели карту проекта

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

У Codex для постоянных проектных инструкций есть `AGENTS.md`. По официальной документации Codex читает эти файлы перед работой и собирает цепочку правил от глобального уровня к текущей папке. Инструкции, расположенные ближе к рабочему файлу, уточняют более общие правила. В других инструментах ту же роль может играть RULES.md, CLAUDE.md или другой явно подключённый файл.

Минимальная проектная память может выглядеть так:

project/
├── AGENTS.md
├── TODO.md
├── CHANGELOG.md
└── docs/
    ├── architecture.md
    ├── product-flow.md
    └── modules/
        ├── auth.md
        └── billing.md

У каждого элемента своя работа:

• AGENTS.md хранит правила, границы, команды проверки и критерии готовности;
• architecture.md объясняет компоненты и связи между ними;
• документы модулей фиксируют локальные контракты и ограничения;
• TODO.md показывает незавершённую работу;
• CHANGELOG.md сохраняет историю значимых решений;
• product-flow.md описывает экраны, состояния и переходы пользователя.

Последний файл необязательно должен быть текстом. Для интерфейсного продукта схема в FigJam, Figma или на простой доске часто быстрее показывает пропущенное состояние, чем длинное описание.

Память помогает только пока совпадает с реальностью. Не заводите семь документов ради красивого дерева папок. Начните с AGENTS.md, схемы продукта и одного файла текущего состояния. Добавляйте следующий документ, когда без него агент уже повторил ошибку или потерял важное решение.

Короткий шаблон AGENTS.md

Хороший файл правил не обязан быть большим. Для первого проекта достаточно такого каркаса:

# AGENTS.md

## Цель проекта
Одним абзацем: для кого продукт и какую задачу решает.

## Архитектура
- клиентская часть: где находится и за что отвечает
- серверная часть: где находится и за что отвечает
- данные: какие хранилища используются

## Рабочие правила
- перед изменениями читать ближайшую документацию;
- не менять файлы вне текущей задачи;
- не добавлять зависимости без обоснования;
- сохранять совместимость перечисленных контрактов.

## Проверки
- команда сборки;
- команда тестов;
- основной пользовательский сценарий в браузере.

## Готово, если
- критерий пользователя выполнен;
- проверки прошли;
- изменения (`git diff`) просмотрены;
- известен способ отката.

Не помещайте сюда биографию проекта и копию всей документации. AGENTS.md должен отвечать на вопросы, которые возникают почти в каждой задаче. Подробности конкретного модуля лучше хранить рядом с этим модулем.

Одна задача должна помещаться в один пакет

Фраза «сделай приложение» оставляет модели слишком много решений сразу. Она сама выбирает архитектуру, объём, дизайн, способ хранения данных и критерий завершения. Результат может выглядеть убедительно, но проверить его почти невозможно.

Перед работой собирайте короткий пакет задачи:

ЦЕЛЬ: какое изменение нужно выполнить
ПОЛЬЗОВАТЕЛЬСКИЙ РЕЗУЛЬТАТ: что станет возможно после него
КОНТЕКСТ: какие файлы и документы нужно прочитать
ИЗМЕНИТЬ: точные компоненты или экраны
НЕ ТРОГАТЬ: данные, сервисы и соседние модули вне задачи
ПРОВЕРИТЬ: тесты и реальный сценарий
ОТКАТ: к какому состоянию возвращаемся при неудаче

Такой пакет ограничивает пространство решений. Агент может самостоятельно работать внутри него, а выход за границы становится заметным событием, которое требует отдельного решения.

Повторяемый цикл одного изменения

Рабочий процесс удобно собирать из семи шагов.

1. Прочитать текущее состояние. Проверить инструкции, документацию, git status и код затрагиваемого модуля.
2. Назвать наблюдаемый результат. Например: после отправки формы пользователь видит подтверждение, а запись появляется в списке после перезагрузки.
3. Ограничить изменение. Выбрать один сценарий и конкретные файлы. Соседнее улучшение отправить в отдельную задачу.
4. Внести правку. Сохранить существующие контракты и не добавлять инфраструктуру без доказанной необходимости.
5. Запустить машинные проверки. Сборка, типы, линтер и тесты должны соответствовать правилам проекта.
6. Проверить поведение. Пройти сценарий в реальном интерфейсе и зафиксировать, что увидит пользователь.
7. Просмотреть изменения и сохранить контрольную точку. После успешных проверок зафиксировать ограниченное изменение в Git или другом принятом журнале версий.

Каждая правка обнуляет предыдущую проверку затронутого поведения. Если после теста агент «заодно» поправил ещё один компонент, этот компонент тоже нужно проверить.

«Готово» начинается с браузера

Сообщение агента о завершении задачи подтверждает только то, что агент перестал редактировать файлы. Пользовательский результат появляется позже: когда приложение запускается и нужный сценарий действительно работает.

Playwright позволяет описывать действия пользователя и проверять состояние страницы. Его web-first assertions повторяют проверку до ожидаемого результата или тайм-аута, а проверки actionability помогают не нажимать на невидимый или недоступный элемент.

Chrome DevTools MCP даёт агенту доступ к живому Chrome: странице, консоли, сетевым запросам, скриншотам и данным производительности. Это полезный канал наблюдения, но само подключение к браузеру ничего не доказывает. До начала работы нужно сформулировать ожидаемое поведение.

Минимальный контрольный проход в браузере для пользовательской функции:

• открыть страницу с чистого состояния;
• выполнить основной сценарий;
• проверить успешный результат и одно ошибочное состояние;
• обновить страницу, если результат должен сохраняться;
• посмотреть консоль и критичные сетевые запросы;
• проверить интерфейс хотя бы на основном настольном и мобильном размере.

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

Git превращает эксперимент в обратимое изменение

Git хранит историю проекта как последовательность снимков. В книге Pro Git коммит описывается как сохранение снимка подготовленного состояния, который позже можно сравнить с другими версиями или восстановить.

Для работы с агентом полезны четыре привычки:

• начинать эксперимент с понятного рабочего состояния;
• просматривать изменения через git diff перед фиксацией;
• делать отдельный коммит на одно законченное изменение;
• отправлять проверенную историю в согласованный удалённый репозиторий.

Удалённый репозиторий даёт дополнительную копию истории и облегчает проверку. Он не спасает изменения, которые остались только в рабочей папке и не попали в коммит. Секреты, локальные конфиги и тяжёлые сгенерированные файлы нельзя отправлять туда автоматически.

Запретите неопределённые «улучшения»

Опасный промпт выглядит безобидно:

Улучши этот экран и приведи код в порядок.

У него нет границы. Агент может поменять вёрстку, тексты, зависимости, структуру компонентов и поведение формы. После этого непонятно, какое изменение требовалось и что считать регрессией.

Рабочая формулировка описывает дефект и результат:

На экране оплаты при ширине 390 px основная кнопка уходит ниже видимой области.
Сделай кнопку доступной без горизонтальной прокрутки.
Не меняй тексты, серверную часть и платёжную логику.
Проверь экран на 390 × 844 и 1440 × 900, затем покажи изменения через git diff.

Если система уже выполняет согласованный контракт, предложение «сделать ещё лучше» отправляется в список будущих задач с отдельной причиной. Неограниченное улучшение работающего кода быстро превращается в источник новых ошибок.

Навыки Codex появляются после повторяемого процесса

Когда один и тот же порядок работы повторился несколько раз, его можно вынести в навык Codex (skill). В официальной документации OpenAI так называется пакет инструкций, ресурсов и необязательных скриптов для надёжного выполнения конкретного рабочего процесса. Основой служит SKILL.md; рядом могут находиться папки references, scripts и assets.

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

• обязательный вход;
• порядок проверок;
• разрешённые изменения;
• условия остановки;
• формат доказательства результата.

Если каждый запуск требует переписывать половину инструкции, процесс ещё не стабилизировался. Продолжайте собирать наблюдения вместо того, чтобы прятать неопределённость в автоматизацию.

Установочный проход на один час

Для небольшого существующего проекта минимальный контур можно собрать за один короткий проход. Час здесь служит ориентиром, а не обещанием для любого репозитория.

1. Первые 10 минут: сформулируйте пользователя, проблему, результат и границы продукта.
2. Следующие 10 минут: создайте короткий AGENTS.md с архитектурой, правилами и командами проверки.
3. Ещё 10 минут: опишите главный пользовательский путь и состояния интерфейса.
4. Ещё 10 минут: подготовьте пакет ближайшей задачи с ИЗМЕНИТЬ, НЕ ТРОГАТЬ, ПРОВЕРИТЬ и ОТКАТ.
5. Ещё 10 минут: добавьте ручной или автоматический браузерный сценарий.
6. Последние 10 минут: проверьте рабочее состояние и сохраните понятную контрольную точку в Git.

На выходе получится минимальная система управления. Она позволяет новому чату или агенту продолжить работу без археологии по старым сообщениям.

Чек-лист перед следующей задачей

• Пользовательский результат сформулирован одним предложением.
• Границы задачи перечислены явно.
• Агент прочитал актуальные проектные правила.
• Текущее рабочее состояние сохранено.
• Изменяется один ограниченный сценарий.
• Команды проверки известны заранее.
• Пользовательский путь проверяется в интерфейсе.
• Изменения просмотрены человеком или независимым проверяющим.
• Изменение можно откатить.
• Следующий шаг записан вне чата.

Вайбкодинг становится управляемым, когда скорость генерации окружена памятью, границами и проверками. Модель по-прежнему пишет большую часть кода. Ответственность за задачу, архитектуру и принятый результат остаётся у человека.

Источники

• Custom instructions with AGENTS.md — OpenAI Docs
• Build skills — OpenAI Docs
• Writing tests — Playwright
• Chrome DevTools MCP — официальный репозиторий
• What is Git? — Pro Git

Следующий шаг

AGENTS.md / SESSION_NOTES — проектная память для coding-агентов

Связанные материалы

• Статья: Сначала архитектура, потом код: зачем ИИ-агенту контрольные барьеры
• Блог: Вайбкодинг без разрушений: 10 правил рабочего процесса
• База знаний: GitHub для новичков: регистрация, репозиторий, Git и Pull Request

Этот контур пригодится тем, кто уже разрабатывает с ИИ и хочет сделать процесс предсказуемым для себя или команды.

Если захотите обсудить, как это применить у себя или в команде — пишите в Telegram @pimenov