docs(ai): adopt task-driven scoped context
This commit is contained in:
@@ -1,160 +1,62 @@
|
||||
# Token-efficient agent workflow
|
||||
# Context discipline
|
||||
|
||||
## Authority и границы
|
||||
|
||||
Этот документ — vendor-neutral authority для context discipline: recovery,
|
||||
fingerprint bindings, bounded reads и observed evidence. Lifecycle ownership
|
||||
принадлежит [Engineering governance](engineering-governance.md), native команды
|
||||
— [OpenSpec lifecycle](openspec-authority-and-lifecycle.md). Эти процедуры
|
||||
выполняются без обязательных skills, session adapter, telemetry или service.
|
||||
|
||||
Исходный наблюдаемый baseline сохранён в
|
||||
[аудите сессий 26.08.2026](../audits/codex-sessions-token-audit-2026-08-26.md).
|
||||
Raw logs и числовые token budgets не становятся delivery gates. Экономия
|
||||
контекста не оправдывает пропуск relevant authority или ослабление verification.
|
||||
Цель — получить правила, которые меняют текущее решение, и не читать остальные
|
||||
заранее. Это процедура прямой работы по задаче, без обязательных SDD artifacts,
|
||||
ролей, approval fingerprints или подсчёта документов как delivery gate.
|
||||
|
||||
## Routing context
|
||||
|
||||
До supporting reads определите текущую роль, разрешённый outcome и affected
|
||||
repositories. Прочитайте их local `AGENTS.md` для boundaries и canonical gates,
|
||||
затем только применимую authority:
|
||||
1. Определи требуемое поведение, тип решения и affected repos до supporting reads.
|
||||
2. Прочитай root/local AGENTS, затем CONVENTIONS и SOURCES affected code repo.
|
||||
3. Объедини сработавшие semantic, path и boundary triggers. Путь — сигнал ответственности, а не повод загружать всё по расширению `.tsx`/`.ts`.
|
||||
4. Прочитай выбранные conventions или явно указанные sections до зависимого решения. При domain/API/security вопросе открой точный source через [docs index](../AI_INDEX.md).
|
||||
5. Проследи ближайший существующий owner и подходящие код/тесты. Его поведение не заменяет canonical fact.
|
||||
6. Повтори routing при новой потребности и по финальным staged, unstaged и новым файлам. Содержимое работы важнее первоначального названия задачи.
|
||||
|
||||
| Trigger | Context |
|
||||
| --- | --- |
|
||||
| Planning или Implementation | Native instruction и каждый возвращённый context file; применимые материалы через canonical Design |
|
||||
| Approval, роль, testing, Delivery Map или completion | Релевантный раздел governance |
|
||||
| Cross-area architecture | `architecture/system-overview.md`, нужные ADR/feature docs |
|
||||
| Domain или API semantics | Термин в `architecture/domain-glossary.md`, canonical contract/spec |
|
||||
| Известный Audit ID | Найденная запись `audit-remediation.md` и её source/evidence |
|
||||
| Validation | Approved artifacts, delivery inventory, relevant checks и findings |
|
||||
| Finalization | Текущий независимый verdict с binding и существующие delivery facts |
|
||||
Первый проход работает без diff. Auth + refresh, например, активирует API,
|
||||
security и testing вместе. Отображение query state без изменения запросов не
|
||||
добавляет transport rules. Docs-only опечатка не требует frontend/backend conventions.
|
||||
Обычно хватает нескольких тем; это наблюдение, не лимит. Обязательный source
|
||||
нельзя пропускать ради числа файлов или token budget.
|
||||
|
||||
В новой роли canonical artifacts читаются заново только в необходимом scope.
|
||||
В том же context повторно читаются изменившиеся relevant inputs. История чата
|
||||
не заменяет artifact и не является обязательным prerequisite.
|
||||
Новая граница внутри задачи требует дочитать правила до работы. Расширение
|
||||
самой задачи сначала сообщи пользователю; уже данное разрешение не запрашивай
|
||||
повторно. Чужой concurrent diff учитывай при разграничении ownership.
|
||||
|
||||
## Источники и конфликты
|
||||
|
||||
Прямое указание пользователя определяет задачу. Текущий executable HTTP contract
|
||||
генерируется backend; docs описывает проектные факты/решения; conventions задают
|
||||
выбор реализации; code показывает существующие аналоги. Generic framework advice
|
||||
используется после проектных источников. Research содержит рекомендации, которые
|
||||
нужно сверить с actual code/config, а не автоматически превращать в новый контракт.
|
||||
|
||||
Если задача намеренно меняет контракт, обновляй его source и зависимые материалы
|
||||
согласованно. Missing input, противоречие security/data правил или неоднозначный
|
||||
контракт блокируют только зависимое решение до установления фактов/уточнения.
|
||||
История чата, случайный аналог и предполагаемый путь не заменяют источник.
|
||||
|
||||
## Recovery и handoff
|
||||
|
||||
При наличии session adapter mutable state является единственным navigation
|
||||
pointer. Прочитайте только его текущий self-contained immutable record, затем
|
||||
phase-specific authority. Без adapter тот же актуальный envelope передаётся
|
||||
в доступном рабочем контексте; отдельный versioned verdict или planning store
|
||||
ради handoff не создаётся.
|
||||
Для продолжения достаточно текущей задачи, сделанных изменений, remaining work,
|
||||
точных checks/results и blockers. Не создавай параллельную копию требований,
|
||||
Design, state registry или обязательный handoff-файл.
|
||||
|
||||
Envelope содержит только change identity, текущую роль/outcome, affected areas,
|
||||
observed approval bindings, completed/remaining task IDs, краткие observed checks,
|
||||
blockers и один следующий допустимый outcome. Для продолжения после Validation
|
||||
он также сохраняет её verdict, relevant inventory и fingerprint; Finalization
|
||||
retry не должен требовать восстановления цепочки старых records. Requirements,
|
||||
Design, Tasks и acceptance scenarios остаются в canonical OpenSpec.
|
||||
В новом контексте восстанови необходимые sources; в том же переиспользуй уже
|
||||
прочитанные неизменившиеся inputs. Supporting reads добавляй по возникшему вопросу.
|
||||
Git status/diff показывают staged и unstaged; новые файлы учитывай отдельно.
|
||||
Relevant ignored/workspace-owned inputs (например `.env`, root AGENTS) не
|
||||
теряются только потому, что Git их не показывает. Секреты в evidence не печатай.
|
||||
|
||||
Первичное `approved` записывается только после явного решения Change Owner,
|
||||
со ссылкой на наблюдённый источник решения, artifact identity и fingerprint.
|
||||
При recovery совпадение позволяет продолжить без повторного approval. Отсутствие
|
||||
binding, включая legacy state, требует явного решения; mismatch сбрасывает
|
||||
approval изменённого artifact и всех downstream artifacts. Approval status
|
||||
сохраняет наблюдение, но не доказывает личность или решение владельца сам по себе.
|
||||
## Проверка эффективности
|
||||
|
||||
Порядок сохранения: `canonical outcome → immutable record → state pointer`.
|
||||
Сначала создаётся новый record; существующие records не перезаписываются. Перед
|
||||
заменой pointer проверяется, что исходный state не изменён другим участником.
|
||||
Конфликт или неполная запись остаются видимыми и не разрешаются last-write-wins.
|
||||
Старые records читаются только для расследования конкретного текущего расхождения.
|
||||
Используй [набор routing cases](agent-context-evals.md) для настройки новых правил.
|
||||
Проверяй activating case, safe exception и unrelated counterexample по реальным
|
||||
инструкциям. Source links и gates дополняют эту проверку, но не доказывают first-pass quality.
|
||||
|
||||
## Fingerprints
|
||||
|
||||
Fingerprint имеет вид `sha256:<64 lowercase hex digits>` и связывает observation
|
||||
с содержимым, а не только с именем файла, временем изменения или Git HEAD.
|
||||
Одинаковая процедура применяется к approval artifact, gate inputs и PASS;
|
||||
отличаются только scope и явно указанная ниже нормализация task progress.
|
||||
|
||||
### Scope и inventory
|
||||
|
||||
До проверки сохраните reviewed inventory: workspace-relative точные пути и
|
||||
релевантные directory roots, их явные exclusions, назначение набора и список
|
||||
входящих files. Directory roots должны включать новые files, способные изменить
|
||||
проверяемый результат; произвольный список только уже известных изменённых files
|
||||
недостаточен. Scope покрывает все actual inputs gate/review, включая dependency
|
||||
и config files. Unrelated concurrent change исключается по объяснённой границе,
|
||||
а не потому, что мешает получить прежний fingerprint.
|
||||
|
||||
- Proposal и Tasks — соответствующий canonical файл. Design — его Markdown
|
||||
и все перечисленные применимые материалы, включая exact immutable reuse
|
||||
inputs. Перечень разрешается из Design, без параллельного visual registry;
|
||||
missing, ambiguous или изменённый материал блокирует dependent outcome по
|
||||
[UI/UX policy](engineering-governance.md#uiux-пакет-design). Сам Design не
|
||||
содержит собственного digest. Delta Specs —
|
||||
полный разрешённый native CLI набор `specs/**/spec.md` этого change; при
|
||||
сравнении membership запрашивается заново, чтобы обнаружить additions/removals.
|
||||
- PASS включает raw approved planning artifacts, relevant main baseline,
|
||||
проверенные delivery files affected areas и local unversioned instructions,
|
||||
если они входят в change. Runtime/gate command и environment prerequisites
|
||||
сохраняются рядом с fingerprint как observed metadata.
|
||||
- Для каждого Git repository candidate paths получают через
|
||||
`git ls-files --cached --others --exclude-standard -z`, затем пересекают
|
||||
с reviewed roots/paths и de-duplicate. Это включает tracked и nonignored
|
||||
untracked, staged и unstaged working content. Workspace-owned paths вне Git
|
||||
перечисляются явно; relevant ignored inputs также включаются явно.
|
||||
- При сравнении заново раскрываются те же roots и добавляются paths из прежнего
|
||||
inventory: исчезнувший файл остаётся entry `missing`, новый входит в набор.
|
||||
Directory names не хешируются отдельно. Пути используют `/`, относительно
|
||||
workspace, без `.`/`..`, абсолютного host prefix и повторов.
|
||||
- Собственные navigation state, phase records и
|
||||
`changes/<change>/completion-evidence.md` исключаются из self-hash. Exclusions
|
||||
относятся к конкретному change, не ко всем `.agents`, `.opencode` или specs.
|
||||
Ожидаемые archive/sync/evidence/registry mutations проверяются отдельно как
|
||||
completion outputs; ими нельзя скрыть новое implementation изменение.
|
||||
|
||||
### Детерминированное представление
|
||||
|
||||
1. Для каждого entry прочитайте текущие bytes из working tree. `file` получает
|
||||
mode `100755`, если установлен хотя бы один executable bit, иначе `100644`.
|
||||
`symlink` получает mode `120000`, payload — bytes самого link target без
|
||||
разыменования. Для отсутствующего прежнего path используйте kind `missing`,
|
||||
mode `-`, digest `-`. Unresolved Git conflicts, unreadable inputs и special
|
||||
files блокируют binding; приблизительный fingerprint не создаётся.
|
||||
2. Только для **approval Tasks** замените ASCII prefix `b"- [x] "` на `b"- [ ] "`
|
||||
у строк canonical task checkbox (`X.Y [area]` после prefix). Другие bytes,
|
||||
whitespace, строки, `Covers` и `Verification` не меняются. Во всех остальных
|
||||
наборах, включая gate/PASS и их Tasks, используется raw payload. Таким образом
|
||||
observed progress не отменяет approval содержания, но остаётся виден review.
|
||||
3. Рассчитайте lowercase SHA-256 hex digest payload каждого существующего entry.
|
||||
Отсортируйте entries по UTF-8 bytes workspace-relative path. Непредставимые
|
||||
в UTF-8 paths требуют явного разрешения input issue, а не замены символов.
|
||||
4. Соберите byte stream: ASCII prefix `wealth-ledger-input-v1` и один NUL byte,
|
||||
затем для каждого entry UTF-8 fields `path`, `kind`, `mode`, `digest`, каждый
|
||||
с завершающим NUL. Пробелы, JSON, newline separators и BOM не добавляются.
|
||||
SHA-256 этого stream с prefix `sha256:` — fingerprint всего набора.
|
||||
|
||||
Inventory и fingerprint не содержат копии исходных artifacts. Если review
|
||||
зависит от содержимого symlink target, target включается отдельным input;
|
||||
хеширование только ссылки не подтверждает внешнее содержимое. Перенос файлов,
|
||||
изменение mode, content или membership меняют binding. Commit/staging без
|
||||
изменения этих данных его не меняют. Relevant input mutation инвалидирует PASS;
|
||||
изменение planning approval fingerprint дополнительно применяет cascade policy.
|
||||
|
||||
## Повторное использование evidence
|
||||
|
||||
Сохранённый успешный gate повторно используется при совпадении его input scope,
|
||||
fingerprint и relevant environment prerequisites. Evidence сохраняет exact
|
||||
command, cwd, exit status и достаточный observed result. Неизвестный scope или
|
||||
отсутствующий binding не доказывают неизменность. Нельзя заменить full gate
|
||||
результатом проверки части файлов.
|
||||
|
||||
Validation независимо оценивает свежесть gates и semantic/acceptance behavior;
|
||||
успех Implementation tests сам по себе не даёт независимый PASS. Finalization
|
||||
сверяет последний PASS до terminal mutations и потребляет его без повторения
|
||||
неизменившихся checks. Expected archive move, approved semantic sync и создание
|
||||
Completion Evidence проверяются как новые completion outputs; их effect не
|
||||
переписывает сохранённое описание проверенного delivery input.
|
||||
|
||||
## Evidence batching
|
||||
|
||||
Один batch заканчивается перед следующим смысловым решением. Независимые
|
||||
read-only inputs получают вместе; adaptive discovery, side effects и approvals
|
||||
остаются последовательными. Начните с `rg`/identity search или Git status/stat,
|
||||
затем раскройте relevant paths. Successful output сохраняет команду, exit status
|
||||
и существенный outcome; failure, semantic verification и review получают весь
|
||||
relevant evidence. Произвольный лимит строк не должен скрывать диагностический
|
||||
сигнал. Контекст оценивается вместе с качеством checks, findings и rework,
|
||||
а не по сокращению tokens отдельно.
|
||||
Сравнивай startup context и реально выбранные sections, фиксируя способ измерения.
|
||||
Не объявляй меньшее число файлов или зелёный application test улучшением качества
|
||||
агента. Для first-pass acceptance нужны одинаковые реальные задачи/модель/tools,
|
||||
наблюдённые ошибки ownership/contract/security и число исправлений.
|
||||
Добавляй convention по повторяющейся decision error; уточняй trigger при missed
|
||||
source; deterministic regression отдавай существующему test/linter, если он подходит.
|
||||
|
||||
Reference in New Issue
Block a user