PRD мало: я собрал spec bundle, который можно отдавать агенту

GitHub: agent-spec-bundle

У AI-разработки есть один скучный, но очень дорогой провал.

Человек пишет хороший PRD. Правда хороший. Там есть идея, цель, даже scope. Всё выглядит солидно.

А потом агент начинает кодить и почти сразу натыкается на старый вопрос:

“Хорошо. А что именно хранится в базе?”

Или:

“Как выглядит payload?”

Или:

“Что считается done, а что пока отложили?”

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

Поэтому я собрал agent-spec-bundle. Это маленький public kit, который помогает превратить обычный PRD в пакет, который уже можно отдавать агенту без ритуальных танцев и гадания по атмосфере.

Где обычно ломается работа

Проблема не в том, что PRD плохие. Проблема в том, что они часто живут слишком высоко над землёй.

В них есть:

• что мы хотим сделать;
• зачем это нужно;
• какие у продукта рамки.

Но часто там не хватает вещей, которые на деле решают, быстро поедет работа или утонет в уточнениях:

• контракты;
• схема данных;
• acceptance criteria;
• тестовый контур;
• нормальное разбиение на эпики и задачи.

Из-за этого агент формально “получил документ”, но по факту всё ещё вынужден догадываться.

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

Что я начал делать вместо этого

Я перестал относиться к PRD как к финальной истине.

Теперь для больших продуктовых задач я смотрю на него как на сырьё. Полезное, но не финальное.

Если задача действительно серьёзная, следующий шаг — не просто brief, а небольшой spec bundle.

В моём варианте он по умолчанию состоит из пяти файлов:

• prd.md
• contracts.md
• schema.sql
• test-plan.md
• epics.md

Это не культ пяти священных файлов. Если половина из них не нужна, отлично, выкинь половину.

Смысл не в количестве документов. Смысл в том, чтобы дать агенту и ревьюеру ровно те артефакты, которые снимают двусмысленность.

Что даёт каждый файл

prd.md отвечает за цель, scope, non-goals и границы.

contracts.md нужен там, где есть API, IPC, события, очереди, фоны и прочие вещи, которые любят ломаться молча.

schema.sql нужен не потому, что SQL красивый, а потому что память у нас у всех ограничена. Если у проекта есть реальные сущности и связи, лучше записать их явно, чем потом спорить в комментариях, должен ли здесь быть enum, отдельная таблица или просто молитва.

test-plan.md нужен, чтобы “готово” было проверяемым словом, а не настроением команды.

epics.md превращает всё это в нормальный GitHub-ready breakdown, чтобы потом не сидеть над задачей второй раз, уже во время исполнения.

Почему это особенно полезно для агентов

Человек часто может простить документу дырки. Он сам же и писал, он помнит контекст, он может достроить смысл на лету.

Агент тоже может. Но цена такого “может” обычно выше, чем кажется.

Если агент угадает правильно, ты просто подумаешь, что всё хорошо.

Если агент угадает криво, ты потеряешь время не в момент написания PRD, а позже, когда код уже появился, ветка уже есть, и нужно не просто уточнить мысль, а переделывать работу.

Поэтому нормальный spec bundle — это не бюрократия, а способ перенести часть боли в более дешёвую фазу.

Честно решить спорные места до того, как они стали кодом, почти всегда выгоднее, чем чинить их потом.

Что я положил в public kit

В agent-spec-bundle я вынес три простые вещи.

Первое: сам skill spec-bundle, который подсказывает, когда bundle вообще нужен, а когда это уже бумажный перегрев.

Второе: scaffold-скрипт, который за секунду создаёт стартовый набор файлов под новый проект.

Третье: компактные шаблоны, где уже есть форма для scope, contracts, schema, test-plan и GitHub-ready эпиков.

То есть идея здесь не “писать больше документов”.

Идея в том, чтобы перестать каждый раз изобретать форму заново.

Когда это реально стоит делать

Я бы тянул bundle только в тех случаях, когда работа правда может расползтись:

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

Если работа маленькая и обратимая, bundle не нужен. Там хватит brief или короткого checklist.

Никакой романтики. Просто честный объём процесса под честный объём риска.

Что можно повторить у себя

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

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

Мне в этой идее нравится её приземлённость.

Она не обещает магию.

Она просто убирает тот момент, когда агент уже что-то строит, а важные части задачи всё ещё существуют только в голове автора. Для продуктивности это обычно плохой storage backend.