Живая документация проекта через VS Code + Codex + Memory Bank

Пошаговая инструкция и промпты для агента OpenAI Codex — создаем актуальную документацию проекта. А заодно упрощаем для продакт-менеджеров постановку задач программистам.

Для кого эта методология

Материал рассчитан на опытных разработчиков, тимлидов и продакт-менеджеров, которым важно:

• держать документацию всегда актуальной и привязанной к коду;

• снизить зависимость от внешних вики/доков, которые быстро устаревают;

• выстроить «операционную систему» проекта для человека и AI-агента;

• получать воспроизводимые результаты: от первичного ресёрча репозитория до плана реализации фич.

Проблема: «документация умирает»

Классические каналы (Confluence/Outline/Google Docs) часто деградируют по одной причине: у документации нет естественного механизма синхронизации с кодом. Вопрос «кто обновляет, когда обновляет, что считать правдой» остаётся без ответа. В итоге появляется разрыв:

• код меняется ежедневно;

• документация обновляется эпизодически;

• команда теряет время на повторное «раскапывание» проекта.

Решение: сдвинуть documentation-as-code в репозиторий и автоматизировать её построение/обновление через AI-агента, который читает код и работает с файлами напрямую.

Ключевая идея подхода

1.Источник правды — Git-репозиторий.

2.Документация живёт рядом с кодом (Markdown-файлы), хранится и версионируется в Git.

3.Агент Codex понимает кодовую базу и может:

• исследовать структуру,

• создавать/обновлять файлы документации,

• собирать техконтекст, паттерны и спецификации,

• выдавать планы работ, опираясь на документацию.

4.Чтобы агент работал предсказуемо, ему задаётся управляющая инструкция (policy) и устойчивый контекст проекта через Memory Bank.

Практическая архитектура документации

В этой методологии есть два слоя:

• Архитектурный якорь проекта — local/README.md (единый источник архитектуры).

