Дизайн-документ как контекст для агента: один файл вместо сотни уточнений
Раньше каждая задача начиналась с десятка уточняющих вопросов от агента. Теперь я пишу один файл с решениями и критериями приёмки — и агент садится работать сразу.
Раньше каждая задача у меня начиналась одинаково. Я писал агенту «свёрстай экраны по макетам» и получал в ответ список вопросов: откуда брать шрифты, какие брейкпоинты нужны, тексты хардкодить или тянуть из CMS, что делать с блоком, который есть на трёх экранах и везде чуть-чуть отличается. Десять уточнений до первой строки кода и ещё двадцать по ходу. Причём половина ответов лежала у меня в голове, остальное — в переписке с заказчиком трёхнедельной давности.
Сейчас я делаю иначе: пишу дизайн-документ и кладу его в репозиторий. Агент читает файл и начинает работать.
Дизайн-документ — это протокол решений
По жанру это протокол принятых решений. Вот шапка моего документа по проекту Million Estate:
# Million Estate — дизайн-документ
Дата: 2026-08-19
Статус: согласование
Заказчик: Дарья (агентство Million Estate)
Дальше идёт раздел «Задача» на четыре строки: перенести сайт с WordPress на собственный код по готовым макетам, 14 экранов, тёмная айдентика, добавить личный кабинет для самостоятельного ведения контента, поднять корпоративную почту на домене. И отдельным абзацем — что готово на входе: бренд-бук, дизайн-код, 14 экранов Desktop 1440, компоненты Header / Footer / Concierge, тексты сняты с текущего сайта дословно.
Эти несколько строк закрывают процентов тридцать будущих вопросов. Агент уже знает, что макеты существуют, тексты существуют и копирайт придумывать не нужно.
Таблица решений закрывает остальное
Самый рабочий раздел документа — таблица «Решения, принятые на старте». Два столбца: вопрос и решение.
| Вопрос | Решение |
|---|---|
| Хостинг | Один VPS 8–16 ГБ |
| Шрифты | Локально, без запроса к Google Fonts |
| Тексты | Всё из CMS, в коде ничего не захардкожено |
Каждая строка здесь — это уточнение, которое агент задал бы в чате. Разница в том, что решение записано один раз и живёт дальше: его видит следующая сессия, другой агент и я сам через месяц.
Acceptance criteria вместо «сделай хорошо»
Внутри документа каждый этап получает чек-лист приёмки. Этап 1.3 «Вёрстка 12 страниц по макетам» выглядит так:
- пиксельное соответствие макетам на 1440;
- адаптив 1440 / 1024 / 768 / 375;
- шрифты Playfair Display и Helvetica Neue подключены локально;
- Header, Footer, «Консьерж» — переиспользуемые компоненты;
- все тексты тянутся из CMS.
Чек-лист работает в обе стороны. Агент понимает, когда задача закончена. Я понимаю, что проверять при приёмке. Формулировка «свёрстано красиво» такого не даёт.
Отдельно про пустоты
Самое неожиданное открытие: в документе полезно фиксировать то, чего в макетах нет.
Когда я снимал спеки с дизайн-системы SexyGram — HTML-холст на 14 разделов — я разложил их по файлам docs/specs/01..06 и в каждой таблице ставил пометку не задано в прототипе там, где значения в исходнике не было. Отступ есть, цвет фона есть, шрифт есть. А состояние hover у кнопки в разделе админки дизайнер просто не нарисовал.
Без пометки агент придумает hover сам — молча и правдоподобно. С пометкой он либо задаст один конкретный вопрос, либо возьмёт значение по токенам из README. Пустота, названная явно, перестаёт быть источником домыслов.
Как я это веду
Правила простые.
- Один файл на проект, лежит в репозитории рядом с кодом.
- Дата и статус в шапке. Статус «согласование» означает, что решения ещё двигаются.
- Решение поменялось — сначала правлю документ, потом задачу. Обратный порядок приводит к тому, что документ врёт.
- Спеки, снятые с макетов, живут отдельными файлами и подключаются ссылкой. Держать их в одном файле неудобно — он распухает до нечитаемого состояния.
Первый такой документ отнял у меня часа полтора. Окупился он на первом же этапе вёрстки: агент отработал 12 страниц без единого уточняющего вопроса про шрифты, брейкпоинты и источник текстов. Все три ответа уже лежали в файле.
Что это меняет
Уточнения в чате исчезают вместе с чатом. Дизайн-документ остаётся. Через месяц заказчик спросит, почему почта поднята на своём домене, — ответ найдётся в таблице решений, с датой рядом.
Полтора часа на файл я плачу один раз за проект. Сотня уточнений стоит дороже.
Ваш контекст для работы с ИИ
Дело всё меньше в удачном запросе и всё больше в том, что ИИ знает о вас и вашей работе. Собираю и упаковываю ваш профессиональный контекст и передаю систему, в которой вы сами поддерживаете его актуальным.