diff --git a/README.md b/README.md index b536738..8f4493d 100644 --- a/README.md +++ b/README.md @@ -75,6 +75,7 @@ problem space solution space execution space | Документ | Для кого и зачем | | --- | --- | | [Внедрение Memory Bank](docs/adoption.md) | Для команд, подключающих шаблон к brownfield- или greenfield-проекту | +| [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-агентами после внедрения | | [Использование `memory-bank-cli`](docs/memory-bank.md) | Для пользователей CLI и downstream CI | diff --git a/docs/adoption.md b/docs/adoption.md index bd7b441..0dfbbb2 100644 --- a/docs/adoption.md +++ b/docs/adoption.md @@ -14,58 +14,9 @@ memory-bank/ ## Адаптировать существующий проект (brownfield) -В существующем проекте Memory Bank сначала должен отразить реальное состояние продукта и разработки, а не желаемую картину. +Для существующего проекта следуйте [brownfield adaptation protocol](brownfield-adaptation-protocol.md). Он начинает с evidence-backed discovery **до** установки и чтения `memory-bank/`, затем описывает intake PRD, adaptation canonical owners, governed conversion, validation и real-task trial. -Цель brownfield-внедрения — сделать текущий контекст проекта видимым и проверяемым для людей и агентов. Не начинайте с идеального описания будущей архитектуры. Сначала зафиксируйте то, что уже влияет на разработку: реальные пользователи, термины, ограничения, интеграции, принятые решения, неочевидные правила и known gaps. - -1. Скопируйте каталог `memory-bank/`. -2. Проведите inventory существующего кода, документации, терминов, архитектурных решений и процессов. -3. Адаптируйте `product/`, `domain/`, `engineering/` и `ops/`. В `engineering/ui-design-guide/` заполните draft-заготовки для реальных UI surfaces и удалите неприменимые файлы вместе со ссылками из index. Не выдумывайте отсутствующие знания: отмечайте пробелы и вопросы явно. -4. Перенесите устойчивые сценарии в `use-cases/`, а значимые принятые решения — в ADR. -5. Проверьте подход на одной реальной задаче или фиче, прежде чем описывать весь проект. -6. Запустите аудит ссылок и индексации. - -### Brownfield inventory - -Минимальный inventory перед первой адаптацией: - -- README, wiki, runbooks, ADR, старые design docs; -- ключевые директории кода и границы модулей; -- production/staging/local окружения; -- внешние интеграции и владение credentials/config; -- основные пользовательские сценарии и операционные сценарии; -- термины, которые уже используются в коде, UI, API и команде; -- текущий CI/CD и обязательные проверки перед merge; -- известные технические долги, ограничения и опасные зоны. - -### Brownfield порядок заполнения - -1. `product/` — что продукт уже делает, для кого, какие outcomes и метрики реально важны. -2. `domain/` — glossary, domain model, states/events/rules из существующей системы. -3. `engineering/` — текущая архитектура, coding style, testing policy, frontend/backend conventions, git workflow. -4. `ops/` — локальный запуск, окружения, config, release process, runbooks. -5. `use-cases/` — только устойчивые сценарии, которые уже проверяются или должны проверяться. -6. `adr/` — решения, которые уже приняты и продолжают влиять на разработку. - -Если факт неизвестен, пишите это явно: `Unknown`, `TBD`, `Needs owner confirmation`. Для агента это безопаснее, чем уверенная выдумка. - -### Brownfield типичные ошибки - -- описывать желаемую архитектуру как текущую; -- переносить в Memory Bank все старые документы без нормализации и ownership; -- создавать PRD/feature packages до описания базового product/domain/engineering context; -- дублировать один и тот же факт в нескольких местах; -- блокировать PR из-за устаревшей документации, которую команда ещё не готова исправлять. - -### Brownfield готовность - -Brownfield-внедрение достаточно для первого рабочего использования, когда: - -- агент может понять, как проект устроен, из `memory-bank/README.md` и owner-документов; -- минимум `product/`, `domain/`, `engineering/` и `ops/` адаптированы под реальный проект; -- known gaps явно отмечены; -- одна реальная задача прошла через `Small Change`, feature package, bug fix или другой выбранный flow; -- `memory-bank-cli lint` проходит локально. +Не заменяйте protocol кратким inventory: порядок важен, потому что generic template не является источником project facts до завершения discovery. ## Начать новый проект (greenfield) @@ -84,7 +35,7 @@ codex --search \ Используйте managed-блок, который устанавливает `memory-bank-cli init`: он направляет агента к `memory-bank/README.md`, `memory-bank/dna/README.md` и `memory-bank/flows/routing.md`, не копируя governance. Не редактируйте содержимое между markers вручную; project-specific инструкции размещайте снаружи. Полный marker, update, doctor и alternative-target contract описан в [managed-блоках agent instructions](agent-instructions.md). -Для первой адаптации можно использовать запрос: +После установки Memory Bank для первой адаптации можно использовать запрос: ```text Прочитай ./memory-bank/README.md и governance-ядро в ./memory-bank/dna/. diff --git a/docs/brownfield-adaptation-protocol.md b/docs/brownfield-adaptation-protocol.md new file mode 100644 index 0000000..4fe2adf --- /dev/null +++ b/docs/brownfield-adaptation-protocol.md @@ -0,0 +1,191 @@ +# Протокол адаптации Memory Bank для brownfield-проекта + +## Цель и граница + +Этот protocol помогает добавить Memory Bank в уже существующий web service или +CLI utility так, чтобы он отражал наблюдаемое состояние проекта, а не желаемую +картину. Он не заменяет существующие repository instructions, документацию или +код и не реализует продуктовые изменения. + +**До шага «Установить и активировать» не открывайте, не копируйте и не +консультируйте `memory-bank/`, включая generic template, его README, governance +и templates.** На этой стадии они не являются источником project knowledge: +placeholders и generic rules нельзя принимать за facts текущего репозитория. + +Если repository sources противоречат друг другу или факта нет, не выбирайте +молча: сохраните conflict или open question с источниками, confidence и owner, +если он известен. + +## Источники pre-adaptation discovery + +Сначала прочитайте repository instructions (`AGENTS.md`, `CLAUDE.md` и +эквиваленты), затем исследуйте только уже существующие project sources: + +- root и nested README, wiki, docs, runbooks, design docs и historical ADR; +- source code, manifests, dependency files и critical code paths; +- CI/CD, configuration, deployment/release definitions и observability assets; +- existing task-tracker, operational и ownership references, доступные в scope. + +Не извлекайте и не копируйте secret values, PII, tokens или internal endpoints. +Допустимо зафиксировать только owner и безопасный access procedure. + +## Lifecycle + +### 1. Pre-adaptation discovery + +Проведите inventory источников и зафиксируйте только наблюдаемые facts, их +source references, freshness и confidence. На этой стадии Memory Bank не +установлен и не используется. + +Минимальный inventory: + +- runtime modules, boundaries, dependencies и critical code paths; +- API/UI contracts, clients, queues, scheduled jobs, webhooks и external + integrations; +- configuration, feature flags, ownership/access procedure для secrets, + environments, CI/CD, release/rollback, migrations, observability, SLOs и + alerts; +- existing docs/ADRs/runbooks, их owner и известные freshness concerns; +- product terminology, key user/operational flows, technical debt, risky areas + и unresolved ownership. + +### 2. Создать intake PRD вне Memory Bank + +Создайте временный evidence-backed документ +`./brownfield-intake-prd.md` в корне downstream repository. Этот путь — +default; repository может использовать иной уже принятый путь только если он +явно записан, находится вне `memory-bank/` и сохраняет все обязательные поля +ниже. + +Intake PRD не governed document и не source of truth после conversion. Он +содержит: + +- current product problem, users/jobs, goals, non-goals и scope; +- success signals, risks, assumptions, open questions и conflicts; +- source reference для каждого существенного факта, confidence и известного + owner/freshness; +- inventory summary и список intentionally unadapted facts/documents. + +Не добавляйте invented architecture, selected solution, delivery plan, feature +packages или epics. Unknown означает `Unknown`/`TBD`/`Needs owner confirmation`, +а не правдоподобную догадку. + +### 3. Установить и активировать Memory Bank + +Только после завершения discovery скопируйте или инициализируйте `memory-bank/` +по [инструкции CLI](memory-bank.md). Затем прочитайте +`memory-bank/README.md`, governance-ядро и применимый flow. Сохраните existing +repository instructions: managed agent block дополняет их, но не заменяет. + +### 4. Адаптировать canonical owners из тех же evidence + +Переносите durable facts из intake PRD в owner-документы без дублирования: + +| Owner layer | Что адаптировать | +| --- | --- | +| `product/` | Current product problem, users, jobs, outcomes, non-goals и известные success signals | +| `domain/` | Glossary, actors, entities, states/events/rules и bounded contexts, подтверждённые sources | +| `engineering/` | Architecture, module boundaries, technology/testing/coding/git conventions и technical constraints | +| `ops/` | Local development, config ownership, environments, releases, rollback и runbooks | + +Отмечайте unknown, conflicts и owner-pending facts в соответствующем owner или +явном gap/open-question record вместе с evidence. Для real UI surfaces заполните +релевантные draft-заготовки в `engineering/ui-design-guide/`; неприменимые +файлы и их index links удаляйте только после проверки, что они не нужны проекту. + +### 5. Govern intake PRD + +После адаптации только нужных upstream owners конвертируйте intake PRD в +`memory-bank/prd/PRD-XXX-*.md` по PRD template. Governed PRD: + +- зависит через `derived_from` только от уже адаптированных relevant upstream + owners; +- сохраняет source references, confidence, conflicts, assumptions и open + questions, а не превращает их в asserted facts; +- добавляется в `memory-bank/prd/README.md` и достижим из navigation tree. + +Temporary intake PRD можно оставить как historical evidence или удалить по +repository retention policy; в обоих случаях governed PRD должен сохранить +нужную provenance. Не превращайте его в second active canonical owner. + +### 6. Добавить только подтверждённые durable artifacts + +Создавайте или обновляйте use cases только для устойчивых доказанных flows, а +historical ADR — только для уже принятых и всё ещё влияющих решений. Не +создавайте epics, feature packages или delivery plans, пока existing source +явно не требует delivery work. + +### 7. Validate и trial + +Обновите README indexes и `derived_from` links. Запустите +`memory-bank-cli lint` и `memory-bank-cli doctor`; если команда недоступна, +запишите точную verification gap и выполните доступную проверку +ссылок/структуры. Затем используйте adapted context в одной реальной task через +подходящий flow до объявления rollout complete. + +## Product-type considerations + +Inventory и owner-документы conditional: не создавайте irrelevant artifacts. +Для каждого unsupported dimension укажите `N/A` и короткую причину. + +### Web service + +Проверьте и адаптируйте, если применимо: + +- API/UI contracts, authentication/authorization, tenancy, rate limits и + compatibility commitments; +- data stores, caches, asynchronous processing, webhooks, retention и + migration constraints; +- deployment/rollback, health checks, contract/E2E testing, observability и + operational response. + +### CLI utility + +Проверьте и адаптируйте, если применимо: + +- commands/subcommands, flags, stdin/stdout/stderr contract, exit codes, + non-interactive behavior и shell completion; +- installation/distribution, supported OS/architectures, update/uninstall; +- config files, environment variables, filesystem effects, remote API + compatibility, golden tests и user-visible error compatibility. + +## Safety и change control + +- Не перезаписывайте existing docs, instructions или runtime code как часть + adaptation. +- Ссылайтесь на external/legacy sources вместо indiscriminate copying; сохраняйте + их status и freshness caveats. +- Выполняйте adaptation в reviewable change. Перечислите created, changed и + intentionally unadapted documents. +- Назначьте follow-up trigger и owner для обновления Memory Bank при изменении + source code, operations или documented contracts. + +## Minimum rollout Definition of Done + +- [ ] Baseline `product/`, `domain/`, `engineering/` и `ops/` адаптированы из + evidence или явно отмечены gaps/`N/A`. +- [ ] Intake PRD находится вне `memory-bank/`; governed/draft PRD имеет + корректные upstream dependencies и index route. +- [ ] Все known gaps, conflicts и owner-pending facts имеют evidence и owner, + если он известен. +- [ ] Use cases и historical ADRs созданы только при source evidence; лишние + delivery artifacts не созданы. +- [ ] `memory-bank-cli lint` и `memory-bank-cli doctor` успешны либо + verification gap указан без заявления об успехе. +- [ ] Adapted context испытан на одной real task через выбранный flow. +- [ ] Reviewable change перечисляет created, changed и intentionally unadapted + documents, а также follow-up owner/triggers. + +## Copyable Codex prompt + +```text +Это brownfield-репозиторий. До явной команды «установить Memory Bank» не +открывай и не консультируй memory-bank/. Сначала прочитай repository +instructions и исследуй только существующие README, docs, code, manifests, +CI/CD, configuration, runbooks и historical ADR. Запиши evidence-backed intake +PRD в ./brownfield-intake-prd.md: facts, sources, confidence, conflicts, +assumptions, open questions и owner/freshness. Не выдумывай architecture или +delivery plan. После discovery установи Memory Bank, адаптируй canonical owners +из того же evidence, конвертируй intake в governed PRD и проверь +memory-bank-cli lint/doctor. +```