Skip to content
Closed
Show file tree
Hide file tree
Changes from all commits
Commits
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
1 change: 1 addition & 0 deletions README.md
Original file line number Diff line number Diff line change
Expand Up @@ -89,6 +89,7 @@ service setup-команды проекта; он намеренно не пер
| [Brownfield adaptation protocol](docs/brownfield-adaptation-protocol.md) | Для evidence-backed адаптации существующего репозитория до и после установки Memory Bank |
| [Greenfield adaptation protocol](docs/greenfield-integration-protocol.md) | Для копирования шаблона, извлечения project facts из README и docs, адаптации Memory Bank и создания initial PRD |
| [Использование Memory Bank](docs/usage.md) | Для повседневной работы с задачами и AI-агентами после внедрения |
| [Праймеринг контекста](docs/context-priming.md) | Для подготовки AI-агента к конкретной задаче и сбора релевантного контекста |
| [Использование `memory-bank-cli`](docs/memory-bank.md) | Для пользователей CLI и downstream CI |
| [Глоссарий](docs/glossary.md) | Термины governance и структуры документации, используемые в этом репозитории |
| [Ownership и безопасные обновления](docs/ownership.md) | Для понимания lock schema, границ владения и conflict policy |
Expand Down
106 changes: 106 additions & 0 deletions docs/context-priming.md
Original file line number Diff line number Diff line change
@@ -0,0 +1,106 @@
# Праймеринг контекста

Праймеринг контекста (*context priming*) — подготовка агента к конкретной
задаче до начала планирования или изменения файлов. Агент последовательно
собирает ровно те сведения о проекте, предметной области, ограничениях и
текущем состоянии кода, которые нужны для обоснованной работы.

Цель праймеринга — не «залить в модель весь репозиторий», а дать ей надёжную
исходную картину. Он уменьшает риск неверных предположений, повторения уже
принятых решений и изменений в неподходящей части системы.

## Из чего состоит

Практичный праймеринг проходит в три шага:

1. **Общий прогрев.** Агент читает входную точку проекта и его навигацию:
`README`, инструкции агента и главный индекс Memory Bank. Так он узнаёт
назначение проекта, его устройство и правила работы.
2. **Специализация.** Агент переходит только к разделам, связанным с задачей:
конкретной подсистеме, доменному правилу, feature package, ADR, контракту
или тестовой политике.
3. **Граундинг задачи.** Перед планированием агент сверяет сформулированную
задачу с реальным состоянием репозитория: затронутым кодом, тестами,
интерфейсами и актуальными ограничениями. Результатом должны стать
подтверждённые факты, открытые вопросы и границы изменения.

Для нового проекта первый шаг часто сводится к брифу и базовым инженерным
правилам. Для существующего проекта все три шага особенно важны: фактическое
состояние кода может отличаться от ожиданий или устаревшего описания.

## Праймеринг в lifecycle Memory Bank

В шаблоне праймеринг разделён на три уровня, чтобы не смешивать сбор контекста
с выбором lifecycle или выполнением задачи:

- **P0 — route classification:** перед Task Routing собираются только facts,
нужные для выбора flow или точного вопроса человеку;
- **P1 — route profile:** после routing контекст специализируется под первый
gate выбранного flow — например, reproduction для bug fix или baseline для
refactoring;
- **P2 — execution grounding:** только когда конкретный flow требует
дополнительной проверки текущего состояния перед execution. В Feature Flow
это `GRND-*` evidence против immutable commit SHA перед sequencing.

Подробный contract и profiles определяет
[`memory-bank/flows/priming.md`](../template/memory-bank/flows/priming.md).
Routing и праймеринг различаются: первый выбирает lifecycle, второй снабжает
следующее решение проверяемым контекстом.

## Progressive disclosure, а не полная загрузка

Праймеринг использует [progressive disclosure](../template/memory-bank/dna/principles.md):
сначала индекс, затем нужный раздел, затем конкретный документ или фрагмент.
Полный Memory Bank и весь репозиторий редко нужны для одной задачи; лишний
контекст затрудняет поиск существенного и делает ответ менее сфокусированным.

