Напишіть опис задачі для агента

Опишіть зміну, яку рецензент може оцінити

«Додати експорт даних клієнтів» залишає кілька рішень відкритими. Хто може експортувати записи? Які записи й поля включено? Що відбувається, коли запит завершується невдало? Агент може заповнити ці прогалини правдоподібними рішеннями. Вони все одно можуть бути неправильними для бізнесу.

Почніть із користувача та проблеми. Потім опишіть потрібну поведінку. Додайте докази, які покажуть, чи прийнятний результат.

Опис має зменшувати невизначеність, не визначаючи кожного внутрішнього проєктного рішення. Вкажіть потрібну межу даних. Нехай реалізація використовує наявні підходи репозиторію, якщо немає причини їх змінювати.

Використайте конкретний приклад

Наведений нижче опис стосується вигаданого застосунку підтримки. Це навчальний приклад, а не повна специфікація для продуктивного середовища.

Результат: Менеджер підтримки може завантажити список клієнтів.
Виконавець: Менеджер поточної організації.
Дані: Лише активні клієнти цієї організації.
Поля: Ідентифікатор клієнта, назва компанії та статус облікового запису.
Формат: UTF-8 CSV із рядком заголовків.
Заборонений запит: Повернути наявну помилку авторизації.
Порожній результат: Повернути коректний CSV лише із заголовками.
Обсяг: Використати наявний маршрут експорту та підхід до аудиту.
Виключено: Без нових ролей, залежностей або розгортання.
Докази: Тести дозволених і заборонених запитів, запитів із порожнім результатом і запитів до іншої організації.

Цей опис визначає корисну поведінку та обмеження. Він також виявляє подальші питання. Чи має система обмежувати розмір експорту? Чи може поле містити формулу електронної таблиці? Хто має доступ до аудиторського запису? Розв’яжіть питання з важливими наслідками перед реалізацією. Не сприймайте приклад як універсальний контрольний список.

Відокремлюйте вимоги від припущень

Вимога визначає поведінку, яку зміна має забезпечити. Припущення — це факт, якого ви ще не перевірили. Тримайте їх окремо.

Наприклад, «використати наявний підхід до аудиту» передбачає, що відповідний підхід існує. Попросіть агента знайти його. Якщо в репозиторії його немає, агент має повідомити про відсутню передумову, перш ніж вигадувати нову систему аудиту.

Обмеження також може суперечити результату. Наявний маршрут може за задумом повертати дані всіх організацій. Агент має показати суперечність і запропонувати обмежене виправлення. Він не повинен мовчки прибирати межу даних або розширювати задачу до переписування архітектури.

Включіть докази до умов завершення

Попросіть підсумок виконаної роботи з поясненням остаточної поведінки, зміненого обсягу та виконаних перевірок. Вимагайте точні команди й результати там, де це важливо. Відрізняйте перевірку, яка пройшла успішно, від перевірки, яку не вдалося запустити.

Pull request має зберігати причину зміни. Майбутній супроводжувач може побачити код без початкової розмови. Додайте достатньо контексту, щоб пояснити, чому експорт не включає певних полів і як забезпечується контроль доступу.

Рекомендації Google щодо опису змін — корисне джерело для цього запису. Опис має пояснювати зміну та її мету. Після правок за результатами перегляду узгодьте запис з остаточною реалізацією.

Зберігайте пропорційність опису

Для невеликого виправлення тексту достатньо короткого опису. Експорт даних потребує більше деталей, бо його збої можуть розкрити інформацію. Новий платіжний процес потребує ще більше аналізу й перегляду.

Не вимірюйте якість опису його довжиною. Запитайте, чи зможе компетентний рецензент відрізнити правильний результат від неправильного. Якщо дві розумні реалізації можуть по-різному виконувати дію з важливими наслідками, спочатку уточніть цю поведінку.