XDLC в деле #2. Первые падения и новые взлеты
Карта из первого поста оказалась мертвой. Ниже вскрытие и что родилось на ее месте.
Задача:
Машинная карта module-map.md провалилась на всех трех полигонах: legacy, PlayBiz, SmartBiz. Ждали навигации и экономии токенов - получили огромные “копии” структуры и дорогие запросы.
Обнаружение: Провал вскрылся на legacy: сканер выгружает структуру, SWE вычитает - в карту ложатся тысячи строк. Агент обязан читать карту перед каждой задачей - формально все правильно. По факту: сожженная квота, пользы почти ноль.
Второй слой тоньше: формальные записи не несут смысла. Агент знает, что в файле А - файл “за то-то”, но это не делает карту картой. Юнит определяется ролью и механизмом, а не путями и “ответственностью” по именам файлов (“смысловые названия” тоже не спасли).
Что родилось:
1. project-map.yaml вместо md. Markdown позволял структуре “плыть”; YAML строгий, машинно-читаемый, парсится без промахов. (спасибо @Виктор Шамов за наводку и Владимиру Иванову за GRACE). Но XML и JSON мы отклонили: плохо читаются инженерами.
2. Semantic Units вместо модулей. “Модуль” - термин, занятый инженерами web-стека, порождал путаницу. Имена юнитов теперь смысловые: content-files, content-block etc.
3. Закрытый мир. Агент работает только с описанными SWE частями проекта; остальное для него не существует - не “запрещено”, а отсутствует. Для крупного legacy это единственная масштабируемая оптика.
4. Запретить средой. Агент обходит любые правила и читает запреты как рекомендации без легитимных альтернатив. Предугадать все обходы невозможно - запрет должен быть физическим: границы файлов в WO, права пользователя, git ветки.
Результат:
В ядре: карта в YAML, закрытый мир в глоссарии, база знаний .xdlc/kb/ и паспорта юнитов (это уже не просто спеки, а спеки задач + спека проекта, но из-за “сберовской” путаницы мы выбрали “базу знаний”). Агент не угадывает - читает паспорта и карту.
Мелочь стала требованием. Например: список записей в TS-файле отображается в порядке массива: “добавить запись” = “запись вверху списка”. Вставка в конец - файл валиден, acceptance выполнен, а по факту запись внизу страницы при рендере. Гипотеза провалена при “чистом” агенте. Позиция записи - проверяемое требование в SPEC, а не в запретах WO.
Инженерные детали:
Анатомия юнита: id, name, desc (назначение и границы вне путей), elements (пути и паттерны), links (направленные связи). Паспорт есть не у всех юнитов - норма.
Паттерны путей - семантика именованных групп PCRE. Подошел под паттерн - файл описан: можно читать и править (если позволяет WO).
Закрытый мир механический: путь вне паттернов закрыт - не читать, не изменять, даже если лежит рядом. Нужно больше - карту расширяет SWE до начала WO, иначе агент останавливается. Разрезы не всегда ложатся на пути. Например два юнита накрывают один src/components/*: block-renderers (реализации блоков) и inline-embeddable (сущности для inline вставок). Граница - по реестру юнита block-catalog: есть в реестре - блок, нет - inline-сущность. Разрез правилом фиксируется в паспортах обоих юнитов.
Паспорт - .xdlc/kb/units/<unit-id>.md, секции: Назначение, Правила, Контракты. Карта несет структуру и границы, паспорт - инварианты, невидимые из кода. Примеры: beehive-list - “новые записи идут в начало массива”; block-catalog - “реестр - единственный признак применимости блока”.
Шаблоны карты и паспортов намеренно не даем - до open-source версии. Опытный инженер напишет свои под свою среду.
Штурмы. AI-Disrupt PDLC зовет AI равноправным участником штурма. Ощутили на своей шкуре: по уровню знаний сильная модель не просто равноправна - со скиллами типа BE-AMBITIOUS.md (привет, Бен) она становится super-базой знаний. Оговорка: не антропоморфизируйте машину (с AI “наравне”): проверяйте-проверяйте-и-еще-раз-проверяйте (с).
Следующий пост - прогон связки на реальных задачах: агенты по карте и паспортам, уровень R3+.
Вопрос аудитории: Как ограждаете агентов от чужих зон проекта - промптами, правами или надеждой? 😀 Если промптами - как часто агент их обходил? 😉
