Урок 4.2. Что такое хорошая Agent Task

Зачем это нужно

В предыдущем уроке мы разложили feature на candidate tasks. Но список задач еще не гарантирует управляемую работу агента. Формулировка "добавить endpoint" может быть слишком расплывчатой: агент не знает, какие документы читать, какие файлы можно менять, какие constraints важны и какой командой проверить результат.

Хорошая Agent Task - это маленький контракт на один agent run. Она должна дать агенту достаточно контекста для действия и достаточно ограничений для контроля.

Главная идея: агенту нужно передавать не просто "что сделать", а bounded task package.

Основная идея

Хорошая Agent Task отвечает на семь вопросов:

Goal:
Что нужно получить?

Context:
Почему это нужно и к какой feature относится?

Inputs:
Какие документы и файлы нужно прочитать?

Allowed scope:
Какие файлы или директории можно менять?

Constraints:
Что нельзя нарушать?

Acceptance criteria:
Какое поведение должно быть достигнуто?

Verification:
Какие команды или проверки нужно выполнить?

Если этих ответов нет, агент начинает заполнять пробелы сам.

Ключевые термины

Термин	Значение
Agent Task	Маленькое проверяемое задание для одного controlled agent run.
Goal	Конкретный результат, который должен появиться после task.
Context	Краткое объяснение связи task с feature/spec/design.
Inputs	Документы, файлы и артефакты, которые агент должен прочитать.
Allowed Scope	Файлы или области, которые можно изменять.
Do Not Modify	Файлы, модули или поведение, которые нельзя менять.
Constraints	Архитектурные, продуктовые, security или workflow ограничения.
Acceptance Criteria	Условия, по которым task считается выполненной.
Verification	Команды, tests или checklist для доказательства результата.
Expected Output	Что агент должен вернуть человеку после выполнения.

Плохая и хорошая task

Плохо:

Добавь reset password endpoint.

Почему плохо:

неясно, request или confirm endpoint;
нет ссылки на spec;
нет allowed scope;
нет constraints;
непонятно, какие tests писать;
непонятно, что нельзя менять;
непонятно, как проверить результат.

Хорошо:

TASK AUTH-017

Goal:
Добавить endpoint проверки reset token.

Context:
Это часть Password Reset feature.
Endpoint нужен frontend форме перед показом password reset form.

Inputs:
- specs/password-reset/spec.md: REQ-003, REQ-004, AC-003, AC-004
- specs/password-reset/design.md: ResetTokenService section
- docs/architecture/constraints.md: Auth layering
- existing file: src/auth/auth.controller.ts
- existing tests: tests/auth/test_reset_token.py

