Plain Text vs XML or Markdown: на чём писать промпты для ИИ-кодера?

Структура — это новый язык общения с ИИ. Особенно когда дело касается кода.
Есть миф: чтобы попросить ИИ написать код, достаточно набросать запрос в чат «как есть». Plain text, без правил. Сработает? Иногда. Будет эффективно? Редко.
Почему ИИ «понимает» структурированный промпт (с тегами, отступами, чёткими блоками) лучше, чем простой текст?

• Ясность ролей. Когда вы явно прописываете <role>Ты senior Java-разработчик</role>, ИИ не гадает, в каком стиле писать - он сразу включает нужный режим.

• Разделение задач. Отдельный блок с требованиями, примером и самим заданием помогает модели не путать условие с контекстом. Это как дать не кучу деталей, а чертёж со схемой сборки.

• Контроль формата. Хотите получить ответ в виде JSON, код с комментариями или готовый модуль? Скажите это явно в теге <output_format>. ИИ не будет добавлять от себя лишних пояснений, если вы просите только код.

Как это работает на практике?
Вместо:

Напиши на Java метод, который проверяет, является ли строка палиндромом.
Игнорируй регистр и пробелы. С использованием StringBuilder."

Структурируем:

<role>
  Ты senior Java-разработчик, который строго следует code convention
  и пишет надежный production-ready код
</role>
<task>
  Напиши публичный статический метод для проверки,
  является ли строка палиндромом
</task>
<requirements>
  - Название метода: 'isPalindrome'
  - Параметры: 'String input'
  - Возвращаемый тип: 'boolean'
  - Игнорировать регистр символов (привести к нижнему регистру)
  - Удалить все не-буквенные символы (пробелы, знаки препинания)
  - Использовать 'StringBuilder' для разворота строки
  - Добавить JavaDoc комментарий
  - Продемонстрировать работу метода в методе 'main'
</requirements>
<output_format>
  Предоставь готовый к компиляции Java-код класса 'PalindromeChecker'
  без лишних объяснений
</output_format>

Второй вариант даст более точный и готовый к использованию результат. Меньше правок - быстрее результат.
Но! Не всегда нужно усложнять.
Для простых задач вроде "напиши регулярное выражение для email" или "объясни этот код" достаточно plain text. Не стоит делать XML-каркас для одноразового запроса.
Если хотите писать код с ИИ быстрее и точнее - учитесь структурировать промпты. Но используйте сложные форматы там, где они действительно нужны.

Усложним пример.

<prompt>
  <context>
    Цель: Внести изменения в API/бизнес-логику модуля модерации    
    Модуль: Модуль модерации moderation
    Важно: не пишите тесты
  </context>
  <task>
     ## Измените API POST /api/moderation/approve/{id} "Одобрить Post для публикации":
     - При публикации добавьте параметр даты и времени
     - Параметр даты и времени необязателен
     - Если параметр даты и времени не указан, сохраните текущее время и дату в поле scheduledAt.
     - Просмотрите модуль moderation
     - Не пишите тесты
  </task>
  <files>
    @ModerationController @ModerationService @PostRepository @PostEntity
  </files>
  <rule>
    @RULES.md
  </rule>
</prompt>

Получился относительно компактный и информативный промпт.

Блок context описываем общую информацию, в данном случае краткую постановку задачи, модуль в котором необходимо сделать изменения (об этом позже) и дополняем, что бы Агент не пытался сразу покрывать тестами решенную задачу.

Есть информация, что можно указать, к примеру, - "Ты senior Java разработчик, который строго следует code convention и пишет надежный production-ready код" или написать конкретное имя автора книги с ее названием и попросить действовать как он, ИИ быстро поймет в каком ключе действовать. Но я так не делаю, по причине, что code-review строго оставляю за человеком.

task в этом блоке описываем шаги реализации задачи. Да, вы правильно поняли, мы не вайбим описывая абстракцию - "Хочу то, не знаю что, похожее на это".
В начале можно указать общую информацию и разбить на пункты. Может быть несколько крупных шагов с этапами реализации. Если задача объемная - разбивайте, на сколько это возможно, на независимые кусочки - декомпозируйте.

В блоке files укажем все файлы которые нужно смотреть агенту. Тут, в зависимости от того какой инструмент вы используете можно указать путь или, если вы просто кидаете промпт в чат, то в отдельных блоках написать конкретный код класса, но помните об ограничении контекста.

