MODULE_09 · УРОК 9.3

Verification contract

В уроке 3.3 вы уже повесили агенту на язык замок: «не говори, что тесты зелёные, если не запускал». Замок хороший, но он запрещает врать, а не учит проверять. Модель по-прежнему не знает, чем в этом проекте вообще принято проверять работу, и в лучшем случае угадывает по названиям файлов.

Полный контракт устроен иначе. Агент видит список реальных проверок этого проекта, гоняет их по порядку и в отчёте отделяет «это я сломал» от «так было до меня». Взрослая формулировка звучит примерно так: «три падения были и раньше, новых моя правка не добавила». Скучно и очень надёжно.

ЧТО ПОЛУЧИТСЯ Функция discover_gates находит проверки в pyproject.toml и рядом с ним, список команд уезжает в промпт, а секция Verification требует узких честных утверждений (scoped claims) вместо победных реляций.

Слова, которые встретятся

  • Гейт (gate) - конкретная команда проверки, шлагбаум перед словом «готово»: pytest, ruff, mypy и им подобные.
  • Узкое утверждение (scoped claim) - отчёт, который не расширяет правду: что именно запускали, что вышло, где ваша поломка, а где чужая. «Всё работает» узким утверждением не является никогда.

Быстрый путь

  1. Создать verification.py с discover_gates.
  2. В PromptContext добавить verification_commands.
  3. Переписать секцию Verification под список из контекста.
  4. В main.py вызвать discover и передать в билдер.

Какие файлы трогаем

Файл Что делать
verification.py Создать. discover_gates(sandbox).
prompts.py Править. Поле контекста + секция Verification.
main.py Править. Вызвать discover, передать список.
approval.py По желанию: префиксы uv run / pytest / ruff, иначе гейты упрутся в блок.

Шаг 1. discover_gates

Смотрим не в свои представления о правильном проекте, а в то, что реально лежит в рабочей папке. Для Python якорь один - pyproject.toml, плюс взгляд на соседние каталоги. И главное: пустой список честнее выдуманных команд. Агент, который скажет «гейтов не нашёл», полезнее агента, который уверенно запустит несуществующий make test.

verification.py (целиком)

from __future__ import annotations

from sandbox import Sandbox


async def discover_gates(sandbox: Sandbox) -> list[str]:
    """Вернуть команды проверки, которые имеют смысл в этом проекте."""
    gates: list[str] = []

    try:
        raw = await sandbox.read_file("pyproject.toml")
    except Exception:
        raw = ""

    lower = raw.lower()

    # тесты
    has_pytest = "pytest" in lower or "[tool.pytest" in lower
    try:
        listing = await sandbox.exec("ls")
        names = listing.get("stdout", "")
        if "tests" in names.split() or "test" in names.split():
            has_pytest = True
    except Exception:
        pass
    if has_pytest:
        gates.append("uv run pytest")

    # lint
    if "[tool.ruff" in lower or "ruff" in lower:
        gates.append("uv run ruff check .")

    # типы
    if "[tool.mypy" in lower or "mypy" in lower:
        gates.append("uv run mypy .")
    elif "pyright" in lower:
        gates.append("uv run pyright")

    return gates

Порядок в списке не случайный: сначала то, что быстро отвечает и ловит грубые поломки, потом тяжёлое. Наш набор из тестов, линтера и типов - обычный минимум uv-проекта, но подстройте его под свой: если mypy у вас идёт двадцать минут, ему место последним. А если pyproject.toml в папке нет вообще, вернётся пустой список, и это рабочий сценарий, а не сбой.

Шаг 2. Поле в prompts.py

В PromptContext добавьте:

    verification_commands: NotRequired[list[str]]

Старую общую секцию Verification из урока 3.3 замените на эту:

prompts.py - секция Verification

    cmds = ctx.get("verification_commands") or []
    if cmds:
        gates = "\n".join(f"{i}. `{c}`" for i, c in enumerate(cmds, 1))
    else:
        gates = "(для этого проекта команд проверки не найдено)"

    parts.append(f"""
# Verification
После изменений проверь работу этими гейтами по порядку:
{gates}

Каждый гейт: запусти, сохрани вывод, напиши что прошло и что нет.

Отделяй свои поломки от уже бывших:
- «Запустил uv run pytest: 12 passed, 0 failed.»
- «Запустил uv run pytest: 47 passed, 3 failed. Три падения в
  tests/test_user.py были до правки, новых не добавил.»

НЕ пиши «тесты прошли», если не запускал.
НЕ раздувай частичную проверку до «всё зелёное».
Если approval заблокировал команду - так и скажи.
""")
ЧЕСТНОСТЬ ТЯЖЕЛЕЕ ДИСКАВЕРИ Найти команды - самая простая часть урока. Идеальный discover_gates не стоит ничего, если модель по-прежнему пишет «проверил» там, где не запускала. Настоящая работа сделана формулировками секции, и несущая среди них одна: «отделяй свои поломки от уже бывших». Без неё агент боится красного и начинает округлять.

Шаг 3. Вызов в main.py

from verification import discover_gates

# sandbox уже создан
verification_commands = await discover_gates(sandbox)

instructions = build_system_prompt({
    "working_directory": str(cwd),
    "sandbox_type": "local",
    "tool_names": tool_names,
    "verification_commands": verification_commands,
    # git_branch / project_context - если есть
})

Если верхний уровень main у вас синхронный, оберните сборку так же, как уже обёрнут agent.run: один asyncio.run или async-main. Принципиально тут одно - discover вызывается до создания Agent, иначе список гейтов просто не попадёт в instructions, и вы будете гадать, почему промпт пустой.

Быстрая страховка на этом шаге: воткните print(verification_commands) и посмотрите глазами. Там должны быть команды вашего учебного проекта или честный [], если pyproject.toml совсем минимальный.

Как звучит отчёт

Разница между левой и правой колонкой - это разница между «поверь мне» и «вот что было». Правую можно проверить за десять секунд, левую придётся перепроверять целиком.

Плохо Нужно
«Все тесты прошли» «uv run pytest: 47 passed, 3 failed - падения старые в test_user.py»
«Сборка ок» «ruff check: exit 0. pytest: 12 passed»
«Вроде нормально» «Гейтов не найдено; правку сделал, проверки не гонял»

Проверьте

Берём заведомо безобидную правку: важно не что изменилось, а как агент об этом расскажет.

uv run python main.py . "Добавь в начало main.py однострочный комментарий # harness-9.3 и проверь работу по контракту Verification"

Дальше смотрим на четыре вещи. Агент должен:

  1. Сделать мелкую правку (write/bash - как умеет).
  2. Прогнать гейты из списка (если approval пускает).
  3. Отчитаться командой и результатом, не «вроде всё ок».
  4. При красном - сказать, его ли это или было раньше.
APPROVAL Если uv run, pytest и ruff не попали в белый список, в interactive-режиме гейты упрутся в шлагбаум. Это не поломка: контракт как раз требует сказать «команду заблокировал approval», и хорошо, если вы это увидите своими глазами. А чтобы демо доехало до конца, добавьте префиксы в SAFE_PREFIXES.

Готово, если:

  • discover_gates возвращает команды этого проекта
  • Секция Verification показывает найденные гейты
  • Агент гоняет их и пишет конкретный результат
  • Отделяет свои падения от старых (или честно говорит, что не знает)
  • При пустом списке не выдумывает «всё зелёное»
ДАЛЬШЕ - МОДУЛЬ 10 План и проверка на месте, врать агенту стало неудобно. Дальше займёмся поверхностями: приведём в порядок CLI, включим стрим, чтобы терминал перестал притворяться зависшим, и разберём, как к тому же агенту приделать web.