🧩 Memory bank для существующих проектов :: Реверс-проектирование и реверс-документирование в brownfield
2/2

(.. начало тут: https://t.me/deksden_notes/66)

Немного практики:

🔵 Нет смысла документировать очевидные из кода вещи: агент может прочитать и воспринять что написано в коде. Делать дублирование логики функций в документации особенной ценности не имеет и будет забивать контекст - агент будет читать и документацию, и код.

🔵 полезно вносить в мемори банк то, для сбора чего агенту нужно совершить несколько действий. Например: схему взаимодействия между модулями (кто кого и откуда вызывает), контракты подсистем, публичное api модулей, примеры и паттерны их использования

🔵 Отличную почву для дополнения меморибанков дают ошибки агента - когда он сделал что-то "не то". Это верный знак необходимости рефакторинга документации: отсутствие правильного контекста, или его качеством. Проверим что у агента документация была: индексные файлы, duo файлы. Проверяем - опирался ли агент на корректную документацию? противоречий или ошибок в документации не было? важные вещи документированы?

🔵 Используем агентов:
- собраем полную карту апи-роутов сервера;
- исследовать и документировать схему из БД и связанных файлов кода, "вытаскиваем" максимум мета-информации;
- описать существующий UI: перечень экранов, их структурных элементов; data test id атрибуты для тестирования; идентифицировать основные actions в интерфейсе;
- call graph: агент может составить схему взаимодействия модулей - какие функции/методы вызывают другие модули/функции; конечно, специализированные системы (типа qoder) сделают это лучше, но и простыми способами зафиксировать "соседние ветки" дерева зависимостей несложно и весьма полезно.

🔵 Самое сложное - это вытащить нормальную структуру фич из кода. Тут может помочь фиксация типовых сценариев использования системы - как пользователи с ней работают. Элементы системы, которые участвуют в сценарии и могут стать отправными точками для фич. Пример: "Пользователь входит в систему: на экране логина он вводит имя пользователя и пароль. Система валидирует пароль и загружает главный экран с доступными пользвоателю разделами." (фича аутентификации, фича авторизации).

🔵 Используйте методологии CRUD анализа: еси в системе зафиксирована работа с некоей сущностью "заказ" - типа, "пользователь создал заказ", то для сущности "заказ" должны быть описаны все CRUD методы: как создавать, просматривать, менять и удалять такие сущности (бывает, что удаление часто выпадает при документирвовании).

🔵 Используйте методики Use Case Analysis: сценарии часто описывают только "happy path". Но что будет если пользователь ввёл неправильный пароль? 10 раз подряд? если при регистрации пользователь с таким паролем уже существует? Если api станет недоступно посередине регистрации? Такие сценарии называются "exception flows" и "alternative paths".

🔵 Анализ Перехода Состояний (State Transition Analysis) : если в системе есть сущности с состоянием, надо разобраться со схемой переходов состояний. Составляем агентами список состояний и карту возможных переходов между ними, и смотрим - документировали ли мы все, что касается доступных переходов. Как именно заказ из состояния on-hold переводится обратно в processing. Документировали ли мы как заказ из "paid" становится "shipped"? Такая карта здорово помогает найти пробелы в документировании.

🔵 В целом - практики "классического" "enterprise" моделирования процессов, проектирования, бизнес-инжиниринга будут работать на пользу процессу и тут - ведь мы решаем похожие задачи: если раньше эти практики использовались чтобы люди понимали как работает система в бизнесе, то теперь у нас даже более практичное применения - мы должны растолковать все то же самое ИИ агентам!

Надеюсь, дал какие то намётки подхода! И помните - задача творческая, жёстких методик пока не сформировано, все познается на практике.

🙇‍♂️ Пробуем, анализируем, делимся, улучшаем!


␄
#post
@deksden_notes