Методология SAMO: архитектура репозитория под параллельную разработку десятками ИИ-агентов

За последние два года разработка программного обеспечения претерпела фундаментальное изменение: написание синтаксиса всё чаще поручается языковым моделям. Автономные агенты генерируют компоненты, пишут тесты и выполняют рефакторинг. Однако ускорение генерации кода вскрыло архитектурный парадокс: чем больше свободы предоставляется модели в традиционной кодовой базе, тем быстрее проект погружается в хаос.

Классический репозиторий спроектирован для человека. Разработчик вправе сам выбрать имя файла, расположить утилиту в произвольной папке или добавить промежуточный слой абстракции. Для человека эта гибкость естественна, но для ИИ-агента она оборачивается пространством ошибок: модель плодит утилиты-дубликаты, теряет контекст и способна непреднамеренно стереть критические ветки проекта.

Ответом на этот вызов стала экспериментальная методология SAMO, предложенная в исследовательском разборе на Хабре инженером Дмитрием Паваренкиным на основе опыта одновременной оркестрации десятков моделей над единым проектом. Центральный тезис подхода прост: надежность ИИ-разработки определяется не столько сообразительностью модели, сколько архитектурными ограничениями среды, в которой она работает.

Предел возможностей AGENTS.md и текстовых промптов

Большинство команд пытаются управлять агентами через файлы инструкций — системные промпты, конфигурации правил или файл AGENTS.md в корне репозитория. В них естественным языком описываются соглашения: стек, структура каталогов и запреты.

На практике этот подход регулярно сбоит. Языковая модель оперирует вероятностями, а не абсолютными законами. По мере роста контекста и усложнения задач инструкции из промпта начинают вымываться (эффект «Lost in the Middle»). Текстовое правило не обладает принудительной силой: если модель решит сохранить вспомогательный класс в корне проекта, текстовый манифест физически не помешает созданию файла.

SAMO предлагает перенести правила из пассивных инструкций в исполняемые ограничения. Если соглашение критично, его должен контролировать программный код: линтер, архитектурный аудитор, проверка структуры в CI или конечный автомат (FSM), определяющий фазы решения задачи. Нарушая правило, агент получает не напоминание, а блокирующую ошибку сборочной системы.

Четыре опоры концепции SAMO

Аббревиатура SAMO объединяет четыре известных инженерных подхода:

1. SOLID — классические принципы проектирования, требующие четкого разделения ответственности модулей и понятных интерфейсов.
2. Atomic Design (атомарный дизайн) — иерархическая структура интерфейсов, делящая компоненты на атомы, молекулы, организмы, шаблоны и страницы.
3. Morphological Box (морфологический ящик) — метод системного анализа, раскладывающий объект на фиксированные параметры и допустимые значения. В структуре репозитория он определяет строго разрешенные комбинации папок и файлов.
4. Orchestration (оркестрация) — координация параллельной работы независимых моделей с распределением задач по предметным областям.

SAMO не является официальным стандартом или готовым фреймворком. Это авторская методика: SOLID здесь не диктует пути каталогов, а изолирует модули; атомарный дизайн применяется к интерфейсам; а морфологический ящик задает разрешенную матрицу файловой системы.

Пятиуровневая адресация файлов

Вместо произвольного размещения сущностей SAMO вводит детерминированный адрес:

<domain>/<cluster>/<joint>/<family>/<file>

Каждый сегмент пути решает свою задачу:

• domain (домен): бизнес-область (billing, auth, profile, theme).
• cluster (кластер): базовая категория языка (в TypeScript-проектах автора используются зарезервированные слова: const, type, interface, class, function, component, data).
• joint (сочленение): структурный уровень. Для компонентов это уровни атомарного дизайна (atom, molecule, organism).
• family (семейство): конкретное имя сущности (avatar, button).
• file (файл): строго фиксированный состав допустимых файлов.

Например, путь к атому аватара выглядит так: profile/component/atom/avatar/

В этой директории разрешены только заранее оговоренные файлы:

• index.ts — точка входа и реэкспорт;
• index.svelte — разметка компонента (в проекте автора полигоном выступает библиотека stylist-svelte на Svelte 5);
• index.story.svelte — сценарий для витрины компонентов;
• state.svelte.ts — локальное реактивное состояние;
• test.svelte.ts — модульные тесты.

Появление файлов вроде AvatarHelper.ts или avatarUtils.ts запрещено проверками. Агент вычисляет адрес по жесткому алгоритму и сразу знает допустимые имена файлов, что превращает файловую систему в подобие статической системы типов.

Параллельная работа и статистика моделей

Главная ценность жесткой адресации проявляется при одновременной работе нескольких моделей. Агенты распределяются строго по границам domain: агент, работающий над профилем, физически не затрагивает платежи. Поиск файлов не требует сканирования всего репозитория, экономя токены. Сквозные изменения, затрагивающие несколько доменов, запрещено поручать локальным агентам — их координирует человек или центральный процесс.

В ходе экспериментов с библиотекой stylist-svelte автор зафиксировал статистику непреднамеренного удаления файлов:

• Специализированный автономный агент кодогенерации: 0 инцидентов, 0 удаленных файлов.
• Claude Code: 1 инцидент, 555 случайно стертых файлов.
• Qwen Code: 3 инцидента, около 3 000 удаленных файлов.
• Крупная мультимодальная модель: 8 инцидентов, более 10 000 удаленных файлов (при высокой полезности в роли системного аналитика и скрам-мастера).

Важное предостережение: эти данные не являются стандартизированным бенчмарком. Модели решали разные задачи в разных контекстах, и эти цифры нельзя считать универсальным рейтингом. Они лишь доказывают: чем выше автономность моделей, тем опаснее операции с файловой системой и тем строже должны быть внешние инфраструктурные барьеры.

Практический пилот: внедрение без готовых библиотек

Поскольку для SAMO нет официального пакета, CLI или репозитория, безопасный путь внедрения — постепенный локальный пилот в одном домене:

1. Выбор домена и фиксация правил: команда выбирает обособленный модуль (например, UI-компоненты) и фиксирует в архитектурном соглашении (ADR) разрешенные списки cluster, joint и допустимые имена файлов.
2. Создание аудитора: пишется компактный скрипт на Node.js или Bash, проверяющий пути файлов на соответствие манифесту.
3. Запуск в режиме отчета: проверка встраивается в CI, но не блокирует сборку, собирая список существующих отклонений.
4. Утверждение исключений: фиксируется список legacy-путей и план их устранения, после чего проверка в CI переводится в блокирующий режим.
5. Ограничение агентских задач: при постановке задачи агенту явно задаются разрешенный домен и перечень файлов, а любые отклонения блокируются сборочным конвейром.

Компромиссы и ограничения

Методология не лишена недостатков. Пятиуровневая структура громоздка для человека и создает лишнюю бюрократию в небольших проектах или стартапах, где предметная область еще не устоялась.

Кроме того, файловые ограничения не заменяют системную песочницу: они не защищают от утечек токенов или выполнения опасных терминальных команд.

Роль инженера при таком подходе меняется: разработчик перестает быть просто автором синтаксиса и становится архитектором среды исполнения, определяющим границы дозволенного для искусственного интеллекта.