Хорошая инструкция не перечисляет все возможные файлы, а задаёт маршрут и
цель чтения. Например:

```text
Изучи README и главный индекс Memory Bank. Затем найди документы и код,
относящиеся к <подсистеме>. Не изменяй файлы. Сначала верни:
- текущую реализацию и её ограничения;
- применимые доменные и инженерные правила;
- существующие тесты и контракты;
- неясности, которые нужно уточнить до плана.
```

Аннотированные ссылки в индексах помогают агенту выбрать следующий документ:
они объясняют не только *что* открыть, но и *зачем* это читать.

## Как сохранить чистый рабочий контекст

Длинный разговор смешивает утверждённые решения, отклонённые варианты и
промежуточные догадки. Поэтому полезно:

- собирать согласованный бриф или краткое резюме вне диалога;
- для следующей итерации начинать с чистого запроса, содержащего только
подтверждённые требования и результат праймеринга;
- отделять исследование, реализацию и независимую проверку в разные задачи
или сессии, когда им нужны разные точки зрения.

Это не означает игнорировать историю: устойчивые решения следует фиксировать
в их canonical owner, а не держать только в переписке.

## Минимальный результат праймеринга

До перехода к плану или реализации агент должен уметь кратко ответить:

- какую цель и границы имеет задача;
- какие документы и участки кода являются источниками истины;
- какие контракты, инварианты и тесты нельзя нарушить;
- чего пока не хватает для безопасного решения.

Если остаётся существенная неопределённость, нужно уточнение или отдельный
research/design этап, а не уверенное продолжение реализации. Праймеринг не
заменяет Task Routing, acceptance criteria, планирование и проверку результата;
он делает каждый из этих этапов более обоснованным.

## Связь с Memory Bank

Memory Bank делает праймеринг повторяемым: его индексы и canonical documents
помогают агенту найти актуальный контекст без копирования описаний в каждый
промпт. Начинать следует с [`memory-bank/README.md`](../template/memory-bank/README.md),
а маршрут входящей задачи определяет
[`memory-bank/flows/routing.md`](../template/memory-bank/flows/routing.md).
12 changes: 12 additions & 0 deletions docs/glossary.md
Original file line number Diff line number Diff line change
Expand Up @@ -79,6 +79,18 @@ SSoT, status и порядок зависимостей.
Это удерживает верхний уровень читаемым и не смешивает обзор с
низкоуровневыми подробностями.

## Context Priming (Праймеринг контекста)

`Context priming` / `праймеринг контекста` — подготовка агента к конкретной
задаче через последовательный сбор релевантных project facts до планирования
или реализации. Обычно он включает общий прогрев по индексам проекта,
специализацию на нужной подсистеме и граундинг задачи на актуальном коде,
контрактах и тестах. Праймеринг следует `progressive disclosure`: он не
означает загрузить весь репозиторий или весь Memory Bank в один контекст.
Практическое описание приведено в [статье о праймеринге](context-priming.md).
В template lifecycle `P0` подготавливает выбор route, `P1` специализируется
под первый gate flow, а flow-specific `P2` выполняется только при необходимости.

## Index-First

`Index-first` — правило, по которому каждый документ должен быть достижим из
Expand Down
2 changes: 2 additions & 0 deletions template/memory-bank/flows/README.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ purpose: Навигация по task routing, lifecycle flows и governed-ша
derived_from:
- ../dna/governance.md
- routing.md
- priming.md
- research.md
- incident.md
- bug-fix.md
Expand All @@ -25,6 +26,7 @@ audience: humans_and_agents
Каталог `memory-bank/flows/` содержит reusable process-layer для шаблона: lifecycle rules, taxonomy стабильных идентификаторов и governed templates.

