memory_bank_setup

Шаблон документации для опенсорс-проекта, который делают один-четыре человека с AI-агентами.

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

Развернуть в своём проекте: QUICKSTART.md.

Четыре режима

Режим	Где	Отвечает на	Как обновляется
Состояние	docs/	как устроено сейчас	переписывается на месте
Требование	specs/active/	что функция должна делать	замораживается
История	specs/archive/, docs/adr/	как было и почему так решили	не правится
Процесс	.work/	что делается прямо сейчас	удаляется после слияния

Каждый файл принадлежит ровно одному режиму. Это главное правило шаблона.

Размеры memory bank

Размер задаётся YAML-файлом в memory_bank/sizes/. Полный физический скелет будущего проекта лежит в memory_bank/project_templates/.

Размер	Когда использовать	Что внутри
minimal	маленький проект или библиотека	AGENTS, базовые docs, specs, .work
medium	рекомендуемый default	продукт, архитектура, инженерные правила, операции, specs, .work
maximum	зрелый проект	почти весь текущий каркас, сайт, CI и правила ведения документации

YAML содержит список файлов, исходные шаблоны и подсказки для агента. Скрипт развёртывания не знает структуру заранее: он читает выбранный YAML.

Структура

.
├── AGENTS.md            роутер для агентов: команды, правила, маршруты
├── CLAUDE.md            специфика Claude Code, импортирует AGENTS.md
├── QUICKSTART.md        как развернуть шаблон
├── justfile             единственная точка входа для всех команд
│
├── memory_bank/
│   ├── sizes/           состав minimal, medium и maximum
│   ├── stacks/          необязательные подсказки по стеку
│   └── project_templates/ полный физический скелет memory bank
├── docs_scripts/        bootstrap, линтеры, setup и optional site tooling
├── .github/workflows/   optional GitHub CI
└── .gitlab-ci.yml       optional GitLab CI

Команды

Всё через just.

just docs-setup-core       # Python core в .venv, без Node/npm
just docs-init medium      # развернуть выбранный размер
just docs-check            # базовая проверка memory bank
just docs-fix              # пересобрать индексы и доску работ
just docs-hooks-install    # установить .githooks через core.hooksPath
just docs-setup-site       # optional: MkDocs, markdownlint, Mermaid
just docs-check-site       # optional: сайт, Markdown и Mermaid

just check остаётся проектным агрегатором и сейчас вызывает just docs-check.

.work и state.yaml

Папка изменения остаётся в текущей модели .work/todo, .work/in-progress, .work/done.

Внутри изменения:

CHG-012-name/
├── plan.md
├── state.yaml
├── tasks/                  optional
│   ├── todo/
│   ├── in-progress/
│   └── done/
└── artifacts/              optional, только реальные файлы

Статус изменения и задачи задаёт их папка. Фактический прогресс, доказательства и замечания ревью хранятся в state.yaml.

Что держит конструкцию

Не хранить то, что выводится. Статус задаёт файловая зона, а доска работ генерируется. Дублирующее поле разъезжается с источником.

Генерируемые блоки. Таблицы содержимого и доска работ собираются через just docs-fix.

Базовый слой без npm. Core memory bank требует Python и just. Node/npm нужны только для optional site layer.

Шаблон ничего не навязывает. YAML-подсказки стеков лежат в memory_bank/stacks/, но проект выбирает свои реальные команды и инструменты.

Лицензия

MIT, см. LICENSE.