DESIGN.md для Codex: как передать визуальные правила ИИ-агенту
ИИ-агент не видит ваш вкус сам по себе. Когда Codex получает задачу "сделай интерфейс аккуратнее", он опирается на код, существующие компоненты и общие представления о хорошем UI. Иногда этого хватает. Но если в проекте нет явных визуальных правил, агент легко делает очередной правильный, но безликий экран: карточки, градиент, крупный заголовок, одинаковые отступы и текст, который выглядит как демонстрация возможностей.
DESIGN.md решает эту проблему как рабочий документ для агента. Это не брендбук на сто страниц, а короткая карта: какие цвета использовать, какая типографика допустима, какие компоненты уже есть, какие приемы запрещены, как выглядят хорошие примеры и что надо проверить перед завершением. Такой файл можно положить рядом с кодом и подключать к задачам Codex.
Интерес к этому подходу усилился после появления Google Stitch: в материалах Google про Stitch и в документации DESIGN.md хорошо видна сама идея. Интерфейсный агент должен получать не только просьбу, но и дизайн-контекст. Для Codex это переводится особенно просто: если агент работает в репозитории, визуальные правила должны быть частью репозитория.
Почему обычного промпта мало
Разовая просьба быстро теряется. Сегодня вы написали "не делай карточки внутри карточек", завтра забыли, послезавтра другой агент сделал ровно это. Визуальная культура проекта не должна держаться только на памяти человека. Если правило повторяется больше двух раз, его пора вынести из чата в файл.
Для Codex такой файл работает как навигация. Агент читает код, видит компоненты и одновременно понимает, какой визуальный коридор считается нормальным. Тогда задача "сделай экран" становится не угадайкой, а применением правил.
Главное:DESIGN.md нужен не для красоты документации. Он нужен, чтобы Codex перестал заново изобретать визуальный язык проекта в каждой задаче и начал применять уже принятые решения.
Что положить в DESIGN.md
Документ должен быть коротким и проверяемым. Если он превращается в эссе о стиле, агенту трудно применить его в коде. Лучше писать блоками: правило, пример, запрет, проверка.
| Блок | Что написать | Как это помогает Codex |
|---|---|---|
| Назначение продукта | кто пользуется интерфейсом и зачем | выбирает плотность, тон и сценарии |
| Палитра | основные цвета и роли цветов | не делает случайную одноцветную тему |
| Типографика | размеры, веса, где крупный текст запрещен | не ставит hero-типографику в панель |
| Компоненты | кнопки, таблицы, формы, панели, модалки | использует существующую систему |
| Запреты | что не делать в этом проекте | отсекает шаблонные AI-приемы |
| Примеры | 2-3 удачных экрана или ссылки | дает агенту зрительную опору |
| Проверка | что посмотреть перед финалом | снижает риск наложений и сломанной адаптивности |
Самый важный блок здесь - запреты. Многие ошибки AI-интерфейсов возникают не от отсутствия идей, а от слишком большого числа общих идей. Агенту надо прямо сказать: не использовать декоративные шарики, не вкладывать карточки в карточки, не делать лендинг вместо инструмента, не масштабировать шрифт от ширины окна, не прятать реальный продукт за атмосферой.
Как связать DESIGN.md и AGENTS.md
AGENTS.md может говорить Codex, как работать в проекте: какие команды запускать, какие файлы не трогать, как проверять результат. DESIGN.md должен быть рядом как визуальный контракт. В AGENTS.md достаточно добавить короткое правило: "перед frontend-правками прочитай DESIGN.md и проверь результат по его списку".
Такой формат меняет роль человека. Он не ловит каждую мелкую визуальную ошибку после факта, а заранее задает правила игры. Codex получает меньше свободы для случайного вкуса и больше свободы для полезной реализации.
Рабочая карточка
Когда использовать: когда Codex делает интерфейсы, лендинги, панели, админки, редакторы, визуальные компоненты или обложки.
Что подать на вход: существующий экран, цель изменения, DESIGN.md, ограничения по компонентам, размеры для проверки.
Что сделать по шагам:
- Создать короткий DESIGN.md в корне проекта или в папке docs.
- Записать палитру, типографику, компоненты и запреты.
- Добавить 2-3 примера хорошего результата.
- В AGENTS.md указать, что frontend-задачи должны учитывать DESIGN.md.
- После правки проверять desktop и mobile, а не только код.
- Обновлять DESIGN.md, когда повторяется новая визуальная ошибка.
Какой результат получить: Codex правит интерфейс в стиле проекта, а не в стиле усредненного AI-макета.
Как проверить качество: текст не налезает, размеры стабильны, компоненты не дублируются, палитра не расползается, экран похож на продолжение продукта.
Когда не использовать: если задача чисто backend и не затрагивает пользовательский интерфейс.
Какой навык из этого собрать: навык передачи визуального контекста агенту. Человек учится превращать вкус в проверяемые правила.
Что делать дальше
Начать можно с одного экрана, который чаще всего ломается. Не надо сразу писать полный дизайн-гайд. Достаточно зафиксировать 10-15 правил, которые уже повторяются в работе. После этого дать Codex маленькую задачу и посмотреть, какие правила он применил, а какие проигнорировал.
В статье про одинаковый AI-дизайн мы разбирали, почему "сделай красиво" часто ведет к однотипным решениям. DESIGN.md делает следующий шаг: он не просто критикует результат, а дает агенту рабочую опору до начала правки.