«Добавь избранные кейсы на главную» — нормальная просьба в разговоре, но слабое техническое задание для ИИ. За ней скрываются решения, которых заказчик ещё не принимал: кто выбирает кейсы, сколько карточек выводить, что делать без выбранных записей и где хранить настройку. Модель может заполнить эти пробелы сама. В результате получится рабочая функция, которая ведёт себя совсем не так, как ожидал владелец сайта.
ТЗ для ИИ-разработчика WordPress нужно прежде всего для согласования поведения. Рассмотрим одну небольшую задачу от первой фразы до условий приёмки. Пример условный: он не описывает выполненный проект UWEAM и не требует конкретной модели ИИ.
Было: «Сделай блок лучших работ, чтобы мы сами выбирали проекты».
Стало: «Редактор отмечает опубликованные кейсы для главной. Блок показывает до шести отмеченных кейсов в существующем порядке. Если таких кейсов нет, секция целиком скрывается».
Сначала договоритесь о трёх спорных ситуациях
Первый вопрос — что именно означает «лучшие». Это ручной выбор редактора, количество просмотров или автоматически рассчитанный рейтинг? Для нашего примера выбираем ручной флажок. ИИ не должен подменять редакционное решение сортировкой по популярности.
Второй вопрос — что увидит посетитель, если отмеченных кейсов нет. Пустая рамка, последние публикации и скрытая секция — три разных результата. В примере секция скрывается вместе с заголовком и внешними отступами. Такой нюанс стоит записать словами: одного требования «не выводить карточки» недостаточно.
Третий вопрос — что происходит с черновиками. Флажок можно сохранить при подготовке кейса, но на главной он появится только после публикации. Если опубликованный кейс вернуть в черновики, карточка исчезает. Здесь определяется бизнес-логика, которую потом придётся реализовывать и проверять.
На эти вопросы отвечает владелец продукта или ответственный редактор. Просьба к модели «выбери лучший вариант» лишь переносит решение на того, кто не знает ваших договорённостей с клиентами.
Как выглядит достаточно подробное ТЗ
Задача. Дать редактору возможность выбирать кейсы для существующей секции на главной странице. В учебном примере кейсы хранятся в типе записей project. На реальном сайте сначала нужно выяснить фактический тип записей и место, где собирается секция: шаблон темы, Gutenberg-блок или отдельный плагин.
Поведение в редакторе. У кейса появляется настройка «Показывать на главной». Для новой записи она выключена. Текущий выбор сохраняется при обычном обновлении записи и повторном открытии редактора. Название настройки, её положение и доступность для конкретных ролей согласуются до написания кода.
Поведение на сайте. Секция получает только опубликованные отмеченные кейсы, максимум шесть. Порядок остаётся таким же, как у существующего блока. Если нынешний порядок нигде не определён, разработчик сначала показывает варианты и получает решение, а не вводит свою сортировку. На странице архива кейсов выбор для главной ничего не меняет.
Границы изменения. Сохраняются разметка карточки, изображения, ссылки, стили и мобильная сетка. Новая функция не добавляет аналитику, внешние запросы, дополнительные роли или собственный конструктор страниц. Постоянные настройки и данные не должны зависеть от того, какая тема сейчас активна; место реализации выбирается после изучения проекта.
Обновление результата. После изменения флажка данные должны обновляться с учётом используемого кэша. В ТЗ следует назвать допустимую задержку и согласовать, требуется ли автоматический сброс. Обещание «видно сразу» нельзя оставлять без пояснения, если главную отдаёт страничный кэш.
Доступ. Изменять выбор может пользователь, которому разрешено редактировать соответствующий кейс. Проверка nonce защищает от определённого класса поддельных запросов, но не заменяет проверку полномочий — это отдельно отмечено в документации WordPress о nonce. Конкретный обработчик сохранения должен учитывать способ, которым настройка отправляется на сервер.
Приёмка: четыре коротких истории вместо «всё работает»
Сценарии ниже — часть задания, которую стоит написать ещё до генерации кода. Они позволяют заказчику и разработчику одинаково понять результат.
- Редактор выбирает опубликованный кейс
После сохранения и предусмотренного обновления кэша карточка появляется на главной. В редакторе флажок остаётся включённым после перезагрузки страницы.
- На главную выбрано восемь кейсов
Отображается не больше шести карточек. Порядок совпадает с согласованным правилом, а не зависит от случайной очередности сохранения.
- У выбранного кейса меняют статус
После перевода в черновик карточка исчезает из публичной секции. Непубличный кейс не становится доступен посетителям через новый механизм.
- Выбор полностью очищен
На главной нет заголовка секции, пустого контейнера и лишнего промежутка. Соседние блоки сохраняют своё оформление.
Для реальной задачи добавьте проверку пользователя без необходимых прав и оговорённого режима кэширования. Автоматизировать нужно прежде всего то, что легко сломать при следующей правке: отбор записей, ограничение количества и сохранение значения. Внешний вид на узком экране всё равно полезно посмотреть глазами.
Передайте модели контекст, который можно проверить
Нужны фактические версии WordPress и PHP, название используемого редактора, относящийся к задаче фрагмент проекта и описание существующей секции. Если агент видит репозиторий, попросите сначала найти реализацию и объяснить её устройство. Если видит только вставленный текст, прямо укажите это ограничение: он не должен утверждать, что проверил весь сайт.
В рекомендациях GitHub для работы с coding agent хорошо сформулирован общий принцип: ограниченная задача, понятное описание проблемы и критерии готового решения. Для WordPress мы дополняем его редакторскими сценариями, поведением пустых состояний и условиями кэширования. Это наш практический подход, а не обязательный формат документации GitHub.
Стартовый запрос для нашего примера можно написать так:
Изучи приложенный код секции кейсов и техническое задание. Пока не меняй файлы. Назови существующую точку расширения и недостающие данные. Отдельно перечисли решения, которые нельзя вывести из кода. Затем предложи минимальный план реализации и проверки четырёх сценариев. Не придумывай пути файлов, названия функций и результаты тестов. Если код недоступен, прямо укажи, что вывод предварительный.
После согласования плана можно поручать реализацию. Новый запрос не должен отменять договорённости о количестве карточек или пустой секции: храните утверждённое ТЗ рядом с задачей, а не только в длинной переписке. Изменение требований фиксируйте отдельно.
Если ответ начинается с установки нового плагина или полной переделки главной, попросите объяснить, почему нельзя использовать существующий механизм. Иногда новая зависимость оправданна, но она должна решать выявленное ограничение, а не появляться потому, что модели проще написать знакомый пример.
Хорошее ТЗ не обещает безошибочную генерацию. Оно делает спорные решения видимыми до начала работы. Проверка полученного кода — следующий самостоятельный этап; её порядок разобран в статье о проверке кода, написанного ИИ. Перед передачей задачи полезно задать себе один вопрос: сможет ли другой разработчик по этому описанию отличить выполненную работу от похожей демонстрации?