Формулируйте инструкции так, будто объясняете задачу другому человеку - лаконично, последовательно и без потери ключевых деталей.

rule - самое интересное. В процессе анализа и проектирования возникают артефакты в виде документа, описывающего ваше приложение, его характеристики и параметры. Для агента важно получить в контекст некоторые правила которые дадут представление как устроено приложение.

Тут важно заметить, что @RULES.md указан в конце, это не совсем правильно, так как важна последовательность и лучше указать в начале ссылку на этот блок, к примеру:

<context>
    Смотри rule
</context>

Или непосредственно в контексте указать файл @RULES.md

Посмотрим как может выглядеть файл @RULES.md на примере:

# Архитектурные правила проекта `Lenta AI`

## Общие принципы
- Код разделён на **модули по доменной логике**: `fetcher`, `processor`, `publisher`, `moderation`, `shared`, `create`.
- Модули **изолированы**: каждая бизнес-логика живёт внутри своего модуля.
- Общение между модулями идёт через **события** (`events/`) или через `shared` (репозиторий, сущности).
- Общий код (сущности, конфиги, утилиты) хранится в `shared`.

---

## Структура каталогов

lenta
 ├── fetcher/             # Модуль 1: работа с RSS
 │    ├── scheduler/      # Планировщики (RssFetcherScheduler)
 │    ├── service/        # Сервисы с логикой (RssFetcherService, NewsFilterService)
 │    ├── listener/       # Слушатели событий (NewsFilterListener)
 │    ├── client/         # Внешние клиенты (RssClient)
 │    └── events/         # Данные событий, dto (NewsItemEvent, FilteredNewsEvent)
 │
 ├── processor/           # Модуль 2: AI обработка
 │    ├── scheduler/      # Планировщик AiProcessorScheduler
 │    ├── service/        # Логика AiProcessorService
 │    ├── listener/       # Слушатель событий AiProcessorListener
 │    ├── client/         # AI-клиенты (YandexGptClient, OpenAiClient)
 │    └── events/         # События dto (PostPendingEvent, ProcessingNewsEvent)
 │
 ├── publisher/           # Модуль 3: публикация
 │    ├── scheduler/      # PostScheduler
 │    ├── service/        # PostService, стратегии публикации
 │    ├── listener/       # PostPersistenceListener, меняет статус с PROCESSING на PENDING, должен быть между processor и publisher, но пока что пусть будет в publisher
 │    ├── client/         # TelegramPublisher, DiscordPublisher
 │    ├── registry/       # PublisherStrategyRegistry
 │    └── events/         # События (PostReadyEvent)
 │
 ├── create/              # Модуль 4: API Создания и получения постов
 │    ├── api/            # Контроллер и перехватчик исключений (CreatedController, CreateExceptionHandler)
 │    ├── exception/      # Исключения с которыми работает модуль
 │    └── service/        # Сервис с логикой работы модуля (CreatedService), может использовать компоненты модуля shared
 │ 
 ├── moderation/          # Ручная модерация постов
 │    ├── service/        # ModerationService логика модуля и перехватчик исключений ModerationExceptionHandler
 │    ├── exception/      # Исключения с которыми работает модуль
 │    └── api/            # ModerationController внешнее api
 │
 ├── shared/              # Общие компоненты
 │    ├── entity/         # Сущность PostEntity
 │    ├── repository/     # Интерфейс JPA репозиторий PostRepository
 │    ├── enums/          # Status, Target
 │    ├── dto/            # dto
 │    │    ├── request/   # dto входные
 │    │    └── response/  # dto выходные
 │    ├── config/         # OpenAiProperties, RssProperties, ExecutorConfig, NewsFilterProperties, yandexGptWebClient, YandexGptProperties
 │    └── api/            # GlobalExceptionHandler


---

## Правила именования
- `*Service.java` → в `service/`
- `*Scheduler.java` → в `scheduler/`
- `*Listener.java` → в `listener/`
- `*Client.java` → в `client/`
- `*Event.java` → в `events/`
- `*Controller.java` → в `api/`
- `*Entity.java` → в `shared/entity/`
- `*Repository.java` → в `shared/repository/`
- `*Properties.java` → в `shared/config/`
- `*ExceptionHandler.java` → в `shared/api/`

---

## Правила для тестов
- Тесты повторяют структуру `main/`.
- Пример: `src/main/java/.../fetcher/service/RssFetcherService.java`  
  → `src/test/java/.../fetcher/service/RssFetcherServiceTest.java`
