Почему PRD мало и когда spec bundle реально нужен

GitHub: agent-spec-bundle

Самый скучный провал в AI-разработке выглядит не как сломанный build, а как вежливый вопрос от агента посреди вполне приличного PRD.

Документ хороший. Там есть идея, цель, scope, иногда даже аккуратные non-goals. Всё выглядит взрослым ровно до того момента, когда агент спрашивает: что хранится в базе, как выглядит payload, что считается done и где именно заканчивается ответственность этого релиза.

В этот момент обычно и выясняется неприятная вещь: PRD объяснял продукт, но не объяснял сборку.

Поэтому я собрал agent-spec-bundle. Внутри у него три простые вещи: skill spec-bundle, scaffold-скрипт и шаблоны для prd.md, contracts.md, schema.sql, test-plan.md и epics.md. Не культ священных markdown-файлов. Просто способ убрать двусмысленность до того, как у кого-то уже появилась ветка с кодом и собственная трактовка задачи.

Где PRD начинает подводить

Проблема не в PRD как жанре. Проблема в том, что он слишком часто живёт выше земли. Он хорошо отвечает на вопросы вроде “что строим” и “зачем это нужно”. Гораздо хуже отвечает на другой набор вопросов: что агенту нельзя додумывать самому и какие спорные места должны быть закрыты до кода.

Когда этих артефактов нет, агент всё равно двигается дальше. В этом и подвох. Ошибка обычно проявляется не во время чтения PRD, а позже, когда уже есть код, черновой schema drift, кривой contract или ревью, в котором внезапно выясняется, что слово “готово” у всех означало разное.

То есть основной баг здесь не “документ плохой”. Основной баг в том, что документ оставил слишком много места для дорогой догадки.

Что bundle убирает на практике

contracts.md нужен там, где молчаливые допущения особенно любят ломать работу: API, очереди, IPC, события, фоновые джобы. schema.sql фиксирует сущности в тот момент, когда спор про них ещё дешёвый. test-plan.md делает слово “готово” проверяемым, а не эмоциональным. epics.md превращает всё это в внятный handoff, а не в повторное осмысление проекта уже по дороге в GitHub.

Смысл bundle вообще не в количестве файлов. Если половина не нужна, прекрасно, значит ей и не место в папке. Bundle полезен только тогда, когда конкретный артефакт снимает конкретную неоднозначность.

Это особенно заметно с агентами. Человек часто прощает документу дыры, потому что он сам его писал и может достроить смысл по памяти. Агент тоже может достроить. Просто цена такого “может” обычно прилетает позже и уже в коде.

Неприятный tradeoff

У spec bundle есть и неприятная сторона: для маленькой задачи это дорогой paperwork. Если работа помещается в 40 минут, обратима и не затрагивает второй слой системы, bundle может быть просто красивой папкой, которая съела время и не сняла ни одного реального риска.

Именно поэтому мне нравится не bundle как ритуал, а bundle как инструмент с очень скучным критерием полезности. Он должен убирать ambiguity. Если не убирает, значит это не дисциплина, а бумажный перегрев.

Нормальный момент для bundle начинается там, где работа переживёт одну сессию, пересечёт несколько подсистем, упрётся в schema/queues/background jobs или потом пойдёт в GitHub Issues как реальный execution lane.

Что я бы утащил себе

Если хочется повторить подход у себя, я бы начал с трёх вещей:

• не считай PRD автоматически execution-ready;
• добавляй contracts, schema и test-plan только там, где они реально убирают двусмысленность;
• измеряй bundle не количеством файлов, а количеством дорогих догадок, которые он успел убить до первой ветки.

Всё остальное уже вопрос масштаба. Иногда хватит brief. Иногда нужен полноценный bundle. Но если bundle не снимает ambiguity, это не agent-ready пакет. Это просто ещё одна папка с markdown, которую потом тоже придётся объяснять.