# 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.

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:

```text
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 — способ убрать заведомо
нерелевантный шум, а не обрезать доказательства.