- Для тестирования данных используется тест контейнер

Как видим в @RULES.md описана общая архитектура приложения. Получив эту информацию ИИ будет хорошо представлять в какой области придется работать и, надеюсь, не будет сканировать не нужные модули.

Одни агенты используют векторный поиск (RAG) для контекстного обогащения промпта, другие опираются на простую индексацию проекта и извлечение данных по ключевым признакам.

Кстати, такую структуру каталогов он понимает хорошо.

Немного про архитектуру

Почему выбран модульный подход? Это напрямую связано с контекстом.

У нас есть контекст агента и, так как мы оставили за собой задачу по code‑review — примем нашу память как контекст — внимание. У агента есть ограничение по токенам, а у человека — по вниманию. Поэтому наша «память» — это память разработчика, которому нужно удерживать в голове всю логику изменений.

Модульная архитектура делает это проще: она позволяет понимать, где именно произошли изменения, быть уверенным, что они не затронули другие части системы, и держать в фокусе только один небольшой кусочек.

Теория устройства человеческой памяти и его ограничений нам не важны, термины взяты для общего понимания.

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

Была идея делать отдельный модуль как одна фича, но в теории может быть все очень плохо. Приложение будет разбито на много мелких кусочков, а с ростом проекта они начнут пересекаться - страшно представить на что это будет похоже.

Не всегда следует писать маленькие функции

Почему это удобно для vibe coding

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

Лёгкий рефакторинг - переделываешь логику в одном модуле - остальные остаются живыми.

Локальные правила - внутри модуля можно менять структуру (например, перейти от JPA к JdbcTemplate), не ломая глобально проект.

Меньше когнитивной нагрузки - вместо "огромного монолита" у тебя мозг думает только про кусок системы. Это хорошо ложится на vibe coding, где важен фокус на текущем потоке работы.

Локальные правила...

Отвлечемся от основного повествования. Вернемся к нему чуть позже.

PromptOps: стандартизация промптов в команде

Что если выстроить процесс передачи задач AI‑агенту так, чтобы от бизнес‑задачи до готовых инструкций всё было максимально формализовано?

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

Допустим, у нас уже есть такой стандарт.
Основная идея: XSD как триггер:

• XML - единый формат промпта.

• XSD - фиксирует правила и шаблон (автовалидация).

• Проверка - ручная, перед отправкой в AI-агента. И вот тут появляется интересный момент: XSD можно воспринимать не только как инструмент валидации, но и как триггер. Почему XSD = триггер:

  1. Стандартизация входа.
     Модель никогда не получает "любой XML". Всё валидируется по XSD - значит, структура предсказуема.

  2. Триггеры внутри схемы.
     Например, в XSD есть <Status> с ограничением CREATED | PROCESSING | .... Это не просто валидация, а чёткий сигнал: модель работает только с этими статусами.

  3. Расширяемость.
     Добавили новый элемент <Module> или <Agent> - теперь он обязателен во всех промптах. Это превращается в контракт: модель всегда получает нужный контекст.

Чем это похоже на триггерный промптинг:

• XSD = заготовка (trigger template).

• XML = конкретный вызов (trigger input).

• Валидация по схеме = защита от "шума" и "лишних слов".

По сути, мы превращаем формат в инструмент управления моделью.

Как это использовать в команде:

• Для каждого типа промптов пишем свою XSD (например, Task, BugReport, RefactorRequest).

• Все участники формируют промпты только через XML, валидный по схеме.

• LLM всегда получает стандартизированные входы - одинаковое поведение. Дополнительно можно генерировать XML-промпты автоматически, например, прямо из Jira. Фактически, XSD становится DSL (domain-specific language) для работы с AI. Триггерный промптинг = гарантированное выполнение схемы.

Возможно будет не понятно про триггеры в данном контексте, и хорошо бы предоставить пример, но так как я это не реализовал - оставим это для обсуждения.

...Локальные правила

Когда мы даём задачу ИИ-агенту, он может оставить после себя не только код, но и артефакт - например, технический документ, который хорошо подходят для модульности. Храним их непосредственно в модулях - локальные правила.

 ├── moderation/          # ...
 │    ├── service/        # ...
 │    ├── exception/      # ...
 │    ├── rules/          # Локальные правила модуля
 │    └── api/            # ... 

Пример:

# TRIGGER: ERROR_HANDLING_MODERATION

## Контекст

В модуле `moderation` реализована специализированная обработка ошибок для операций модерации постов.
Обработка ошибок организована по модульному принципу и работает независимо от глобального обработчика.