Allowed scope:
- src/auth/*
- tests/auth/*

Do not modify:
- database schema
- email service
- frontend
- login flow

Constraints:
- Controller must call AuthService.
- Do not access database from controller.
- Do not store or expose raw reset token.

Acceptance criteria:
- valid token -> HTTP 200
- expired token -> HTTP 400 TOKEN_EXPIRED
- consumed token -> HTTP 400 TOKEN_USED
- malformed token -> HTTP 400 TOKEN_INVALID

Verification:
- pytest tests/auth/test_reset_token.py -q
- pytest tests/auth/test_auth_controller.py -q

Expected output:
- changed files
- tests added/updated
- commands run with exit codes
- AC status
- notes about any unresolved issues

Такую task уже можно дать coding agent с меньшим риском.

Структура Agent Task

Goal

Goal должен быть один.

Плохо:

Добавить backend, UI и E2E для password reset.

Лучше:

Добавить service method, который создает reset token для существующего пользователя.

Context

Context объясняет, зачем task нужна в общей feature.

Эта task подготавливает token generation для request reset endpoint.
Следующие задачи будут использовать этот service method из controller.

Context не должен превращаться в полный пересказ spec. Ссылки на source documents лучше длинных вставок.

Inputs

Inputs говорят агенту, что прочитать перед edit.

Inputs:
- specs/password-reset/spec.md: REQ-001..REQ-004
- docs/architecture/adr/ADR-001-password-reset-token-storage.md
- src/auth/reset_token_service.py
- tests/auth/test_reset_token.py

Если файл неизвестен заранее, можно указать search instruction:

Find existing auth service and token repository patterns before editing.

Allowed scope

Allowed scope ограничивает diff.

Allowed scope:
- src/auth/reset_token_service.py
- tests/auth/test_reset_token.py

Для первых задач scope лучше делать уже. Если агенту понадобится выйти за scope, он должен остановиться и объяснить причину.

Do not modify

Этот раздел защищает соседние области.

Do not modify:
- src/email/*
- src/users/*
- frontend/*
- database migrations

Constraints

Constraints связывают task с архитектурой и security.

Constraints:
- Follow ADR-001: reset token stored only as hash.
- Do not import EmailService in repository.
- Service must not return raw token after persistence except to caller for email link construction.

Acceptance Criteria

AC на уровне task должен быть меньше feature AC, но связан с ним.

AC:
- service creates token for active user
- token expires after 15 minutes
- created token is stored as hash
- raw token is returned only once

Verification

Verification должна быть конкретной.

Плохо:

Запусти тесты.

Лучше:

pytest tests/auth/test_reset_token_service.py -q

Если полной команды нет, укажите manual check:

Manual verification:
- show diff;
- list changed files;
- explain how each AC is satisfied.

Agent Task как boundary

Task - это boundary между planning и execution.

flowchart TD A[Approved spec] --> B[Architecture constraints] B --> C[Task definition] C --> D[Agent execution] D --> E[Verification] E --> F[Review] F --> G{Done?} G -->|Yes| H[Commit / next task] G -->|No| I[Fix task or clarify] I --> C

Если task плохая, execution будет нестабильным. Если task хорошая, даже несовершенный agent вынужден двигаться маленькими проверяемыми шагами.

Expected output агента

После выполнения task агент должен вернуть не только "готово".

Минимальный output:

Summary:
- что изменено;
- почему это соответствует task.

Changed files:
- ...

Verification:
- command
- exit code
- result summary

Acceptance criteria:
- AC-001 PASS
- AC-002 PASS
- AC-003 PASS

Notes:
- unresolved issues
- follow-up tasks

Это помогает человеку быстро проверить результат и не искать evidence по всему transcript.

Definition of Ready для Agent Task

Task готова к передаче агенту, если:

[ ] Goal один и проверяемый
[ ] Есть ссылка на approved spec или requirement
[ ] Inputs перечислены
[ ] Allowed scope задан
[ ] Do-not-modify list задан при необходимости
[ ] Architecture/security constraints указаны
[ ] Acceptance criteria конкретны
[ ] Verification command или checklist есть
[ ] Нет blocker open questions
[ ] Expected output описан

Если task не проходит Definition of Ready, ее нужно уточнить до запуска агента.

Практика: оформить TASK AUTH-017

Создайте или дополните:

specs/password-reset/tasks.md

Оформите task:

TASK AUTH-017: Validate reset token endpoint

Минимальные требования:

goal;
context;
inputs;
allowed scope;
do-not-modify;
constraints;
acceptance criteria;
verification;
expected output.

После написания проверьте task по Definition of Ready.

Типичные ошибки

Ошибка 1. Не указывать inputs

Если агент не знает, какие документы и файлы читать, он может начать с неверной точки.

Ошибка 2. Не ограничивать scope

Без allowed scope task превращается в маленький one-shot.

Ошибка 3. Писать verification слишком общо

Команда "запусти тесты" хуже, чем targeted command. Targeted verification ускоряет feedback loop.

Ошибка 4. Смешивать несколько outcomes

Если task добавляет DB, service, API, UI и E2E, это не одна task.

Ошибка 5. Не просить evidence в expected output

Agent output должен содержать commands, exit codes, changed files и AC status.

Критерии готовности

После урока студент должен уметь:

объяснить, что такое Agent Task;
оформить task с goal, context, inputs, allowed scope, constraints, AC и verification;
отличить плохую task от готовой к execution;
связать task со spec, design и ADR;
использовать Definition of Ready;
описать expected output agent run.

Краткое резюме

Хорошая Agent Task - это маленький контракт выполнения. Она ограничивает свободу агента, дает ему нужный контекст и заранее определяет, как будет проверяться результат.

Task должна быть достаточно маленькой для одного controlled run и достаточно полной, чтобы агенту не приходилось угадывать product или architecture decisions.

Вопросы для самопроверки

Какие поля обязательны в хорошей Agent Task?
Почему allowed scope важен для AI-generated diff?
Чем acceptance criteria отличаются от verification command?
Что должно быть в expected output агента?
Когда agent должен остановиться вместо выхода за scope?

Что дальше

В следующем уроке мы подробнее разберем размер задачи. Даже правильно оформленная task может быть слишком большой. Нам нужно научиться уменьшать задачи до одного проверяемого результата.