Цикл взаимодействия с агентом · теория

Hint Contract · 5 маркеров

Когда CLI или MCP-инструмент возвращает результат - что агенту делать дальше? Без явного маркера он перечитывает CLAUDE.md, гадает, иногда галлюцинирует и зацикливается. Каждое угадывание - это токены и риск ошибки. Hint Contract убирает двусмысленность: каждый ответ Forgeplan несёт детерминированный next-action в одной из пяти форм.

01 · 5-rule Contract

Гарантии формата

Presence · Actionability · Determinism · Conditionality · Consistency

→

02 · 5 маркеров

Язык next-action

Next · Or · Wait · Done · Fix

→

03 · Reading Protocol

Что делать агенту

execute · fallback · retry · stop · remediate

01 · Почему этот контракт вообще нужен

Концепция 01 · аналогия светофоров на дороге

Без явного next-action агент платит «налог на угадывание»

Представьте дорогу без светофоров и знаков. Каждый перекрёсток - водитель угадывает: кто едет первым? Поворот разрешён? Нужно ли остановиться? Каждая догадка - это секунды задержки и риск столкновения. Светофоры убирают неопределённость: цвет - действие.

Forgeplan - это методологический движок. Каждая команда / MCP-вызов - один шаг длинного процесса (Shape → Validate → Code → Evidence → Activate). Когда после ответа агенту не сказано, что делать дальше, он:

Налог · до контракта

Что делает агент без явного next-action

Перечитывает CLAUDE.md, чтобы переоткрыть методологию
Угадывает следующий шаг, иногда галлюцинирует команду
Зацикливается на одной и той же фазе
Подставляет placeholder вроде EVID-NNN в реальную команду
Видит три равноправных опции - paradox of choice

токены · риск ошибки · потеря коннект-контекста

Решение · 5-rule contract

Что делает агент с явным маркером

Читает Next: и выполняет команду как написано
На Wait: ставит retry с условием
На Done. переходит к следующей задаче, не зацикливается
На Fix: запускает remediation немедленно
На Or: использует fallback только если primary блокирует

детерминизм · без перечитывания · без галлюцинаций

Это не «ещё одно правило» · это интерфейсный контракт

Hint Contract - это обещание формата: любой output Forgeplan (CLI text / CLI JSON / MCP success / MCP error) гарантированно содержит либо next-action, либо явный terminal-сигнал. Никаких «silent gaps». Этого достаточно, чтобы Claude Code / Cursor / Windsurf и любой кастомный orchestrator читали output одинаково, без переоткрытия методологии каждый раз.

02 · Пять правил контракта

Концепция 02 · пять гарантий формата

Каждый output Forgeplan - независимо от поверхности - удовлетворяет этим правилам

Каждое правило закрывает один конкретный класс ошибок, который возникал до v0.25.0 - когда инструмент возвращал результат, а агент не знал, что с ним делать.

PRESENCE

Каждый ответ - либо next-action, либо явный terminal. Никаких silent gaps.

ACTIONABILITY

Next-action - полная команда с реальными ID. Не фрагмент, не placeholder.

DETERMINISM

Один input state → одна hint-строка. Никакого randomness.

CONDITIONALITY

Hints только когда actionable. Terminal - Done., не фейк «all done!».

CONSISTENCY

Text и JSON - одинаковый смысл. CLI зеркалит MCP-семантику.

Где читать hint в зависимости от surface

CLI text · последние строки stdout (Next:, Fix:, Wait:, Done.). · CLI JSON · top-level поле _next_action. · MCP · top-level _next_action в response. · Спец-случай: list --json и tree --json сохраняют bare-array (backward compat для jq) - hint уходит в stderr.

03 · Пять маркеров · язык next-action

Концепция 03 · 5 маркеров с фиксированной семантикой

Каждый маркер - однозначное действие для агента

Маркеры не пересекаются по смыслу. Если в одном ответе есть Next: и Or: - это primary action и fallback. Если есть Error: и Fix: - это ошибка и команда восстановления. Done. никогда не идёт вместе с другими маркерами - это терминальный сигнал.

5 hint markers · v0.25.0+

Primary action - рекомендованный следующий шаг. Полная команда с реальными ID.

execute as-is

Or:

Альтернатива, когда primary блокирует (например, claim удерживается другим агентом).

fallback only

Wait:

Async / TTL state. Условие, после которого повторить запрос.

retry after condition

Done.

Workflow завершён. Не loop, не «всё хорошо!» - буквально точка.

move on

Fix:

Error remediation. Парная команда с Error:. Запустить немедленно.

run immediately

Good vs Bad hints

✓ Good · v0.25.0+

Next: forgeplan score PRD-001 specific, full command, real ID, rationale включён

Next: forgeplan dispatch --agents 3 Or: forgeplan claim PRD-054 --agent worker-2 --ttl-minutes 30 primary action + один explicit fallback

Error: Direct status change to 'active' is not allowed. Fix: forgeplan activate PRD-001 ошибка + executable remediation

✗ Bad · pre-v0.25.0 паттерны

suggested next: adi bare word без команды · агент гадает

Try a longer window: --since-hours 720 фрагмент, не полная команда

Either work on a different artifact, wait for TTL expiry, or ask the orchestrator to force-release. три опции, ни одна не primary · paradox of choice

Drift prevention

Контракт enforced двумя механизмами: integration test crates/forgeplan-cli/tests/hint_contract.rs - десятки тестов, фейлится CI, если команда не несёт маркер. Audit script scripts/audit-hints.sh - coverage 100% всех команд. Это не «договорённость», это проверка на pre-commit.

Три паттерна порядка работы · как контракт работает в реальности

Паттерн A

Shape → Validate → Activate

Типовой штатный путь. Каждый шаг возвращает Next: с конкретной командой следующего шага. Агент идёт по цепочке без переоткрытия методологии.

forgeplan_route("add OAuth login") → Next: forgeplan new prd "OAuth login support" forgeplan_new(kind: "prd", title: "OAuth login support") → Next: forgeplan validate PRD-042 forgeplan_validate("PRD-042") → Next: forgeplan activate PRD-042 (если PASS) → Fix: forgeplan validate PRD-042 (если errors) forgeplan_activate("PRD-042") → Done.

Паттерн B

Восстановление после ошибки

Команда вернула ошибку - но не «вот текст ошибки, разбирайся», а Error: + Fix: с готовой командой восстановления.

forgeplan_activate("PRD-042") → Error: No evidence linked → Fix: forgeplan validate PRD-042 forgeplan_validate("PRD-042") → Result: PASS → Next: forgeplan score PRD-042

Паттерн C

Multi-agent dispatch с claim-конфликтом

Несколько агентов работают параллельно. Если claim занят другим - Or: предлагает альтернативу, не блокирует worker.

forgeplan_dispatch(--agents 3) → Next: forgeplan claim PRD-054 --agent worker-1 --ttl 30 → Or: forgeplan list --status draft forgeplan_claim("PRD-054") → Error: Already held by worker-2 → Or: forgeplan release PRD-054 --force

Краткий справочник

Распечатать и держать рядом. Если в output Forgeplan нет маркера и состояние не terminal - это баг, а не «нужно подумать».

FORGEPLAN HINT CONTRACT v0.25.0+

Next:<command> · execute as-is

Or:<command> · fallback if primary blocks

Wait:<condition> · retry after condition

Done.workflow complete · move on

Fix:<command> · error remediation (with Error:)

Read from: stdout (text) · _next_action (JSON / MCP) · Special: list/tree --json → hint on stderr