Verification contract
В уроке 3.3 вы уже повесили агенту на язык замок: «не говори, что тесты зелёные, если не запускал». Замок хороший, но он запрещает врать, а не учит проверять. Модель по-прежнему не знает, чем в этом проекте вообще принято проверять работу, и в лучшем случае угадывает по названиям файлов.
Полный контракт устроен иначе. Агент видит список реальных проверок этого проекта, гоняет их по порядку и в отчёте отделяет «это я сломал» от «так было до меня». Взрослая формулировка звучит примерно так: «три падения были и раньше, новых моя правка не добавила». Скучно и очень надёжно.
discover_gates находит проверки в
pyproject.toml и рядом с ним, список команд уезжает в
промпт, а секция Verification требует узких честных утверждений
(scoped claims) вместо победных реляций.
Слова, которые встретятся
-
Гейт (gate) - конкретная команда проверки,
шлагбаум перед словом «готово»:
pytest,ruff,mypyи им подобные. - Узкое утверждение (scoped claim) - отчёт, который не расширяет правду: что именно запускали, что вышло, где ваша поломка, а где чужая. «Всё работает» узким утверждением не является никогда.
Быстрый путь
- Создать
verification.pyсdiscover_gates. - В
PromptContextдобавитьverification_commands. - Переписать секцию Verification под список из контекста.
- В
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"
Дальше смотрим на четыре вещи. Агент должен:
- Сделать мелкую правку (write/bash - как умеет).
- Прогнать гейты из списка (если approval пускает).
- Отчитаться командой и результатом, не «вроде всё ок».
- При красном - сказать, его ли это или было раньше.
uv run, pytest и
ruff не попали в белый список, в interactive-режиме
гейты упрутся в шлагбаум. Это не поломка: контракт как раз
требует сказать «команду заблокировал approval», и хорошо, если
вы это увидите своими глазами. А чтобы демо доехало до конца,
добавьте префиксы в SAFE_PREFIXES.
Готово, если:
discover_gatesвозвращает команды этого проекта- Секция Verification показывает найденные гейты
- Агент гоняет их и пишет конкретный результат
- Отделяет свои падения от старых (или честно говорит, что не знает)
- При пустом списке не выдумывает «всё зелёное»