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.

Pilot optimize-agent-token-workflow завершён 27.08.2026. Guidance ниже остаётся в силе как наблюдённая рабочая практика, но не повышается до hard guardrail без отдельного evidence-backed change.

Routing context

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

тип работы и текущую SDD-фазу, если change versioned;
affected repositories и их canonical gates;
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 — способ убрать заведомо нерелевантный шум, а не обрезать доказательства.

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.

9.4 KiB Raw Blame History