В статье на Habr я рассказывал про форматированные документы - правила, рассуждал о возможности их применения как инструкции, спецификации и шаринг между команды в разработки программного приложения.
Есть интересный пример и его разбор который не вошел в статью.
В модуле нашего приложения `create` есть форматированный документ, который является описанием обработки ошибок:
CREATE_ERROR_HANDLING.md
# TRIGGER: ERROR_HANDLING_CREATE
## Контекст
В модуле `create` реализована специализированная обработка ошибок для валидации создания постов.
Обработка ошибок организована по модульному принципу и работает независимо от глобального обработчика.
## Структура
### Исключения
- **`PostValidationException`** - базовое исключение для ошибок валидации постов
- **`EmptyTextException`** - исключение для пустого или отсутствующего текста поста
- **`InvalidCategoryException`** - исключение для недопустимых категорий
### Обработчик исключений
**`CreateExceptionHandler`** - специализированный обработчик для модуля create:
- Обрабатывает только исключения в пакете `bla2code.squirrel.lenta.create`
- Возвращает структурированные ответы с кодами ошибок
- Логирует все ошибки валидации
## Коды ошибок
| Код | Исключение | HTTP статус | Описание |
|-----|------------|-------------|----------|
| `VALIDATION_ERROR` | `EmptyTextException` | 400 | Пустое или отсутствующее поле text |
| `INVALID_CATEGORY` | `InvalidCategoryException` | 400 | Недопустимая категория поста |
| `VALIDATION_ERROR` | `PostValidationException` | 400 | Общая ошибка валидации |
## Формат ответа с ошибкой
```json
{
"code": "VALIDATION_ERROR",
"message": "Поле 'text' является обязательным и не может быть пустым",
"field": "text"
}
```
## Поля ответа
- **`code`** - код ошибки (строка)
- **`message`** - подробное сообщение об ошибке (строка)
- **`field`** - поле, с которым связана ошибка (строка или null)
## Примеры ошибок
### Пустой текст
**Запрос:**
```json
{
"title": "Заголовок",
"text": "",
"link": "https://example.com"
}
```
**Ответ:** HTTP 400
```json
{
"code": "VALIDATION_ERROR",
"message": "Поле 'text' является обязательным и не может быть пустым",
"field": "text"
}
```
### Недопустимая категория
**Запрос:**
```json
{
"title": "Заголовок",
"text": "Текст поста",
"categories": ["invalid_category"]
}
```
**Ответ:** HTTP 400
```json
{
"code": "INVALID_CATEGORY",
"message": "Недопустимая категория: 'invalid_category'. Разрешенные категории: [movies, games, technologies, ai]",
"field": "categories"
}
```
## Разрешенные категории
- `movies` - фильмы
- `games` - игры
- `technologies` - технологии
- `ai` - искусственный интеллект
## Тестирование
Все ошибки покрыты автоматическими тестами в `PostControllerTest`:
- `createPost_withNullText_returnsBadRequestWithValidationError`
- `createPost_withEmptyText_returnsBadRequestWithValidationError`
- `createPost_withBlankText_returnsBadRequestWithValidationError`
- `createPost_withInvalidCategory_returnsBadRequestWithCategoryError`
- `createPost_withMultipleInvalidCategories_returnsBadRequestWithCategoryError`
## Архитектурные принципы
1. **Модульность** - обработка ошибок изолирована в модуле create
2. **Специализация** - каждый тип ошибки имеет свое исключение
3. **Структурированность** - единый формат ответов с ошибками
4. **Логирование** - все ошибки логируются для отладки
5. **Совместимость** - не влияет на глобальный обработчик ошибок
Как ИИ-агент воспринимаю этот документ.
Когда Агент анализирую структуру <TRIGGER>:
1. Идентификатор триггера
# TRIGGER: ERROR_HANDLING_CREATE
Однозначно указывает, что это модуль или контекст правил.
Это хорошо - позволяет агрегировать все правила в систему подсказок.
2. Контекст
Блок ## Контекст явно задаёт область применения (модуль create, локальный обработчик ошибок).
Агент может использовать это как scoping - применять правила только к операциям создания постов.
3. Структура исключений
Список из трёх исключений позволяет агенту построить иерархию классов ошибок.
ИИ может интерпретировать:
- PostValidationException - базовый класс
- EmptyTextException, InvalidCategoryException - конкретные подклассы
Это полезно, потому что можно наследовать реакцию (общий шаблон от PostValidationException, уточнения от потомков).
4. Таблица кодов ошибок
Таблица отлично структурирует взаимосвязи:
- exception → error_code → http_status → description
ИИ-агент может сразу построить словарь:
{
"EmptyTextException": {"code":"VALIDATION_ERROR", "http":400, "desc":"Пустое поле text"},
"InvalidCategoryException": {"code":"INVALID_CATEGORY", "http":400, "desc":"Недопустимая категория"},
"PostValidationException": {"code":"VALIDATION_ERROR", "http":400, "desc":"Общая ошибка"}
}
5. Пример формата ответа
JSON-пример очень помогает - агент может использовать его как response template. Он задаёт структуру, типы полей и пример значения.
6. Примеры ошибок
Отличный способ обучить агента на контексте.
ИИ может сопоставить:
- входной JSON (условие)
- выходной JSON (реакция)
- статус (400)
Это даёт возможность не только документировать, но и смоделировать поведение.
7. Раздел "Разрешенные категории"
Чёткий список констант - можно использовать как встроенный reference для валидации.
8. Раздел "Тестирование"
Даёт агенту понятие о покрытии сценариев — при генерации новых тестов или валидации корректности.
9. Архитектурные принципы
Этот блок можно воспринимать как общие директивы поведения:
например, “не пересекаться с глобальным обработчиком” = агент должен изолировать эти правила от других.
--
Этот разбор документа мне сделал ИИ как он его воспринимает и дал некоторые мини-рекомендации:
Можно добавить в начало блока такую шапку:
---
Тогда ИИ сможет:
id: ERROR_HANDLING_CREATE
type: trigger
module: create
scope: validation
format: json
version: 1.0
---
Тогда ИИ сможет:
- быстро понять тип документа
- индексировать по id (тут речь про инструмент генерации кода)
- фильтровать по module или type
На сколько это правда понять сложно, но то что такой документ помогает в дальнейшей разработке это я проверил. Формат с версией может быть интересен - так как документ динамичен и меняется при добавлении новых фич, и возможно поможет ИИ-агенту понимать был ли изменен данный документ. Но как это проверить я не знаю.