155 lines
9.4 KiB
Markdown
155 lines
9.4 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.
|
|
|
|
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: <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.
|