## Структура

### Исключения

- **`ModerationException`** - базовое исключение для ошибок модерации
- **`PostNotFoundException`** - исключение для случаев, когда пост не найден
- **`InvalidStatusTransitionException`** - исключение для недопустимых переходов статусов
- **`InvalidPostIdException`** - исключение для некорректных ID постов

### Обработчик исключений

**`ModerationExceptionHandler`** - специализированный обработчик для модуля moderation:
- Обрабатывает только исключения в пакете `bla2code.squirrel.lenta.moderation`
- Возвращает структурированные ответы с кодами ошибок
- Логирует все ошибки модерации

## Коды ошибок

| Код | Исключение | HTTP статус | Описание |
|-----|------------|-------------|----------|
| `POST_NOT_FOUND` | `PostNotFoundException` | 404 | Пост не найден |
| `INVALID_STATUS_TRANSITION` | `InvalidStatusTransitionException` | 400 | Недопустимый переход статуса |
| `INVALID_POST_ID` | `InvalidPostIdException` | 400 | Некорректный ID поста |
| `INVALID_OPERATION` | `IllegalStateException` | 400 | Недопустимая операция |
| `RESOURCE_NOT_FOUND` | `NoSuchElementException` | 404 | Ресурс не найден |
| `MODERATION_ERROR` | `ModerationException` | 400 | Общая ошибка модерации |

## Формат ответа с ошибкой

```json
{
  "code": "POST_NOT_FOUND",
  "message": "Пост с ID 999 не найден",
  "field": "id",
  "value": 999
}
```

## Поля ответа

- **`code`** - код ошибки (строка)
- **`message`** - подробное сообщение об ошибке (строка)
- **`field`** - поле, с которым связана ошибка (строка или null)
- **`value`** - значение поля, вызвавшее ошибку (объект или null)

## Примеры ошибок

### Пост не найден

**Запрос:** `POST /api/moderation/processing/999`

**Ответ:** HTTP 404
```json
{
  "code": "POST_NOT_FOUND",
  "message": "Пост с ID 999 не найден",
  "field": "id",
  "value": 999
}
```

### Недопустимый переход статуса

**Запрос:** `POST /api/moderation/approve/123` (пост в статусе CREATED)

**Ответ:** HTTP 400
```json
{
  "code": "INVALID_STATUS_TRANSITION",
  "message": "Операция 'одобрение' недоступна для поста ID=123 в статусе 'CREATED'",
  "field": "status",
  "value": 123
}
```

### Редактирование опубликованного поста

**Запрос:** `PUT /api/moderation/edit/456` (пост в статусе PUBLISHED)

**Ответ:** HTTP 400
```json
{
  "code": "INVALID_STATUS_TRANSITION",
  "message": "Операция 'редактирование' недоступна для поста ID=456 в статусе 'PUBLISHED'",
  "field": "status", 
  "value": 456
}
```

### Некорректный ID

**Запрос:** `POST /api/moderation/processing/-1`

**Ответ:** HTTP 404
```json
{
  "code": "POST_NOT_FOUND",
  "message": "Некорректный ID поста: -1",
  "field": "id",
  "value": -1
}
```

## Бизнес-правила модерации

### Операция одобрения (approve)
- Доступна только для постов в статусе `PENDING`
- Переводит пост в статус `APPROVED`
- Устанавливает время публикации

### Операция редактирования (edit)
- Доступна только для постов в статусах `CREATED` или `PENDING`
- Запрещена для постов в статусах `PROCESSING`, `APPROVED`, `PUBLISHED`, `REJECTED`

### Операции изменения статуса (processing, reject)
- Доступны для постов с любым статусом
- Проверяют существование поста

## Валидация ID постов

- ID должен быть положительным числом (> 0)
- null ID обрабатывается как ошибка
- Отрицательные ID возвращают ошибку

## Тестирование

Все ошибки покрыты автоматическими тестами в `ModerationControllerTest`:
- `processing_whenInvalidPostId_shouldReturnNotFound`
- `approve_whenInvalidPostId_shouldReturnNotFound`
- `reject_whenInvalidPostId_shouldReturnNotFound`
- `editPost_whenInvalidPostId_shouldReturnNotFound`
- `approve_whenPostNotInPendingStatus_shouldReturnBadRequest`
- `editPost_whenPostInPublishedStatus_shouldReturnBadRequest`
- `processing_whenNegativeId_shouldReturnNotFound`

