Task contract

Большинство неудачных agent runs начинаются не с плохой модели, а с плохой задачи. «Улучши onboarding», «почини отчёт», «сделай нормально» звучит понятно человеку, который держит контекст в голове. Для агента это приглашение расширить scope, выбрать критерии успеха самому и потом убедительно рассказать, что всё готово.

Task contract превращает просьбу в ограниченную работу: что нужно получить, чего не трогаем, какие проверки запускаем и когда останавливаемся.

Из чего состоит хорошая задача

Минимальный contract можно держать в issue, Markdown или JSON. Формат вторичен. Важнее, чтобы там были эти части:

Часть	Зачем она нужна
Goal	Какой результат нужен пользователю или системе.
Context	Почему задача появилась и какие решения уже приняты.
Scope	Какие изменения разрешены.
Non-goals	Какие соседние улучшения не делаем в этом run.
Constraints	Технические, продуктовые, security и domain boundaries.
Acceptance criteria	Наблюдаемые признаки готовности.
Testing plan	Команды и проверки, которые должен выполнить harness.
Definition of Done	Что приложить к результату: logs, screenshots, summary, limitations.

Хорошая задача не пытается быть длинной. Она пытается снять неопределённость там, где ошибка будет дорогой.

До и после

Плохая задача:

Улучши onboarding.

Agent-ready версия:

Улучшить первый экран onboarding так, чтобы новый пользователь понимал, зачем вести дневник боли, мог выбрать роль пациента и перейти к первому daily check-in. Не менять backend schema. Acceptance criteria: есть role selection, текст не звучит как медицинское обещание, mobile layout не ломается на 360px, тесты и lint проходят.

Разница не в количестве текста. Во второй версии есть границы и проверка.

Как это исполняет harness

В labs contract уже не просто prose. Это task JSON, который runner может проверить:

{
  "id": "algi-01-pain-diary",
  "title": "Build ALGI pain diary slice",
  "spec": "specs/pain-diary.bdd.md",
  "context": ["AGENTS.md", "specs/pain-diary.bdd.md"],
  "expected_outputs": ["algi/__init__.py", "algi/domain.py", "tests/test_domain.py"],
  "acceptance_criteria": [
    "Pain score accepts only integers from 0 to 10.",
    "Notes and activities are normalized.",
    "Clinician summary contains aggregate values and no direct identifiers.",
    "Summary includes a non-medical-advice disclaimer."
  ],
  "checks": [
    {
      "name": "unit tests",
      "command": ["python3", "-m", "unittest", "discover", "-s", "tests"]
    }
  ]
}

Если spec или context не найден, runner не должен героически продолжать. Он классифицирует run как blocked. Если checks падают, это failed. Если checks прошли, результат всё равно может пойти на human review, если задача privacy-sensitive.

Так contract становится не красивой формальностью, а входом в исполняемый процесс.

Проверка перед запуском

Перед agent run ответьте на вопросы:

• можно ли проверить результат без устного контекста;
• помещается ли scope в один bounded run;
• есть ли non-goals;
• понятен ли testing plan;
• названы ли риски и escalation;
• success не зависит от self-report агента;
• задаче не нужны неограниченные secrets, production access или внешние side effects.

Что сделать руками

Возьмите 2-3 слабые задачи из backlog и перепишите их через шаблон task contract. После этого попробуйте честно ответить: запустили бы вы agent на такой задаче без личного пояснения в чате?

На что не соглашаться

• «Сделай красиво», «почини всё», «улучши качество» без criteria.
• Несколько независимых задач в одном contract.
• Acceptance criteria, которые нельзя проверить.
• Testing plan вида «проверь сам».
• Неявные non-goals, которые вспоминаются только на review.