docs: activate token-efficient agent workflow

2026-08-26 16:44:02 +03:00
parent 35c5302e78
commit 42fd8940dc
7 changed files with 904 additions and 1 deletions
@@ -0,0 +1,101 @@
+# 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.
+
+## 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 — способ убрать заведомо
+нерелевантный шум, а не обрезать доказательства.
+
+## Pilot protocol
+
+Pilot change `optimize-agent-token-workflow` остаётся active до 10 завершённых
+post-activation SDD-фаз минимум по двум 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.