diff --git a/README.md b/README.md index 8276d5c..7b21dca 100644 --- a/README.md +++ b/README.md @@ -74,6 +74,7 @@ problem space solution space execution space | Документ | Для кого и зачем | | --- | --- | | [Внедрение Memory Bank](docs/adoption.md) | Для команд, подключающих шаблон к brownfield- или greenfield-проекту | +| [Greenfield adaptation protocol](docs/greenfield-integration-protocol.md) | Для копирования шаблона, извлечения project facts из README и docs, адаптации Memory Bank и создания initial PRD | | [Использование Memory Bank](docs/usage.md) | Для повседневной работы с задачами и AI-агентами после внедрения | | [Установка и использование `memory-bank`](docs/memory-bank.md) | Для пользователей CLI и downstream CI | | [Разработка репозитория](docs/development.md) | Для разработчиков шаблона и CLI | diff --git a/docs/adoption.md b/docs/adoption.md index edae847..2770cbc 100644 --- a/docs/adoption.md +++ b/docs/adoption.md @@ -88,60 +88,16 @@ Brownfield-внедрение достаточно для первого раб ## Начать новый проект (greenfield) -В новом проекте Memory Bank помогает сначала определить проверяемые границы и правила, а затем переходить к реализации. - -Цель greenfield-внедрения — создать минимальный управляемый контекст до того, как код и решения начнут расходиться. Здесь Memory Bank работает как scaffold для product/domain/engineering/ops решений, но он не должен превращаться в большой speculative design document. - -1. Скопируйте `memory-bank/` и подключите его через файл инструкций агента. -2. Зафиксируйте vision, пользователей, ожидаемые результаты и метрики в `product/`. -3. Создайте начальные glossary, domain model, rules и context map в `domain/`. -4. Определите инженерные и операционные ограничения в `engineering/` и `ops/`; значимые технологические решения оформляйте как ADR. -5. Опишите первую инициативу через PRD или epic и выделите канонические use cases. -6. Работу крупнее одной delivery-feature с общим roadmap, cross-feature risks или несколькими delivery units ведите через epic. Для каждой отдельной delivery-unit сначала проверяйте `Small Change` gate; остальные пользовательские и плановые infrastructure/engineering/operations изменения проводите через feature package: `brief.md → optional design.md → implementation-plan.md`. -7. Обновляйте постоянный контекст только по мере появления проверенных знаний. - -### Greenfield минимальный стартовый комплект - -Перед первой существенной реализацией заполните: - -- `product/vision.md` — зачем существует продукт и какой outcome ожидается; -- `product/customers.md` — для кого продукт делается; -- `product/metrics.md` — как будет понятно, что результат полезен; -- `domain/glossary.md` — базовые термины без конфликтующих синонимов; -- `domain/model.md` — основные сущности и связи; -- `engineering/architecture.md` — начальные архитектурные границы и выбранный stack; -- `engineering/testing-policy.md` — какие проверки обязательны с первого дня; -- `ops/development.md` — как запускать проект локально; -- `ops/config.md` — как задаются переменные окружения и secrets; -- ADR для каждого решения, которое будет дорого менять. - -### Greenfield порядок работы - -1. Сначала product intent: users, problem, outcome, non-goals. -2. Затем domain language: glossary, entities, states, events, business rules. -3. Затем engineering constraints: stack, module boundaries, testing, CI, repo workflow. -4. Затем first initiative: PRD или epic, если работа шире одной delivery-feature. -5. Затем первая delivery-unit: feature package или `Small Change`, если issue полностью достаточен. - -### Greenfield типичные ошибки - -- проектировать слишком много до первой проверки реальным use case; -- фиксировать технологические предпочтения без ADR и trade-offs; -- создавать feature packages без product/domain owner-фактов; -- писать acceptance criteria, которые невозможно проверить; -- откладывать testing policy и CI до “потом”; -- смешивать template rules и project-specific решения. - -### Greenfield готовность - -Greenfield-внедрение достаточно для старта разработки, когда: - -- `product/`, `domain/`, `engineering/` и `ops/` задают минимальные проверяемые границы; -- первая инициатива имеет понятный owner: issue, PRD, epic или feature package; -- выбранные технологии и дорогие решения зафиксированы в ADR; -- локальный запуск и проверки описаны; -- `memory-bank lint` проходит локально; -- CI либо подключён, либо явно отложен с причиной. +Для нового GitHub-проекта используйте [протокол адаптации Memory Bank](greenfield-integration-protocol.md). Он поручает Codex изучить существующие README и docs, скопировать generic-шаблон, максимально заполнить его подтверждёнными фактами о продукте и проекте и создать initial PRD. + +Для запуска выполните в корне downstream-репозитория: + +```bash +codex --search \ + "Прочитай протокол адаптации Memory Bank по адресу https://github.com/dapi/memory-bank/blob/main/docs/greenfield-integration-protocol.md и выполни его в текущем репозитории." +``` + +Команда передаёт prompt при запуске интерактивной Codex-сессии и использует sandbox и approval policy из пользовательской конфигурации. Для воспроизводимого запуска замените `main` в URL на immutable commit SHA. ## Подключить агента diff --git a/docs/greenfield-integration-protocol.md b/docs/greenfield-integration-protocol.md new file mode 100644 index 0000000..5415eda --- /dev/null +++ b/docs/greenfield-integration-protocol.md @@ -0,0 +1,62 @@ +# Протокол адаптации Memory Bank для greenfield-проекта + +## Цель + +Скопируй generic-шаблон `memory-bank/` из `dapi/memory-bank` в корень текущего git-репозитория и адаптируй его под описанный в репозитории продукт и проект. + +Результат должен содержать максимально полный набор подтверждённых project facts, разложенных по правильным canonical owners Memory Bank, и initial PRD продукта или первой продуктовой инициативы. + +## Источники + +Перед изменениями прочитай: + +1. `AGENTS.md`, `CLAUDE.md` и другие repository instructions, если они существуют. +2. Корневой `README` и остальные README-файлы проекта. +3. Документы в `docs/` и других документированных knowledge directories. +4. Конфигурацию, manifests, CI и структуру исходного кода — только для подтверждения инженерных и операционных фактов, которых нет в документации. + +Считай источники репозитория authoritative для project-specific фактов. Если источники противоречат друг другу, не выбирай молча: зафиксируй конфликт или open question в подходящем документе. + +## Выполнение + +1. Проведи inventory найденных фактов о продукте, пользователях, предметной области, архитектуре, разработке и эксплуатации. +2. Если `memory-bank/` отсутствует, скопируй в текущий репозиторий только каталог `memory-bank/` из `dapi/memory-bank`. Если каталог уже существует, не перезаписывай его целиком — адаптируй имеющуюся копию. +3. Прочитай `memory-bank/README.md`, `memory-bank/dna/README.md` и правила document governance. +4. Замени template placeholders подтверждёнными фактами текущего проекта и максимально полно адаптируй: + - `product/` — problem, vision, users, jobs, outcomes, non-goals, metrics, positioning и roadmap; + - `domain/` — glossary, actors, entities, relationships, rules, states, events и bounded contexts; + - `engineering/` — architecture, module boundaries, technology choices, quality attributes, testing, coding и git conventions; + - `ops/` — local development, configuration, environments, releases и operational constraints; + - `use-cases/` — устойчивые пользовательские и операционные сценарии, явно следующие из источников; + - `adr/` — только уже принятые значимые архитектурные решения, найденные в источниках. +5. Создай initial PRD в `memory-bank/prd/` по шаблону `memory-bank/flows/templates/prd/PRD-XXX.md`: + - зафиксируй problem, users and jobs, goals, non-goals, product scope, business rules, success metrics, risks и open questions; + - используй стабильный project identifier или `PRD-001`, если в репозитории нет принятой схемы идентификаторов; + - не добавляй architecture design и implementation sequence в PRD; + - если источников недостаточно для уверенного утверждения, оставь документ в `draft` и запиши конкретный open question вместо догадки. +6. Обнови все затронутые README-индексы и `derived_from` связи. Каждый созданный документ должен быть достижим из `memory-bank/README.md`. +7. Проведи финальную проверку на полноту и непротиворечивость: каждый найденный устойчивый факт должен либо иметь canonical owner, либо быть явно отмечен как неприменимый, конфликтующий или неизвестный. +8. Запусти `memory-bank lint`. Исправь broken links, orphan documents и ошибки индексной навигации. Если команда недоступна, сообщи об этом как о verification gap и выполни доступную проверку ссылок и структуры. + +## Правила адаптации + +- Не выдумывай факты, требования, метрики, пользователей, domain rules, архитектуру или operational procedures. +- Не оставляй примерный template content так, будто это факт проекта. +- Не дублируй один факт в нескольких документах: выбери canonical owner, а из остальных мест поставь ссылку. +- Код владеет implementation details; Memory Bank владеет intent, rationale, project rules и contracts. +- Сохраняй полезные существующие repository instructions и документы; не заменяй их Memory Bank автоматически. +- Не реализуй продуктовые фичи и не изменяй runtime-код в рамках этой адаптации. +- Не создавай feature packages, epic packages или delivery plans, если этого прямо не требует уже существующий источник проекта. + +## Результат + +Заверши работу, когда: + +- `memory-bank/` находится в корне проекта и адаптирован под него; +- подтверждённые факты из README, docs и других изученных источников перенесены в соответствующие owner-документы; +- создан initial PRD и добавлен в `memory-bank/prd/README.md`; +- неизвестные и противоречивые сведения явно перечислены как open questions; +- навигация и ссылки согласованы; +- `memory-bank lint` проходит либо verification gap явно указан. + +В финальном ответе перечисли изменённые разделы Memory Bank, созданный PRD, использованные source documents, результат проверки и оставшиеся open questions.