# Token-efficient agent workflow ## Статус и границы Эта инструкция описывает действующий guidance для сокращения повторной передачи agent context. Она не меняет SDD lifecycle, approvals, canonical gates, semantic verification или independent review и не является hard guardrail. Исходный baseline сохранён в [аудите Codex-сессий 26.08.2026](../audits/codex-sessions-token-audit-2026-08-26.md). Raw rollout logs не коммитятся. Числовой budget не блокирует delivery без отдельного утверждённого change, детерминированной non-mutating проверки и controlled positive/negative evidence. Pilot `optimize-agent-token-workflow` завершён 27.08.2026. Guidance ниже остаётся в силе как наблюдённая рабочая практика, но не повышается до 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: ```text Change: Approved through: Current phase: Affected areas: Unresolved blockers: Next allowed 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 — способ убрать заведомо нерелевантный шум, а не обрезать доказательства. ## Pilot result ### Method Post-activation observations собирались в local non-authority dataset `.agent-token-pilot.json` после завершённых фаз SDD. Каждое наблюдение сохраняло change identity, phase type, краткий scope, context-depth indicators, canonical-gate outcome, fix cycles, independent-review findings и итог попытки без raw prompts, source contents или rollout logs в Git. ### Scope - Период наблюдения: 26.08.2026-27.08.2026. - Completed observations: `17`. - Distinct changes: `5`. - Covered phase groups: `proposal` (`4`), `specs` (`3`), `design` (`4`), `tasks` (`4`), `apply-verify` (`2`). - Interrupted attempts recorded: `0`. ### Resource and quality outcomes - Все `17/17` completed observations завершились successful canonical gate. - Совокупно зафиксировано `10` fix cycles; максимум на одно наблюдение: `4`. - Independent review понадобился для двух `apply-verify` фаз и в обоих случаях привёл к исправлению реального defect до terminal completion. - После исправлений не осталось Critical или Important findings. ### Confounders - Dataset охватывает разные phase types и неодинаковый scope, поэтому aggregate не является строгим сравнением "одинаковая работа до/после". - Для части ранних planning observations provider-counted cumulative input, model calls и tool-output volume не были сохранены как числовые поля; pilot опирается на phase outcome, context-depth indicators, gate success, fix cycles и review findings. - Наблюдение проходило на одном workspace и одном agent workflow; результат не экстраполируется на другие инструменты, модели или quota contracts. ### Verdict Stage- and area-first routing, evidence batching и compact successful command summaries показали себя как полезное guidance: pilot превысил минимальный порог в `10` завершённых фаз по `2` changes без ухудшения canonical gates, rework или independent review outcomes. На наблюдённых данных guidance следует сохранить. Числовой token budget остаётся non-blocking guidance, потому что pilot не дал детерминированной локальной проверки и не изолировал сравнимые workloads достаточно строго для hard guardrail. ## Pilot protocol Pilot change `optimize-agent-token-workflow` завершился после 17 completed post-activation SDD phases across 5 changes, превысив минимальный порог в 10 завершённых фаз минимум по двум changes. Для каждой попытки local non-authority dataset содержит: - change identity, phase type и краткий workload scope; - cumulative input, model calls, context-depth indicators и tool-output volume; - canonical-gate outcome, fix cycles и independent-review findings; - completed или interrupted outcome и причину interruption. Interrupted attempts учитываются отдельно и не исчезают из quality assessment. Raw prompts, source contents и rollout logs в Git не добавляются. Рабочий dataset хранится локально в workspace root как `.agent-token-pilot.json`; workspace root не является Git-репозиторием, а файл не является planning, handoff или documentation authority. Сравнение выполняется внутри одинаковых phase types и близкого scope, когда это возможно. Aggregate сопровождается ограничениями неоднородности. Снижение resource usage считается улучшением только без ухудшения gate success, rework и review findings. Итоговый versioned report публикует method, scope, aggregates, confounders и verdict; он не экстраполирует quota или стоимость без provider contract.