- [Task Routing](routing.md) — порядок выбора flow, routing predicates, повторный routing и Human Routing.
- [Task Context Priming](priming.md) — общий P0 перед routing и профильные P1-проверки контекста перед первым gate каждого route.
- [Research & Discovery Flow](research.md) — evidence-backed lifecycle research-задач, от question framing до decision и handoff без преждевременного delivery.
- [Incident And PIR Flow](incident.md) — containment, recovery, timeline, RCA, PIR и prevention work.
- [Bug Fix Flow](bug-fix.md) — reproduction, analysis, fix, regression coverage и closure.
Expand Down
5 changes: 5 additions & 0 deletions template/memory-bank/flows/bug-fix.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ purpose: Delivery flow для воспроизводимого расхожде
derived_from:
- ../dna/governance.md
- routing.md
- priming.md
- ../engineering/testing-policy.md
- ../engineering/validation-profiles.md
canonical_for:
Expand All @@ -23,6 +24,10 @@ audience: humans_and_agents

Bug — наблюдаемое поведение, противоречащее уже принятому expected behavior. Источником может быть error tracker, support, QA, пользовательский report или incident analysis.

## Context Priming

До Entry Gate выполни [`P1-BUG`](priming.md#p1-bug-bug-fix). Expected/actual behavior, reproduction evidence и unknowns фиксируются в bug report или linked delivery task.

## Entry Gate

- [ ] expected и actual behavior различимы
Expand Down
5 changes: 5 additions & 0 deletions template/memory-bank/flows/epic.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ derived_from:
- ../dna/governance.md
- ../dna/frontmatter.md
- routing.md
- priming.md
- feature.md
canonical_for:
- epic_directory_structure
Expand Down Expand Up @@ -36,6 +37,10 @@ FPF-основание:
- **Evidence Graph**: epic решения должны ссылаться на источники, stakeholder answers, specs, ADR или code facts.
- **Q-Bundle**: качество epic нельзя свести к одному score; оно проверяется набором отдельных свойств ниже.

## Context Priming

До Epic Intake или Bootstrap Epic выполни [`P1-EPIC`](priming.md#p1-epic-epic). Intake facts и open questions принадлежат `brief.md`; при прямом bootstrap они фиксируются в `charter.md` или linked issue.

## Package Rules

1. Все документы одного epic живут в `memory-bank/epics/EP-XXX/`.
Expand Down
5 changes: 5 additions & 0 deletions template/memory-bank/flows/feature.md
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,7 @@ derived_from:
- ../dna/governance.md
- ../dna/frontmatter.md
- routing.md
- priming.md
- ../engineering/validation-profiles.md
canonical_for:
- feature_directory_structure
Expand Down Expand Up @@ -35,6 +36,10 @@ audience: humans_and_agents

Этот документ задает порядок появления feature-артефактов. Агент должен вести feature package по стадиям и не создавать downstream-артефакты раньше, чем созрел их upstream-owner.

## Context Priming

До bootstrap feature package выполни [`P1-FEAT`](priming.md#p1-feat-feature). Он подготавливает problem-space context для draft `brief.md`, но не выбирает solution и не заменяет обязательный execution-grounding с immutable revision и `GRND-*` evidence перед Plan Ready.

## Package Rules

1. Все документы одной фичи живут в `memory-bank/features/FT-XXX/`.
Expand Down
5 changes: 5 additions & 0 deletions template/memory-bank/flows/incident.md
Original file line number Diff line number Diff line change
Expand Up @@ -6,6 +6,7 @@ purpose: Operational flow от обнаружения и containment инцид
derived_from:
- ../dna/governance.md
- routing.md
- priming.md
- ../engineering/testing-policy.md
- ../ops/runbooks/README.md
canonical_for:
Expand All @@ -30,6 +31,10 @@ detection → triage → containment → recovery → timeline
→ root cause analysis → remediation → PIR → prevention work
```

## Context Priming

Сразу после route выполни timeboxed [`P1-INC`](priming.md#p1-inc-incident-and-pir). Его результат фиксируется в incident record/timeline; containment не ждёт broad discovery.

## Response Gates

- [ ] impact и affected surfaces зафиксированы
Expand Down
Loading
Loading