102 lines
6.3 KiB
Markdown
102 lines
6.3 KiB
Markdown
# 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.
|