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

Пошаговая инструкция и промпты для агента 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-файлов», а поддерживает операционную память проекта и делает документирование частью цикла изменения кода.

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

Шаг 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 и «Контроль изменений»

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

Проверить git status и список изменённых файлов.
Убедиться, что агент не внёс неожиданных правок в код.
Сформировать commit message.
Обновить в 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.

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

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

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

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

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

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

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

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

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

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

2) Memory Bank

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

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

Резюме

Articles