Качество и документация

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

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

Где агенты преуспевают

Генерация юнит-тестов — Дан функцию, агенты генерируют комплексные тесты: счастливый путь, граничные случаи (null, пусто, границы), условия ошибок. Это, вероятно, единственное с самым высоким ROI для большинства команд.

Обнаружение тест-кейсов — “Какие тест-кейсы мне следует рассмотреть для этой функции? Сфокусируйтесь на граничных случаях и условиях ошибок.” Вы часто обнаружите кейсы, которые не рассматривали.

Генерация моков и фикстур — Тестовые структуры данных, mock-реализации, фабричные функции. Утомительная настройка идеальна для агентов.

Регрессионные тесты — “Создайте тест, который поймал бы этот баг: [описание бага]“

На что обращать внимание

• Тесты, которые проходят по неправильным причинам — Тесты, которые мокают то, что тестируется, или имеют утверждения, которые всегда проходят
• Выдуманные утверждения — Агенты могут утверждать поведение, которое не соответствует реальности
• Копипаст-тесты — Похожие тесты, которые не добавляют значимого покрытия

Всегда проверяйте, что тесты могут проваливаться, когда должны.

Рабочий процесс test-first

1. Напишите или сгенерируйте тесты первыми: “Учитывая это требование [опишите], напишите тесты, которые проверят правильную реализацию.”
2. Просмотрите и доработайте: Убедитесь, что тесты captures то, что вы действительно хотите.
3. Сгенерируйте реализацию: “Вот тесты. Напишите код, который их пройдёт.”
4. Проверьте всё: Запустите тесты, просмотрите реализацию, проверьте на пробелы.

Это даёт лучшие результаты, чем реализация first, потому что тесты определяют контракт.

Паттерны промптов

Юнит-тесты:

Напишите юнит-тесты для этой функции:
[вставьте функцию]

Покройте:
- Обычную работу
- Граничные случаи (пустой ввод, null, границы)
- Условия ошибок

Используйте [тестовый фреймворк]. Следуйте конвенциям в [пример файла].

Регрессионный тест:

Баг исправлен: [описание]
Корневая причина: [объяснение]
Исправление: [краткое описание]

Напишите тест, который поймает этот баг, если он вернётся.

Документация

Типы и подходы

Документация кода: Встроенные комментарии (объясняйте ПОЧЕМУ), docs для функций/методов, классов/модулей. Агенты здесь преуспевают, потому что читают код и делают вывод о том, что нужно документировать.

API-документация: Эндпоинты, SDK, руководства по интеграции. Генерируйте из кода, OpenAPI-спецификаций или примеров.

Архитектурная документация: Обзоры систем, записи решений, диаграммы. Требуется больше человеческого руководства, но агенты помогают с генерацией.

На что обращать внимание

• Выдуманные функции — API, которых не существует, параметры, которые не работают. Проверяйте все утверждения против фактического кода.
• Отсутствующий контекст — Почему были приняты решения, подводные камни, соображения производительности. Добавляйте их вручную — они часто самые ценные.
• Риск устаревания — Легко сгенерировать ≠ легко поддерживать. Стройте процессы обновления, а не только генерации.

Паттерны промптов

README с нуля:

Создайте README для этого проекта.

Проект: [опишите проект]
Технологический стек: [перечислите технологии]
Целевая аудитория: [кто будет это использовать]

Включите: установку, быстрый старт, базовое использование, содействие.

API-документация:

Сгенерируйте API-документацию для этого эндпоинта:

[вставьте код эндпоинта или OpenAPI-спецификацию]

Включите: описание, параметры, примеры запроса/ответа, коды ошибок.
Отформатируйте как Markdown.

ADR:

Помогите написать ADR для выбора [опция].

Контекст: [опишите ситуацию]
Решение: [что мы решили]
Последствия: [что это значит]

Включите рассмотренные альтернативы.

Ресурсы

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

• The 3 Pillars of Autonomy – Michele Catasta, Replit - Автоматическое тестирование как фундамент автономности агентов

Документация

• AGENTS.md - Появляющийся стандарт для документации проектов, читаемой агентами
• The New Code – Sean Grove, OpenAI - Спеки как источник правды, компилируемый в документацию