From 75c5e30fe7ca89ad52239f0d182dc37a2729dd72 Mon Sep 17 00:00:00 2001 From: Danil Pismenny Date: Mon, 24 Aug 2026 16:41:17 +0500 Subject: [PATCH] docs: reframe Memory Bank as a development system --- README.md | 86 ++++++++++++++----- README.ru.md | 238 ++++++++++++++++++++++++++++++++------------------- 2 files changed, 216 insertions(+), 108 deletions(-) diff --git a/README.md b/README.md index 97d9142..4c98b65 100644 --- a/README.md +++ b/README.md @@ -1,16 +1,22 @@ # Memory Bank -**A durable, version-controlled context and governance layer for software development with coding agents.** +**A version-controlled development system that gives coding agents durable knowledge, explicit governance, and repeatable delivery flows.** [Русская версия](README.ru.md) · [Adoption guide](docs/adoption.md) · [Daily usage](docs/usage.md) -**`AGENTS.md` can tell an agent how to start. Memory Bank preserves what the project means, why decisions were made, and how work is verified.** +**`AGENTS.md` can tell an agent how to start. Memory Bank preserves what the project means, why decisions were made, how work moves from a problem to verified code, and what the next agent needs to know.** -Coding agents are most useful when they share the same understanding of the product, domain, architecture, constraints, and definition of done. Memory Bank keeps that knowledge in Git, next to the code, instead of leaving it in one person's head or a disposable chat session. +## What it is -It gives humans and agents an authoritative starting point, routes work through explicit delivery flows, and preserves the decisions and evidence needed to resume a task in a fresh session. +Memory Bank combines three parts that reinforce one another: -Memory Bank is not a wiki, task tracker, or agent runner. It is the control plane around those tools: durable context, ownership rules, lifecycle gates, and verification contracts. +1. **A project knowledge base** for product, domain, engineering, operations, requirements, and decisions. +2. **A governance layer** that defines who owns each fact, how documents depend on one another, and which source wins when documents disagree. +3. **A delivery system** whose flows turn tasks into governed artifacts, implementation, verification, and new durable knowledge. + +Memory Bank is built on the **First Principles Framework (FPF)**. Work starts from explicit facts, constraints, assumptions, and desired outcomes; decisions preserve their rationale and evidence instead of disappearing into a chat session. + +It is not a wiki, task tracker, or agent runner. It is the development control plane around those tools: durable context, ownership rules, lifecycle gates, reusable processes, and verification contracts. Use it when a project has one or more of these symptoms: @@ -23,23 +29,30 @@ Use it when a project has one or more of these symptoms: ## What you get - **Durable project context** — product intent, domain language, engineering rules, and operational constraints survive across sessions. -- **Clear ownership** — Single Source of Truth rules prevent the same fact from drifting across documents. +- **A Single Source of Truth** — every canonical fact has one owner; derived documents point back to that source instead of becoming competing copies. - **Governed delivery** — task routing selects the smallest suitable flow for incidents, bugs, research, small changes, epics, refactoring, or features. -- **Portable starting point** — an agent brings the template into a repository and adapts it from the project's own evidence. -- **Optional automation** — a companion CLI can later add ownership-aware updates and automated documentation checks. +- **Reusable reasoning tools** — artifact templates make the agent state the problem, constraints, selected solution, implementation steps, and verification evidence explicitly. +- **A self-growing knowledge base** — delivery leaves behind decisions, requirements, scenarios, and evidence that future work can reuse. +- **A portable starting point** — an agent brings the template into a repository and adapts it from the project's own evidence. ```text -Memory Bank context and rules - ↓ - Issue / task - ↓ - Agent session and delivery flow - ↓ - Implementation → verification → PR - ↓ - New durable knowledge returns to Memory Bank +Project knowledge + DNA + ↓ + Issue / task + ↓ + Task Routing + ↓ + Delivery Flow + ↓ +Brief → Design Pack → Implementation Plan + ↓ + Code → verification → PR + ↓ +Decisions, evidence, and new knowledge return to Memory Bank ``` +The result is a feedback loop: project knowledge guides delivery, and delivery improves project knowledge. + ## Start with an agent Copy the prompt that matches the repository. It tells the agent to bring in and @@ -77,20 +90,48 @@ cycle and its smaller routes. ## How it works -The `dna/` layer defines document governance: source ownership, dependency direction, lifecycle, frontmatter, and navigation. Stable project context lives in `product/`, `domain/`, `engineering/`, and `ops/`. Requirements and decisions mature through research, PRDs, epics, use cases, feature packages, and ADRs. +### DNA and Single Source of Truth + +The `dna/` layer is the constitution of the knowledge base. It defines Single Source of Truth, document ownership, dependency direction, lifecycle, frontmatter, and navigation rules. These principles keep Memory Bank internally consistent as it grows. + +A canonical document owns a fact. Another document may derive a requirement, plan, or view from it, but must preserve the dependency. When two documents disagree, ownership and dependency direction show which source is authoritative. + +### Project knowledge + +Stable project context lives in `product/`, `domain/`, `engineering/`, and `ops/`. Research, product initiatives, scenarios, delivery packages, and decisions live in `research/`, `prd/`, `epics/`, `use-cases/`, `features/`, and `adr/`. + +Documents own intent, requirements, rationale, and contracts. Code owns implementation. A fresh agent session can therefore resume from the same task and canonical sources without reconstructing the project from chat history. -For a substantial delivery feature, the context typically develops in three stages: +### Flows and Feature Packs + +The `flows/` layer describes repeatable processes that an agent can follow. Every task begins with [Task Routing](template/memory-bank/flows/routing.md), which selects the applicable lifecycle and its evidence requirements. + +For a substantial feature, Feature Flow produces a Feature Pack in three stages: ```text brief.md design.md implementation-plan.md what and why → chosen solution → implementation and checks problem space solution space execution space - (when required) ``` -Documents own intent, requirements, rationale, and contracts. Code owns implementation. A new agent session can therefore restart from the same task and canonical documents without reconstructing the project from chat history. +- `brief.md` owns the problem, scope, requirements, and verification contract; +- the Design Pack owns the selected solution, its rationale, and solution-level contracts; +- `implementation-plan.md` owns execution sequencing and checkpoints. + +The implementation changes the code, while lasting decisions and evidence return to their canonical owners in Memory Bank. The Feature Pack remains as a durable account of what changed, why it changed, and how the result was verified. + +### Templates as reasoning tools + +The templates in `flows/templates/` are not merely blank forms. They require an agent to separate the problem, solution, execution, and verification; name assumptions and constraints; compare meaningful alternatives; and preserve traceability. Filling the template therefore improves the decision process as well as its documentation. + +## Automation + +Memory Bank does not require a runner or CLI, but this repository includes two automation paths: + +- the optional [`memory-bank-cli`](docs/memory-bank.md) adds ownership-aware updates, link checks, diagnostics, and downstream CI; +- the experimental [Symphony integration](docs/symphony-github-issues.md) dispatches selected GitHub Issues to Codex in isolated workspaces and hands completed pull requests to human review. -Every task begins with [Task Routing](template/memory-bank/flows/routing.md), which selects the applicable lifecycle and its evidence requirements. +Symphony runs agents and repository work. Memory Bank supplies the knowledge, governance, delivery flows, and verification contracts those agents follow. ## Template layout @@ -118,6 +159,7 @@ After installation, `memory-bank/README.md` is the primary index inside the down - [Context priming for an agent task](docs/context-priming.md) - [Glossary](docs/glossary.md) - [Optional CLI automation](docs/memory-bank.md) +- [Symphony with GitHub Issues](docs/symphony-github-issues.md) - [Ownership and safe updates](docs/ownership.md) - [Repository development](docs/development.md) - [Detailed overview in Russian](README.ru.md) diff --git a/README.ru.md b/README.ru.md index b7615a3..0d586ae 100644 --- a/README.ru.md +++ b/README.ru.md @@ -1,164 +1,230 @@ -# Memory Bank — governance-ядро AI Software Development OS +# Memory Bank — система разработки программного обеспечения с ИИ-агентами -[English version](README.md) +**Версионируемая система, которая даёт агентам долговременные знания о проекте, явные правила и повторяемые процессы разработки.** -**`AGENTS.md` объясняет агенту, как начать. Memory Bank сохраняет смысл проекта, принятые решения и способ доказать результат.** +[English version](README.md) · [Внедрение](docs/adoption.md) · [Повседневная работа](docs/usage.md) + +**`AGENTS.md` объясняет агенту, как начать. Memory Bank сохраняет смысл проекта, причины принятых решений, путь от задачи до проверенного кода и знания, необходимые следующему агенту.** + +## Что это + +Memory Bank объединяет три взаимосвязанные части: + +1. **Базу знаний проекта** — сведения о продукте, предметной области, инженерии, эксплуатации, требованиях и решениях. +2. **Правила управления знаниями** — кто владеет каждым фактом, как документы зависят друг от друга и какому источнику доверять при противоречии. +3. **Систему процессов разработки** — как превратить задачу в согласованные документы, реализацию, проверку и новые долговременные знания. + +В основе Memory Bank лежит **First Principles Framework (FPF), метод мышления от первых принципов**. Работа начинается с явно сформулированных фактов, ограничений, допущений и желаемого результата, а решения сохраняют обоснование и подтверждения вместо того, чтобы исчезнуть вместе с историей чата. + +Memory Bank — не вики, не трекер задач и не инструмент запуска агентов. Это управляющий слой разработки вокруг этих инструментов: долговременный контекст, правила владения знаниями, этапы готовности, повторяемые процессы и критерии проверки. + +Memory Bank полезен, если в проекте встречается хотя бы одна из этих проблем: + +- новый агент вынужден восстанавливать замысел продукта из истории переписки; +- одно правило записано в нескольких документах, и версии начинают расходиться; +- реализация начинается до прояснения требований, рисков и критериев приёмки; +- задачу нельзя продолжить без человека, который вёл предыдущую сессию; +- успешная проверка заявлена, но не связана с тем, что именно проверялось. + +## Что вы получаете + +- **Долговременный контекст проекта** — замысел продукта, язык предметной области, инженерные правила и эксплуатационные ограничения сохраняются между сессиями. +- **Единственный источник истины** — у каждого канонического факта есть один владелец, а производные документы ссылаются на него, а не создают конкурирующие копии. +- **Управляемую разработку** — маршрутизация выбирает наименьший подходящий процесс для инцидента, дефекта, исследования, небольшой задачи, крупной инициативы, рефакторинга или функционального изменения. +- **Повторяемые инструменты мышления** — шаблоны заставляют явно сформулировать проблему, ограничения, выбранное решение, шаги реализации и подтверждения результата. +- **Самонаполняющуюся базу знаний** — после разработки остаются решения, требования, сценарии и подтверждения, которыми воспользуются следующие задачи. +- **Переносимую точку старта** — агент устанавливает шаблон в репозиторий и адаптирует его по фактам самого проекта. + +```text +Знания о проекте + ДНК + ↓ + Задача + ↓ + Маршрутизация + ↓ + Процесс разработки + ↓ +Бриф → Дизайн-пакет → План реализации + ↓ + Код → проверки → запрос на слияние + ↓ +Решения, подтверждения и новые знания возвращаются в Memory Bank +``` + +Так возникает замкнутый цикл: знания проекта направляют разработку, а результаты разработки улучшают знания проекта. ## Начать с агентом -Скопируй запрос для своего типа проекта. Он поручает агенту принести и -адаптировать Memory Bank; полный lifecycle определяют связанные протоколы. +Скопируйте запрос для своего типа проекта. Он поручает агенту установить и +адаптировать Memory Bank; полный жизненный цикл определяют связанные протоколы. -### Greenfield +### Новый проект ```text Это новый проект. Выполни https://github.com/dapi/memory-bank/blob/main/docs/greenfield-integration-protocol.md. ``` -### Brownfield +### Существующий проект ```text Это существующий проект. Выполни https://github.com/dapi/memory-bank/blob/main/docs/brownfield-adaptation-protocol.md. ``` -Для воспроизводимого запуска замени `main` в URL протокола на immutable commit -SHA. +Для воспроизводимого запуска замените `main` в адресе протокола на неизменяемый +идентификатор коммита. ## Выполнить задачу -После адаптации Memory Bank передай агенту задачу и этот запрос: +После адаптации Memory Bank передайте агенту задачу и этот запрос: ```text Прочитай задачу, ./memory-bank/README.md и ./memory-bank/flows/routing.md. -Выбери применимый flow и следуй его каноническому lifecycle. В финале сообщи -route, изменённые артефакты, verification и open risks. +Выбери подходящий процесс и следуй его каноническому жизненному циклу. В финале +сообщи выбранный маршрут, изменённые документы, результаты проверок и открытые +риски. ``` -[Повседневная работа](docs/usage.md) объясняет цикл «задача → flow → проверки» -и более короткие маршруты. +[Инструкция по повседневной работе](docs/usage.md) объясняет цикл «задача → +процесс → проверка» и короткие маршруты. -## Что это +## Как это работает -Memory Bank — переносимый documentation-first шаблон для разработки ПО с AI-агентами. Его копируют в проект и адаптируют так, чтобы человек и агент одинаково понимали: +### ДНК и единственный источник истины -- какой продукт создаётся и для кого; -- как устроена предметная область; -- какие инженерные и операционные правила действуют; -- какие требования, сценарии и архитектурные решения приняты; -- как работа будет реализована и проверена. +`dna/` — конституция базы знаний. Здесь определены принцип единственного источника истины, владение документами, направление зависимостей, жизненный цикл, метаданные и правила навигации. Эти принципы сохраняют внутреннюю согласованность Memory Bank по мере его роста. -Это не вики и не архив заметок, а версионируемая рабочая память проекта. Важный контекст хранится рядом с кодом, а не в голове разработчика или одноразовом чате. +Канонический документ владеет фактом. Другой документ может вывести из него требование, план или представление, но обязан сохранить зависимость от источника. Если документы противоречат друг другу, правила владения и направление зависимостей показывают, какой источник является авторитетным. -Здесь **OS** — метафора operating system для процесса разработки. Memory Bank работает как control plane: задаёт контекст, правила, lifecycle и критерии готовности. Task tracker, agent runner, coding agent, Git и CI образуют execution layer вокруг него. +### Знания о проекте -## Как это работает +Постоянный контекст проекта находится в `product/`, `domain/`, `engineering/` и `ops/`. Исследования, продуктовые инициативы, сценарии, комплекты документов разработки и решения находятся в `research/`, `prd/`, `epics/`, `use-cases/`, `features/` и `adr/`. + +Документы владеют замыслом, требованиями, обоснованием решений и контрактами. Код владеет реализацией. Поэтому новую сессию агента можно начать с той же задачи и канонических источников, не восстанавливая проект из истории переписки. + +### Процессы и Feature Pack -`dna/` задаёт governance-ядро: Single Source of Truth, зависимости между документами, lifecycle, frontmatter и правила навигации. Постоянный контекст проекта находится в `product/`, `domain/`, `engineering/` и `ops/`; research, инициативы, сценарии и решения — в Research, PRD, epic, use case и ADR. +В `flows/` описаны повторяемые процессы, которым может следовать агент. Каждая задача начинается с [маршрутизации](template/memory-bank/flows/routing.md): она выбирает подходящий жизненный цикл и необходимые подтверждения. -Для значимой delivery-фичи контекст созревает поэтапно: +Для значимого функционального изменения процесс Feature Flow создаёт Feature Pack — комплект документов фичи, который проходит три стадии: ```text brief.md design.md implementation-plan.md -что и зачем → какое решение → как реализовать и проверить -problem space solution space execution space - (если требуется) +что и зачем → выбранное решение → реализация и проверки +пространство задачи пространство решения пространство исполнения ``` -Документы не должны дублировать друг друга. Код владеет реализацией, а Memory Bank — намерением, требованиями, обоснованием решений и контрактами. +- `brief.md` владеет проблемой, границами, требованиями и критериями проверки; +- дизайн-пакет владеет выбранным решением, его обоснованием и контрактами решения; +- `implementation-plan.md` владеет порядком реализации и контрольными точками. + +Реализация изменяет код, а долговременные решения и подтверждения возвращаются к своим каноническим владельцам в Memory Bank. Feature Pack остаётся описанием того, что изменилось, почему это изменилось и как был проверен результат. + +### Шаблоны как инструменты мышления + +Шаблоны в `flows/templates/` — не пустые бланки. Они требуют от агента разделить задачу, решение, исполнение и проверку; назвать допущения и ограничения; сравнить значимые варианты; сохранить прослеживаемость. Поэтому заполнение шаблона улучшает не только документацию, но и сам процесс принятия решения. + +## Автоматизация + +Для базовой работы Memory Bank не требует отдельного инструмента запуска или командной утилиты, но этот репозиторий содержит два направления автоматизации: + +- необязательная утилита [`memory-bank-cli`](docs/memory-bank.md) добавляет безопасные обновления с учётом владельцев, проверку ссылок, диагностику и проверки в непрерывной интеграции; +- экспериментальная [интеграция с Symphony](docs/symphony-github-issues.md) передаёт выбранные задачи GitHub агенту Codex в изолированных рабочих директориях, а готовые запросы на слияние направляет человеку на проверку. -Агенту передаётся компактный стартовый контекст и ссылки на нужные owner-документы. Если сессия исчерпала контекст, новую можно начать с той же задачи: важные факты, решения и способы проверки остаются в Memory Bank. +Symphony запускает агентов и работу с репозиторием. Memory Bank предоставляет знания, правила, процессы разработки и критерии проверки, которым следуют эти агенты. ## Что находится в шаблоне -В этом source-репозитории payload хранится в `template/`. Агент переносит в -корень downstream-репозитория tracked regular files из этого каталога: например, -`template/memory-bank/` становится `memory-bank/`, а `template/init.sh` — -`./init.sh`. Имя `template/` в проект-получатель не переносится. +В этом исходном репозитории содержимое шаблона хранится в `template/`. Агент +переносит файлы, отслеживаемые Git, из этой директории в корень проекта-получателя: +например, `template/memory-bank/` становится `memory-bank/`, а +`template/init.sh` — `./init.sh`. -| Каталог | Назначение | +| Директория | Назначение | | --- | --- | -| [`dna/`](template/memory-bank/dna/README.md) | Governance-ядро: SSoT, frontmatter, lifecycle и правила связей между документами | -| [`product/`](template/memory-bank/product/README.md) | Vision, customers, metrics, marketing и roadmap | -| [`domain/`](template/memory-bank/domain/README.md) | Glossary, domain model, business rules, states, events и context map | -| [`engineering/`](template/memory-bank/engineering/README.md) | Архитектура, тестирование, coding style, git workflow и границы автономии агента | -| [`ops/`](template/memory-bank/ops/README.md) | Локальная разработка, окружения, конфигурация, релизы и runbooks | -| [`prd/`](template/memory-bank/prd/README.md) | Продуктовые инициативы между общим product context и отдельными фичами | -| [`research/`](template/memory-bank/research/README.md) | Evidence-backed market, product и technical research до решения о delivery | -| [`epics/`](template/memory-bank/epics/README.md) | Крупные инициативы с roadmap, рисками, решениями и delivery subissues | -| [`use-cases/`](template/memory-bank/use-cases/README.md) | Канонические пользовательские и операционные сценарии | -| [`features/`](template/memory-bank/features/README.md) | Пакеты отдельных delivery-фич | -| [`adr/`](template/memory-bank/adr/README.md) | Архитектурные решения и причины их принятия | -| [`flows/`](template/memory-bank/flows/README.md) | Lifecycle-процессы и шаблоны документов | -| [`prompts/`](template/memory-bank/prompts/README.md) | Human-only каталог prompt-артефактов и его access contract | - -После установки шаблона [`memory-bank/README.md`](template/memory-bank/README.md) становится основным индексом downstream-проекта. - -Корневой [`template/init.sh`](template/init.sh) — portable bootstrap для -`mise`, Git submodules и `direnv`, если соответствующие файлы есть в проекте. -После установки адаптируй `./init.sh` под реальные dependency, database и -service setup-команды проекта; он намеренно не переносит `.env`-файлы. +| [`dna/`](template/memory-bank/dna/README.md) | Правила управления: единственный источник истины, метаданные, жизненный цикл и связи между документами | +| [`product/`](template/memory-bank/product/README.md) | Замысел продукта, пользователи, показатели, продвижение и дорожная карта | +| [`domain/`](template/memory-bank/domain/README.md) | Словарь, модель предметной области, правила, состояния, события и границы контекстов | +| [`engineering/`](template/memory-bank/engineering/README.md) | Архитектура, тестирование, стиль кода, работа с Git и границы самостоятельности агента | +| [`ops/`](template/memory-bank/ops/README.md) | Локальная разработка, окружения, конфигурация, выпуски и операционные инструкции | +| [`research/`](template/memory-bank/research/README.md), [`prd/`](template/memory-bank/prd/README.md), [`epics/`](template/memory-bank/epics/README.md) | Исследования и планирование инициатив | +| [`use-cases/`](template/memory-bank/use-cases/README.md), [`features/`](template/memory-bank/features/README.md), [`adr/`](template/memory-bank/adr/README.md) | Сценарии, комплекты документов разработки и архитектурные решения | +| [`flows/`](template/memory-bank/flows/README.md) | Жизненные циклы задач и повторно используемые шаблоны документов | + +После установки [`memory-bank/README.md`](template/memory-bank/README.md) становится основным указателем внутри проекта-получателя. + +Корневой [`template/init.sh`](template/init.sh) — переносимый сценарий начальной +настройки для `mise`, вложенных репозиториев Git и `direnv`, если соответствующие +файлы есть в проекте. После установки адаптируйте `./init.sh` под реальные +команды установки зависимостей, подготовки базы данных и запуска служб; сценарий +намеренно не переносит файлы `.env`. ## Внедрение в проект -В downstream-проект устанавливается каталог `memory-bank/`. Исходники CLI, -Go-модуль, CI и release-конфигурация этого репозитория не являются частью -шаблона приложения. Ownership lock и автоматизированные обновления — -опциональное расширение, а не условие базового внедрения. +В проект-получатель устанавливаются директория `memory-bank/` и сценарий +`init.sh`. Исходники командной утилиты, модуль Go, непрерывная интеграция и +настройки выпуска этого репозитория не входят в шаблон приложения. Безопасные +автоматические обновления и проверки — необязательное расширение, а не условие +базового внедрения. Инструкция по внедрению охватывает: -- адаптацию существующего проекта (brownfield); -- запуск нового проекта (greenfield); +- адаптацию существующего проекта; +- запуск нового проекта; - настройку агента; -- локальную проверку и downstream CI. +- локальную проверку и проверки проекта-получателя в непрерывной интеграции. Следуйте [инструкции по внедрению](docs/adoption.md). ## Выбор рабочего процесса -Каждая задача сначала проходит [Task Routing](template/memory-bank/flows/routing.md). Он направляет работу в Incident, Bug Fix, Research & Discovery, Small Change, Epic, Refactoring, Feature или на ручное решение. +Каждая задача сначала проходит [маршрутизацию](template/memory-bank/flows/routing.md). Она направляет работу в процесс обработки инцидента, исправления дефекта, исследования, небольшого изменения, крупной инициативы, рефакторинга или функционального изменения либо передаёт выбор человеку. -Корневой README даёт только обзор. Условия входа, lifecycle, обязательные артефакты и exit contract принадлежат каноническим документам в [`memory-bank/flows/`](template/memory-bank/flows/README.md) и не дублируются здесь. +Корневой README даёт только обзор. Условия входа, жизненные циклы, обязательные документы и критерии завершения принадлежат каноническим документам в [`memory-bank/flows/`](template/memory-bank/flows/README.md) и не дублируются здесь. ## Документация репозитория | Документ | Для кого и зачем | | --- | --- | -| [Внедрение 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-агентами после внедрения | -| [Праймеринг контекста](docs/context-priming.md) | Для подготовки AI-агента к конкретной задаче и сбора релевантного контекста | -| [User Story, Use Case и BDD-сценарии](docs/bdd-user-stories-and-use-cases.md) | Для разделения устойчивого сценария, delivery slice и проверяемых примеров поведения | -| [Опциональная CLI-автоматизация](docs/memory-bank.md) | Для безопасных обновлений и downstream CI при необходимости | -| [Глоссарий](docs/glossary.md) | Термины governance и структуры документации, используемые в этом репозитории | -| [Ownership и безопасные обновления](docs/ownership.md) | Для понимания lock schema, границ владения и conflict policy | -| [Managed-блок инструкций агента](docs/agent-instructions.md) | Для marker contract, doctor и выбора единственного agent instruction target | +| [Внедрение Memory Bank](docs/adoption.md) | Для команд, подключающих шаблон к существующему или новому проекту | +| [Протокол адаптации существующего проекта](docs/brownfield-adaptation-protocol.md) | Для основанной на фактах адаптации репозитория до и после установки Memory Bank | +| [Протокол создания нового проекта](docs/greenfield-integration-protocol.md) | Для копирования шаблона, извлечения фактов из README и документации, адаптации Memory Bank и создания исходного описания продукта | +| [Использование Memory Bank](docs/usage.md) | Для повседневной работы с задачами и ИИ-агентами после внедрения | +| [Подготовка контекста](docs/context-priming.md) | Для подготовки ИИ-агента к конкретной задаче и сбора уместного контекста | +| [Пользовательские истории, варианты использования и BDD-сценарии](docs/bdd-user-stories-and-use-cases.md) | Для разделения устойчивого сценария, поставляемой части функции и проверяемых примеров поведения | +| [Необязательная автоматизация через CLI](docs/memory-bank.md) | Для безопасных обновлений и проверок проекта-получателя в непрерывной интеграции | +| [Symphony и задачи GitHub](docs/symphony-github-issues.md) | Для автоматического запуска Codex по выбранным задачам GitHub | +| [Словарь](docs/glossary.md) | Для терминов управления знаниями и структуры документации | +| [Владение и безопасные обновления](docs/ownership.md) | Для понимания схемы блокировки, границ владения и правил разрешения конфликтов | +| [Управляемый блок инструкций агента](docs/agent-instructions.md) | Для служебных меток, диагностики и выбора единственного файла инструкций агента | | [Разработка репозитория](docs/development.md) | Для разработчиков шаблона | -Опциональный `memory-bank-cli` добавляет безопасные обновления, проверку links и -диагностику governance. Он разрабатывается и выпускается отдельно в -[`dapi/memory-bank-cli`](https://github.com/dapi/memory-bank-cli). +Необязательная утилита `memory-bank-cli` добавляет безопасные обновления, +проверку ссылок и диагностику правил. Она разрабатывается и выпускается отдельно +в [`dapi/memory-bank-cli`](https://github.com/dapi/memory-bank-cli). ## Развитие шаблона -### Методические источники +### Методические основания -- [MECE principle](https://en.wikipedia.org/wiki/MECE_principle) — определение принципа Mutually Exclusive, Collectively Exhaustive: непересекающиеся категории, которые вместе покрывают заявленную область; -- Dan North, [*Introducing BDD*](https://dannorth.net/blog/introducing-bdd/) — первичный источник Behaviour-Driven Development: уточнение требований через business value, concrete examples и executable acceptance scenarios в форме `Given / When / Then`; -- Philippe Kruchten, [*Architectural Blueprints — The “4+1” View Model of Software Architecture*](https://arxiv.org/abs/2006.04975) — первичный источник stakeholder-oriented проверки Logical, Process, Development и Physical views через driving scenarios; [краткий обзор](https://en.wikipedia.org/wiki/4%2B1_architectural_view_model); -- Nenad Medvidovic, Richard N. Taylor, [*A Classification and Comparison Framework for Software Architecture Description Languages*](https://ics.uci.edu/~taylor/documents/2000-ADLs-TSE.pdf) — источник архитектурной модели components, connectors и configurations. +- **First Principles Framework (FPF)** — основание для принятия решений от явных фактов, ограничений и проверяемых следствий; +- [принцип MECE](https://en.wikipedia.org/wiki/MECE_principle) — непересекающиеся категории, которые вместе покрывают заявленную область; +- Dan North, [*Introducing BDD*](https://dannorth.net/blog/introducing-bdd/) — первичный источник разработки через поведение: уточнение требований через ценность для бизнеса, конкретные примеры и исполняемые сценарии приёмки в форме `Given / When / Then`; +- Philippe Kruchten, [*Architectural Blueprints — The “4+1” View Model of Software Architecture*](https://arxiv.org/abs/2006.04975) — первичный источник проверки архитектуры через логическое представление, процессы, разработку и физическое размещение, связанные ключевыми сценариями; [краткий обзор](https://en.wikipedia.org/wiki/4%2B1_architectural_view_model); +- Nenad Medvidovic, Richard N. Taylor, [*A Classification and Comparison Framework for Software Architecture Description Languages*](https://ics.uci.edu/~taylor/documents/2000-ADLs-TSE.pdf) — источник архитектурной модели компонентов, связей и конфигураций. -### Downstream-репозитории и практические полигоны +### Проекты, в которых развивается практика Эти репозитории используют и адаптируют Memory Bank под конкретные проекты. Опыт их эксплуатации может становиться источником обобщаемых правил для -шаблона, но их project-specific факты остаются в downstream-копиях. +шаблона, но сведения о конкретном проекте остаются в его собственной копии +Memory Bank. - [`dapi/zelma`](https://github.com/dapi/zelma); - [`brandymint/merchantly`](https://github.com/brandymint/merchantly); - [`alfagen/mercury`](https://github.com/alfagen/mercury). -Добавляйте в шаблон только обобщаемые правила. Названия продуктов, инфраструктурные детали и другие project-specific факты должны оставаться в downstream-копии `memory-bank/`. +Добавляйте в шаблон только обобщаемые правила. Названия продуктов, +инфраструктурные подробности и другие сведения о конкретном проекте должны +оставаться в его собственной копии `memory-bank/`.