• Устойчивый контекст и операционная память — /.memory_bank/*.

Документация «для людей» и «для агента» — это не взаимоисключающие вещи. На практике, эти документы помогают и команде, и агенту.

Стартовая инструкция для агента

Ниже — стартовая инструкция, которую рекомендуется положить в agents.md в корне репозитория (или применить в виде обязательного регламента для агента). Эта инструкция задаёт правила работы с документацией и Memory Bank.

## Документация и обмен знаниями - `local/README.md` — единственный источник информации об архитектуре. Синхронизируй соответствующие разделы после изменений архитектуры, маршрутов или модулей и укажи правки в PR. - Память проекта: * Перед началом работы перечитай `/.memory_bank/productContext.md`. * Отмечай текущие задачи, последние изменения и следующие шаги в `.memory_bank/activeContext.md`. * Логируй статус, известные проблемы и развитие решений в `.memory_bank/progress.md`. Раздел «Контроль изменений» всегда должен содержать хеш/дату последнего проверенного коммита. * После появления новых коммитов сравни с `git log <last_checked_commit>..`. Если затрагиваешь документацию или регламенты (например, AGENTS, Memory Bank), обнови их и запиши новый «последний проверенный» коммит. * Фиксируй знания для конкретных модулей в `.memory_bank/modules/`, детали UI — в `.memory_bank/ui_extension/`, прочие артефакты — в `.memory_bank/other/`. - Обновления CI/CD (особенно `.gitlab-ci.yml`) отражай и в `techContext.md`, и в `systemPatterns.md`. - При изменении API-контрактов, модулей или SDK-пакетов уведомляй команду ассистента. # Память проекта (Memory Bank) ## Зачем нужна Memory Bank Ты действуешь как инженер без долгосрочной памяти: `/.memory_bank` — единственный устойчивый контекст. Каждый раз перед работой перечитывай содержимое, чтобы сохранять преемственность и эффективность. ## Структура Memory Bank Bank состоит из Markdown-файлов, организованных в иерархию: ## Технические задания (ТЗ) - При добавлении нового функционала обязательно составляй отдельное ТЗ, описывающее цели, сценарии использования, ограничения и формат данных. - Храни ТЗ в отдельном файле в документации (например, в `docs/` или соответствующем разделе `.memory_bank/`), с понятным именем, привязанным к задаче или модулю. - В описании нового функционала в основной документации (например, в `local/README.md`, `techContext.md`, `systemPatterns.md` или модульной документации) обязательно указывай явную ссылку на файл ТЗ. - При доработке существующего функционала обновляй либо исходное ТЗ, либо добавляй новое (связав их между собой в документации), чтобы история решений была прослеживаемой. projectbrief.md → productContext.md → activeContext.md ↓ ↑ systemPatterns.md techContext.md \ / → progress.md ### Основные файлы (обязательно) 1. `projectbrief.md` — фундаментальный документ, задающий цели и рамки. 2. `productContext.md` — зачем нужен проект, какие проблемы решает, чего хочет пользователь. 3. `activeContext.md` — текущее направление, решения, приоритеты и текущие задачи. 4. `systemPatterns.md` — архитектура, ключевые технические решения и важные траектории реализации. 5. `techContext.md` — стек, окружение, ограничения и практики инструментов. 6. `progress.md` — что работает, что осталось, известные проблемы и эволюция решений. ### Дополнительный контекст Создавай дополнительные файлы или подпапки в `.memory_bank/`, если нужно задокументировать: сложные фичи, спецификации интеграций, API, тестовые стратегии, деплой. ## Основные рабочие режимы ### Планирование задачи Перед тем как начать работу по задаче: 1. Сформируй пошаговый план реализации (каждый шаг и результат). 2. Отправь план на утверждение и не приступай к выполнению, пока он не будет одобрен. 3. После утверждения выполняй работу последовательно, отмечая завершение каждого шага и подтверждая готовность перехода к следующему. ### Планирование 1. Читай Memory Bank. 2. Проверяй, заполнены ли файлы. * Если нет → сформируй план и опиши его в чате. * Если да → уточни контекст → разработай стратегию → представь подход. ### Действия 1. Изучи Memory Bank. 2. Обнови документацию, если контекст изменился. 3. Выполни задачу. 4. Задокументируй результат в чате. ## Обновление документации Перезаписывай Memory Bank когда: 1. Находишь новые шаблоны или знания. 2. Внедряешь значимые изменения. 3. Получаешь запрос **update memory bank** (в этом случае перечитывай все файлы). 4. Контекст стал неясным. Процесс: 1. Перечитай каждый файл Memory Bank. 2. Опиши текущее состояние. 3. Определи следующие шаги. 4. Зафиксируй инсайты и паттерны. Если тебя попросили обновить Memory Bank, обязательно прочитай все файлы, особенно `activeContext.md` и `progress.md` — они отражают актуальное состояние.

Что меняется в методологии после внедрения этой инструкции

Исходный подход из видео (VS Code + Codex + документация в Git) становится жёстко регламентированным:

• local/README.md объявляется архитектурным «single source of truth».

• .memory_bank/* становится устойчивым контекстом, который агент обязан перечитывать и обновлять.

• Появляется формальный «контроль изменений» через хеш/дату последнего проверенного коммита.

• Документация и регламенты превращаются в часть процесса разработки (PR-правки, синхронизация, уведомления).

Практически это означает: агент больше не просто «генерирует набор markdown-файлов», а поддерживает операционную память проекта и делает документирование частью цикла изменения кода.

Рекомендуемая структура репозитория для документации

1) Архитектурный якорь

• local/README.md — обзор архитектуры, ключевые подсистемы, маршруты, модули, интеграции.

Рекомендация: держать этот файл компактным и «управляемым по объёму», а углублённые детали выносить в .memory_bank/modules/* и .memory_bank/other/*.

2) Memory Bank

Минимальный набор:

• /.memory_bank/projectbrief.md

• /.memory_bank/productContext.md

• /.memory_bank/activeContext.md

• /.memory_bank/systemPatterns.md

• /.memory_bank/techContext.md

• /.memory_bank/progress.md

Дополнительно:

• /.memory_bank/modules/* — знания по модулям (границы, зависимости, публичные API, точки расширения).

• /.memory_bank/ui_extension/* — UI-детали, страницы, компоненты, UX-паттерны.

• /.memory_bank/other/* — протоколы интеграций, ADR-заметки, окружения, сценарии.

Пошаговый процесс: от нуля до «живой» документации

Шаг 0. Безопасная зона: отдельная ветка

Ключевой принцип из видео сохраняется: документацию делаем в отдельной ветке (docs/*), чтобы не влиять на прод.

Пример:

• создаём ветку docs/init от master;

• работаем в ней;

• открываем PR (MR) и фиксируем изменения.

Шаг 1. Создать/обновить agents.md

Задача агенту:

Создай файл `agents.md` в корне репозитория (если его нет). Вставь в него стартовую инструкцию по документации и Memory Bank дословно. Ничего не меняй в содержании инструкции. После этого кратко перечисли, какие файлы Memory Bank должны быть в проекте, и где они расположены.

Шаг 2. Инициализировать .memory_bank/*

Если Memory Bank отсутствует или пустой — сначала создаём «скелет».

Пример инструкции агенту:

Проверь, существует ли папка `/.memory_bank`. Если нет — создай. Проверь наличие обязательных файлов: projectbrief.md, productContext.md, activeContext.md, systemPatterns.md, techContext.md, progress.md. Если каких-то файлов нет — создай их с базовой структурой заголовков (без фантазий про проект): - вставь шаблонные секции, - оставь пометки TODO, - в progress.md создай раздел «Контроль изменений» и укажи текущий HEAD-коммит (hash) как last_checked_commit. После создания — напиши в ответе список созданных файлов и кратко, что в каждом будет фиксироваться.

Шаг 3. Первичный ресёрч репозитория (с ограничением контекста)

Здесь важно учесть ограничение контекстного окна: даже большой контекст не гарантирует, что модель удержит весь проект. Поэтому работаем итеративно.

Пример инструкции:

Сначала составь карту проекта (без детализации): - основные директории, - ключевые runtime-точки входа, - где лежит публичная часть, - где компоненты/шаблоны, - где CI/CD и инфраструктура. Результат запиши в `/.memory_bank/techContext.md` (раздел «Структура репозитория») и в `/.memory_bank/systemPatterns.md` (раздел «Границы подсистем»). Не описывай детали кода. Только карта.

Шаг 4. Архитектура как single source: local/README.md

По инструкции: это единственный источник архитектуры. Значит, агент должен синхронизировать туда архитектурные изменения.

Пример запроса:

Открой `local/README.md`. Если его нет — создай. На основе карты проекта из Memory Bank добавь в README: - обзор подсистем, - маршруты/страницы верхнего уровня (если применимо), - список ключевых модулей, - связи между ними. Важно: не выдумывать то, чего нет в репозитории. Если информации недостаточно, отметь TODO и напиши, какие файлы/настройки нужно проверить (например, админка Bitrix).

Шаг 5. Документирование страниц и UI-расширений

Эта часть из видео логически переносится в .memory_bank/ui_extension/*.

Пример:

Найди публичные страницы проекта. Создай в `/.memory_bank/ui_extension/pages/` по одному файлу на страницу. Для каждой страницы: - назначение (бизнес/продукт), - какие компоненты/виджеты используются, - какие входы/выходы данных, - где искать реализацию. Общий индекс страниц добавь в `/.memory_bank/ui_extension/README.md`.

Шаг 6. Компоненты и шаблоны

Разнесение по папкам:

• компоненты: /.memory_bank/modules/ или /.memory_bank/ui_extension/components/ (в зависимости от того, это UI-компоненты или модульные);

• шаблоны: /.memory_bank/ui_extension/templates/.

Пример:

Собери список компонентов, которые используются на страницах. Для каждого создай файл в `/.memory_bank/ui_extension/components/`: - назначение, - точки конфигурации, - параметры, - шаблоны, - зависимости, - где вызывается. Дальше — проверь шаблоны сайта (Bitrix templates). Не делай утверждений про активный шаблон, если это настраивается в админке. В таком случае: - перечисли все найденные шаблоны, - добавь гипотезу/требуемую проверку в админке, - зафиксируй это в progress.md как “известную неопределённость”.

Шаг 7. PHP interface / legacy-код

Смысл из видео сохраняется: сложные непонятные куски — в явную документацию.

Пример:

Проанализируй `php_interface` (или аналогичную область кастомизации). Создай файл `/.memory_bank/other/php_interface.md`: - какие файлы есть, - какие хуки/события подписаны, - какие «опасные» функции (например, блокировки по IP), - риски и рекомендации по рефакторингу. Если находишь “остатки прошлого”, помечай как candidate-for-cleanup и добавляй в progress.md.

Шаг 8. CI/CD и инфраструктура

Встроенное требование: обновления .gitlab-ci.yml отражать в techContext.md и systemPatterns.md.

Пример:

Изучи `.gitlab-ci.yml` и другие CI/CD файлы. Обнови: - `/.memory_bank/techContext.md` (раздел «CI/CD и окружения»), - `/.memory_bank/systemPatterns.md` (раздел «Пайплайны и гарантии доставки»). Зафиксируй в progress.md, что CI/CD проверен, и обнови last_checked_commit.

Шаг 9. Коммит/PR и «Контроль изменений»

После генерации и правок:

1. Проверить git status и список изменённых файлов.

2. Убедиться, что агент не внёс неожиданных правок в код.

3. Сформировать commit message.

4. Обновить в progress.md:

• last_checked_commit (hash/дата),

• короткое резюме изменений.

Пример команды агенту:

Сформируй: 1) список файлов, которые изменены, 2) краткое описание, зачем каждое изменение, 3) предложение commit message. Затем обнови `/.memory_bank/progress.md`: - добавь пункт в changelog, - обнови раздел «Контроль изменений» новым last_checked_commit (после коммита укажи hash).

Как использовать документацию для постановки задач (для PM и лидов)

Норматив: «сначала план, потом работа»

Инструкция прямо требует:

• сформировать пошаговый план;

• отправить на утверждение;

• только после утверждения выполнять.

Практический шаблон запроса:

Нужно добавить функциональность <X>. 1) Прочитай `/.memory_bank/productContext.md` и `activeContext.md`. 2) Найди релевантные разделы в `.memory_bank/modules/` и `.memory_bank/ui_extension/`. 3) Составь пошаговый план реализации: - шаг, - ожидаемый результат, - файлы/модули, которые будут затронуты, - риски/неопределённости. Не реализуй ничего. Только план.

Когда план утверждён

План утверждён. Выполняй шаг 1. После выполнения: - опиши, что сделано, - укажи изменённые файлы, - обнови `.memory_bank/activeContext.md` и `.memory_bank/progress.md`.

Антипаттерны и как их предотвращать

1) «Агент создал не там»

Причина: не указан целевой путь (или смешаны понятия docs/memory bank).

Решение: указывать явные директории (/.memory_bank/ui_extension/...).

2) «Агент выбрал активный шаблон без доказательств»

Причина: активность шаблона задаётся в админке (не в коде).

Решение: документировать как гипотезу + чек в админке + запись в progress.md как неопределённость.

3) «Длинные задачи — потеря контекста»

Решение:

• дробить на этапы,

• каждый этап фиксировать в Memory Bank,

• обновлять last_checked_commit.

4) «Документация не обновляется при изменениях»

Решение: встроить регламент в PR:

• если меняется архитектура/маршруты/модули — синхронизировать local/README.md.

• если меняются CI/CD — обновлять techContext.md и systemPatterns.md.

Резюме

Методология из видео становится существенно сильнее, если:

• закрепить local/README.md как единственный источник архитектуры;

• использовать .memory_bank как устойчивый контекст (для людей и агента);

• фиксировать «контроль изменений» через хеш последнего проверенного коммита;

• работать итеративно и пошагово: карта → страницы → компоненты → шаблоны → кастомизация → CI/CD;

• стандартизировать промпты: план → утверждение → выполнение → фиксация в Memory Bank.

В результате документация перестаёт быть «отдельным артефактом», а становится частью системы разработки: воспроизводимой, проверяемой, привязанной к коду и пригодной для автоматизации.