Пятого сентября 2026 года на Hacker News появился пост с провокационным названием «User-guide-driven development with coding agents». Автор — разработчик под ником hosamsh — описал эксперимент, к которому его подтолкнул простой вопрос: если агенты пишут почти весь код, что человеку остаётся держать в руках как «источник истины»? Его ответ — пользовательский гайд и мокапы, а не тесты. Разбор ниже — по оригинальному посту и единственному на тот момент комментарию от gojkoa, который пробовал похожее ещё двадцать лет назад.
Что именно предложил автор
Хосамш рассуждает так: раньше код был тем, что человек писал сам, а потому хорошо знал. Теперь код пишет агент, и человек превращается в ревьюера. Проблема — в чём ревьюить: диффы на сотни строк читать тяжело, юнит-тесты проверяют код, а не то, нужный ли продукт получился.
Since agents now own most, if not all of the coding process, I’ve been wondering what would be the best durable and reviewable source of truth for the human side to own.
Раз агенты владеют почти всем процессом написания кода, я задумался, какой будет лучший долговечный и проверяемый источник истины для человеческой стороны.
— hosamsh, HN 49579372, 05.09.2026
Его ответ — писать сначала гайд для пользователя и мокапы экранов, а агентам позволить итерировать до тех пор, пока поведение не совпадёт с гайдом. Цикл выглядит так:
Дальше идёт самая спорная часть:
I’ve almost stopped using unit tests and create user-experience instead, i.e. a context-less agent goes through the guide and tries to follow it literally before the work is considered done.
Я почти перестал использовать юнит-тесты и вместо них делаю «пользовательский опыт»: агент без контекста проходит по гайду и пытается следовать ему буквально — и только тогда работа считается готовой.
— hosamsh, HN 49579372, 05.09.2026
Ключевых идей здесь три, и каждая стоит отдельного разбора:
- Гайд — единый источник истины. Один документ описывает и то, что строим, и то, как проверить, что построили. Его читает и человек (при ревью), и агент (при реализации и при проверке).
- Проверка через «пользовательский опыт», а не юниты. Вместо «ассерт должен быть зелёным» — «агент в новой сессии должен суметь пройти по гайду буквально». Это сквозной сценарий, а не проверка одной функции.
- Контекст-less прогон как защита от самообмана. Агент, который только что написал код, помнит, что он хотел сделать, и легко «подтверждает», что всё работает. Прогон в свежей сессии без памяти о реализации имитирует нового пользователя — и агента без уверенности автора.
Автор честно пишет, где сам сомневается:
tbh though, I’m not sure how far this approach can scale. I’m curious where people think this breaks.
Если честно, я не уверен, как далеко этот подход можно масштабировать. Мне интересно, где, по мнению людей, он ломается.
— hosamsh, HN 49579372, 05.09.2026
Что отвечает оппонент: гайд не заменяет спецификацию
Под постом на момент съёмки был один развёрнутый комментарий — от gojkoa, который признаётся, что пережил две похожие попытки двадцать лет назад, ещё до агентов.
The problem with user guides in general as a driver of specs is that user guides tend to be written for an external audience, hiding a lot of complexity and underlying details.
Проблема гайдов как драйвера спецификаций в том, что гайды пишутся для внешней аудитории и прячут большую часть сложности и внутренних деталей.
— gojkoa, HN 49580093, 05.09.2026
Гайд умалчивает о внутреннем устройстве намеренно: пользователю не нужно знать, почему кнопка сериализует запрос в очередь, а не пишет в базу напрямую. Но именно эти детали определяют, не сломается ли система под нагрузкой и не протечёт ли она данные.
Specs can influence (and potentially be even a source for generating parts of) user docs, but user docs can’t replace specs.
Спецификации могут влиять на пользовательскую документацию (и потенциально даже быть источником для её частей), но пользовательская документация не может заменить спецификации.
— gojkoa, HN 49580093, 05.09.2026
При этом gojkoa признаёт ценность половины идеи: писать гайд и мокапы до спецификации — хороший способ продумать пользовательский опыт до того, как начнётся проектирование. В его команде агенты создают демо-страницы, команда проверяет их, и они становятся частью спецификации и эталоном для финального продукта. Ломается подход, по его словам, там, где у системы нет пользовательского интерфейса: бэкенд-процессы, сквозные задачи (производительность, безопасность) и функции, которые нужны бизнесу, а не пользователю — например, борьба с платёжным мошенничеством.
Где подход реально силён
Скепсис оппонента не отменяет того, что в идее есть зерно, которое объясняет, почему автор чувствует себя «более в контроле».
Гайд — документ, который не врёт о назначении. Юнит-тест отвечает на вопрос «работает ли код так, как задумано», но задумка остаётся в голове разработчика или в комментариях. Гайд фиксирует назначение снаружи: «пользователь вводит адрес — система показывает ближайший офис». Если агент реализует не то, расхождение видно сразу при чтении гайда.
Он читается человеком без исполнения. Чтобы проверить юнит-тест, его надо запустить; чтобы понять, что он проверяет, — прочитать код теста. Гайд читается как обычный текст. Для ревьюера это дешевле: не нужно мысленно исполнять ассерты, чтобы понять, что система должна делать.
Прогон по гайду проверяет связность, а не функцию. Юнит-тесты по построению изолированы: каждый проверяет свой модуль. Интеграционные баги — «кнопка есть, но данные не доходят» — юниты не ловят. Агент, буквально проходящий по гайду от первого экрана до конца, проверяет именно сквозной путь.
Свежая сессия — честный ревьюер. Автор подмечает важную особенность агентов: в длинной сессии агент накапливает контекст и начинает «подтверждать» собственные решения. Контекст-less прогон — это проверка «верит ли в продукт кто-то, кто не писал код». Прямая аналогия — практика чистки контекста в длинных сессиях, о которой мы писали в материале про контекст Claude Code и в кейсе сокращения контекста агента на 80%.
Где подход ломается
Соберём места отказа — из комментария gojkoa, оговорок автора и свойств метода.
| Место отказа | Почему ломается |
|---|---|
| Бэкенд без интерфейса | API, очереди, воркеры не имеют «пользовательского пути», по которому можно пройти буквально |
| Регрессии | Без юнит-тестов нет быстрой сетки «всё ли старое поведение живо»; проверка по гайду покрывает только описанные пути |
| Края и ошибки | Гайд описывает счастливый путь; что происходит при отказе платёжного шлюза или пустой выдаче — в гайд не пишут |
| Производительность | Поведение «быстро» гайдом не проверить: агент не замерит latency на нагрузке |
| Безопасность | Требования защиты (fraud prevention, аудит, ограничение прав) невидимы пользователю и в гайд не попадают |
| Большие системы | При десятках экранов и ролей гайд превращается в простыню, которую ни человек, ни агент не держат в голове целиком |
Отдельно — масштаб проверки. Юнит-тест прогоняется за миллисекунды и автоматически, в CI, на каждом коммите. Прогон «агент идёт по гайду» — это полноценная сессия с моделью: минуты, токены, и её надо инициировать вручную или аккуратно автоматизировать. Как автоматизировать сквозную проверку поведения через агента — отдельная тема, частично разобранная в статье про AI-тесты на pytest и Playwright.
Чем это отличается от TDD и spec-подходов
Чтобы понять место метода, полезно разложить три подхода рядом.
| Подход | Что является «источником истины» | Что проверяется | Стоимость прогона |
|---|---|---|---|
| TDD | Красный тест → код | Поведение модуля | Миллисекунды, автоматически |
| Specification by example / BDD | Сценарии на языке пользователя | Поведение системы на примерах | Секунды-минуты, автоматически |
| User-guide-driven (кейс) | Гайд + мокапы | Способность агента пройти путь буквально | Минуты, полуавтоматически |
TDD и BDD проверяют, что система соответствует ожидаемому поведению, описанному в исполняемых примерах. User-guide-driven проверяет, что агент сумел воспроизвести путь, описанный в тексте для человека. Разница в том, где живёт критерий: в коде теста или в тексте гайда.
По сути, hosamsh предложил крайнюю форму documentation-driven: не «пиши документацию параллельно с кодом», а «документация пользователя — и есть спецификация, а код подгоняется под неё». У этого есть почтенная родословная — идея «сначала руководство, потом продукт» старше агентов. Новое здесь — что проверку по гайду теперь может исполнять агент, и это приближает текстовую документацию к статусу исполняемой спецификации. Смежную рамку — где в агентной разработке живёт доверие и почему нужны проверяемые требования и evidence — подробно разбирает Скотт Спенс в гайде по agentic engineering.
Как попробовать на маленьком проекте
Если эксперимент зацепил, пробовать стоит не на продакшене, а на небольшой утилите — как и сам автор. Порядок шагов:
- Напишите гайд. Markdown-файл
docs/user-guide.md: что делает пользователь от первого запуска до завершения сценария, какими словами, что видит на каждом шаге. Пишите как для человека, который ничего не знает о системе. - Нарисуйте мокапы. HTML-страницы, SVG-эскизы или картинки экранов — то, на что агент может смотреть. Мокапы — визуальная часть спецификации.
- Подключите гайд к правилам проекта. Строка в AGENTS.md: «реализация должна соответствовать docs/user-guide.md и docs/mockups/. Не добавляй функций, которых нет в гайде». Про то, как строить такие файлы, — в статье про AGENTS.md.
- Дайте агенту задачу реализовать по гайду. Пример промпта:
Прочитай docs/user-guide.md и мокапы из docs/mockups/. Реализуй
приложение, которое ведёт себя ровно так, как описано в гайде:
те же шаги, те же экраны, те же ответы системы. Не добавляй ничего,
чего нет в гайде. Сначала покажи план, потом код.
- Проверяйте свежей сессией. После того как агент сообщит о готовности, откройте новую сессию без контекста и дайте задание:
Запусти приложение. Пройди по docs/user-guide.md буквально, как
пользователь: каждый шаг, каждый экран. Где поведение не совпадает
с гайдом — перечисли расхождение с номером шага. Ничего не чини,
только отчитайся.
- Не удаляйте юнит-тесты там, где они зарабатывают место. Критерий из недавней дискуссии про агента, который чистит бесполезные тесты: тест, который не может упасть при поломке поведения, — расходы. Но тест, который ловит регрессию чистого модуля (парсер, валидатор, расчёт), — дешёвая страховка, и её стоит оставить. Автор кейса работал с «small utils»; на них и юниты, и гайд-прогон уживаются.
Российские реалии
Методология сама по себе от региона не зависит — она про процесс, а не про сервисы. Но два момента стоит проговорить для российского контура.
Русскоязычного опыта именно user-guide-driven development на момент публикации нет. Ни на Хабре, ни на vc.ru, ни в профильных Telegram-каналах не нашлось ни одного разбора этого подхода — пост вышел за неделю до этой статьи, обсуждение велось на английском. Если попробуете — вы, скорее всего, окажетесь первым, кто опишет результат на русском. Ближайшее, что освещено в рунете, — спецификация-first практики и документация как источник истины для ИИ, но без радикального отказа от тестов.
Инструменты, на которых это работает, — те же агенты. Claude Code, Codex и другие из российских IP без VPN недоступны, оплата подписок идёт зарубежными картами и посредниками (Anthropic и OpenAI не ведут официальных продаж в РФ). Разбор geo-ограничений Anthropic — на Habr, практика работы через VPN и посредников с оценкой рисков — в кейсе на spryt.ru. На локальных и доступных в РФ моделях подход тоже работает — он не требует фирменных фич конкретного агента, только умения читать файлы проекта и итерировать по тексту. Обзор таких инструментов — в статье про ИИ в терминале.
Честные ограничения
- Это кейс одного человека, а не проверенный метод. Пост набрал скромное число очков, в обсуждении был один развёрнутый комментарий. Автор сам не уверен в масштабируемости. Относиться к этому стоит как к гипотезе с интересным механизмом проверки, а не как к рекомендации.
- Гайд не заменяет спецификацию. Аргумент gojkoa подтверждается практикой: внутренняя сложность, безопасность и бизнес-правила в гайд не попадают. На системе без пользовательского интерфейса метод неприменим в принципе.
- Проверка «агент по гайду» недетерминирована. Разные модели и версии могут по-разному пройти один и тот же гайд; результат прогона — не строгий да/нет, а отчёт с расхождениями, который надо читать человеку.
- Стоимость проверки выше, чем у юнитов. Каждый прогон — сессия с моделью (токены и минуты), тогда как юнит-тесты бесплатны и мгновенны.
- Полный отказ от юнит-тестов — крайняя позиция. Даже если гайд-прогон станет основным критерием, регрессионная сетка для модулей с накопленной логикой остаётся полезной.
Вывод
Идея hosamsh попадает в реальную боль агентной разработки: когда код пишет агент, код перестаёт быть тем, что человек знает «изнутри», и нужен внешний, проверяемый критерий. Гайд с мокапами — такой критерий: он читается человеком, исполняется агентом и не даёт агенту самому решать, что его работа корректна. Это ровно тот принцип, который Скотт Спенс формулирует как границу между vibe coding и agentic engineering: модель не должна сама решать, что её работа правильная.
Но гайд проверяет пользовательский путь, а не систему целиком. Бэкенд, безопасность, производительность и регрессии остаются за кадром, и их надо закрывать другими средствами — спецификацией и тестами. Разумная версия метода — не «гайд вместо юнит-тестов», а «гайд и мокапы как основной контракт с агентом, юниты как точечная страховка самых хрупких модулей, сквозной прогон по гайду как приёмка». Начать можно с одного небольшого инструмента и одного вопроса к агенту в свежей сессии: «пройди по гайду буквально и перечисли, где поведение не совпадает». База агентного кодинга, если нужно освежить понятия, — в статье «Что такое агентный кодинг».
Соседняя статья недели — статье «ИИ-агент для тестирования: навыки, которые режут бесполезные тесты».
