docs/development/agent-token-efficiency.md

Token-efficient agent workflow

Статус и границы

Эта инструкция описывает действующий guidance для сокращения повторной передачи agent context. Она не меняет SDD lifecycle, approvals, canonical gates, semantic verification или independent review и не является hard guardrail.

Исходный baseline сохранён в аудите Codex-сессий 26.08.2026. Raw rollout logs не коммитятся. Числовой budget не блокирует delivery без отдельного утверждённого change, детерминированной non-mutating проверки и controlled positive/negative evidence.

Guidance ниже остаётся non-blocking: он не заменяет required authority или verification и не повышается до hard guardrail без отдельного evidence-backed change.

Routing context

До чтения supporting documentation агент определяет:

1. тип работы и текущую SDD-фазу, если change versioned;
2. affected repositories и их canonical gates;
3. capability или source identity, нужные для следующего решения.

После этого загружается только применимый context:

Trigger	Обязательный context
Versioned SDD planning или Apply	Native OpenSpec instruction, возвращённые contextFiles и локальные AGENTS.md affected areas
Engineering policy, approval, testing, delivery или archive	Релевантный раздел engineering-governance.md
Cross-service flow или архитектурная граница	architecture/system-overview.md и применимые ADR/feature docs
Domain или API semantics	Релевантный термин architecture/domain-glossary.md и canonical contract/spec
Работа по известному Audit ID	Найденная через поиск запись и связанное evidence в audit-remediation.md
Диагностика agent token usage или этот pilot	Этот playbook и применимый dated audit snapshot

Supporting material загружается on demand, если возникший вопрос меняет семантику, архитектуру, audit disposition или обязательный gate. Guidance нельзя использовать как основание пропустить необходимую authority.

Handoff между agent-сессиями

Approved planning artifact, завершённый implementation slice или verification outcome являются естественной границей новой Codex task. Минимальный handoff:

Change: <identity>
Approved through: <explicitly approved artifact>
Current phase: <phase>
Affected areas: <areas>
Unresolved blockers: <none or list>
Next allowed outcome: <one outcome>

Planning content не копируется: новая task читает его из canonical OpenSpec store. Если явный approval недоступен в новой task, агент повторно запрашивает его и не выводит решение владельца только из наличия artifact.

Для handoff Apply → Verify дополнительно передаются фактический scope изменённых areas и unresolved failures. Полная история tool calls не передаётся.

Evidence batching

Один evidence batch заканчивается перед следующим смысловым решением:

• заранее независимые read-only lookups выполняются вместе;
• adaptive discovery, side effects и approval boundaries остаются последовательными;
• discovery начинается с rg или другого identity search, затем читает релевантный диапазон;
• diff сначала сужается через status/stat/name-only, затем раскрывает affected paths;
• successful command result сохраняет exact command identity, exit status и существенную summary;
• failure или неоднозначная summary расширяет diagnostics до достаточной причины;
• semantic verification и reviewer всегда получают полный relevant evidence.

Статический лимит строк или tool tokens не применяется: он может скрыть единственный диагностический сигнал. Compact output — способ убрать заведомо нерелевантный шум, а не обрезать доказательства.