## Архитектурные принципы

1. **Модульность** - обработка ошибок изолирована в модуле moderation
2. **Бизнес-логика** - проверка правил переходов статусов
3. **Информативность** - подробные сообщения с контекстом ошибки
4. **Типизация** - специализированные исключения для разных случаев
5. **Совместимость** - не влияет на глобальный обработчик ошибок

## Интеграция с остальной системой

- Обработчик работает только для пакета moderation
- Не конфликтует с обработчиками других модулей
- Дополняет глобальную обработку ошибок
- Обеспечивает консистентное API для фронтенда

Возникает вопрос: а можно ли использовать локальные правила в последующей разработке/тестировании. «Скармливать» Агенту как контекст. Контролировать создание таких артефактов и встраивать в общий процесс разработки.
Возможности здесь интересные:

• Документ может стать основой для других задач. Например, тестировщик получит готовый сценарий тестов, а аналитик — описание бизнес‑правил. (Тут интереснее про тестировщик и аналитик как агенты).

К примеру, можем подкинуть правило ИИ @MODERATION_ERROR_HANDLING.md и написать - посмотри ERROR_HANDLING_MODERATION - Операция одобрения (approve) и покрой тестами этот функционал ...

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

• Такой артефакт можно встроить в пайплайн: использовать для автоматической генерации тестов, документации API или как контрольную точку при ревью.

• Если контролировать процесс генерации артефактов (например, задавать структуру документа и формат), то они будут стандартизированы и реально полезны для всей команды.

Проблема в том, что без рамок артефакты могут быть слишком «размытыми»: ИИ может написать много текста, но без практической пользы. Поэтому ключевой вопрос — как встроить их в процесс так, чтобы они стали настоящим инструментом, а не побочным продуктом.

Возможно, в будущем артефакты от ИИ станут обязательной частью разработки: код — это одно, а вот спецификации это и есть та ценность которая нам нужна.

В заключение поговорим о тестировании

  <context>
    Цель: Внести изменения в API/бизнес-логику модуля модерации    
    Модуль: Модуль модерации moderation
    **Важно: не пишите тесты**
  </context>

Как тестировать код, написанный ИИ?

Может показаться удобным: ИИ написал фичу — и тут же сам начал покрывать тестами. Но на деле это ловушка. Ещё хуже, если разработчик просто даёт промпт без спецификации и предлагает «по логике» построить тесты. Это как подгонять тесты под код, а не проверять его работу.

Проблема: тесты превращаются в формальность. Они не проверяют корректность реализации, а лишь повторяют то, что уже написал ИИ. В результате мы получаем красивый, но бесполезный набор тестов.

Решение: тестирование должно опираться на спецификацию — чёткое описание того, как должна работать фича. ИИ не должен видеть сам код при генерации тестов: иначе он будет использовать его как инструкцию к действию. Если же дать ему только требования и сценарии использования, тесты будут действительно проверять логику работы, а не подгонять результат.

Так тесты сохраняют свою основную задачу — выявлять ошибки и гарантировать, что продукт работает так, как задумано. (Но это не точно =))

В заключение

Vibecode — это не про абстракции, которые превращаются в готовые фичи, а про точность инструкций. В основе подхода лежит точное описание — спецификации, из которых рождается конкретный результат — будь то фича, сервис или архитектурное решение.

Практика показала, что качество итогового продукта напрямую зависит от того, насколько ясно сформулированы требования и контекст. Чем лучше разработчик умеет описывать процесс, тем эффективнее работает ИИ — и тем ближе результат к ожидаемому.

Сегодня перед нами стоит новая задача: научиться писать код с помощью ИИ так, чтобы он был не хуже, чем если бы мы писали его сами. А в дальнейшем — научимся делать это быстрее, не теряя качества.

При этом ценность хорошего специалиста только растёт. Глубокое понимание основ, архитектуры и принципов проектирования никуда не исчезает — напротив, становится фундаментом для эффективной работы с ИИ‑инструментами.

Новичкам же придётся быстрее расти: разбираться в том, что раньше было доступно только специалистам высокого уровня, чтобы взаимодействие с ИИ действительно приносило результат.

Vibecode — это шаг к более зрелой инженерной культуре, где результат определяется не количеством кода, а качеством мысли, заложенной в спецификацию.

—
Как бы мы ни сопротивлялись, код с ИИ — это уже не будущее, а повседневность. Назови это VibeCode или как угодно — всё равно полетит.