# Architecture Decision Record: Маркетплейс готовых ИИ-агентов > **Дата:** 2026-08-26 | **Статус:** Proposed | **Решение:** Простая архитектура MVP > **Ревизия 27.08.2026:** Обновлено на основе `product/00-research-evidence-base.md` (27.08.2026, ~70 источников, ~60 карточек T1/T2, confidence M–H). Добавлены ADR-5 (One-command installer, урок 2.1.243) и ADR-6 (Guardrails). Исходные ADR-1–ADR-4 сохранены без изменения логики, но получили привязку к доказательной базе. --- ## Ревизия 27.08.2026 — что изменилось и почему **Источник:** Консолидированная доказательная база `product/00-research-evidence-base.md`. До 27.08 вся документация опиралась на T5/T6 (бриф + логика). Теперь ядро гипотез — T1/T2. **Ключевой сдвиг в понимании продукта:** | Было (до 27.08) | Стало (после Discovery) | Находки | |---|---|---| | Продаём ZIP-архив с инструкцией | Продаём **Agent Kit**: пакет + one-command installer + doctor + guardrails + адаптация + обновления. ZIP — лишь транспорт | Находки 3, 9 — синтез §4 базы; Находка 6 | | Установка — «скачал и разобрался» | Установка — барьер №1, но преодолим с installer+doctor+поддержкой. Метрика — `time-to-first-successful-task` | Находка 3 (H,T1) | | «Чистый ZIP навсегда» | Статика гниёт: нужен пин версий, канал обновлений и rollback | Находка 9 (H,T1/T2) | | Безопасность — в промпте | Безопасность — hard-limits в коде транспорта, dry-run, лимиты | Находка 5 (H,T1/T2) | | Ценность — «роль AI-сотрудника» | Ценность — закрытый цикл конкретной задачи (JTBD) | Находка 6 (H,T1) | **Вердикт Discovery для архитектуры:** гипотеза *«готовый ZIP поставят сами»* переписана в *«установят после guided setup с минимальной поддержкой»* (§5 базы). Это требует двух новых архитектурных решений — ADR-5 и ADR-6. > Урок ZIP 2.1.243 (SIGSEGV, autoupdate без отката) учтён как отдельный инвариант: никакого тихого autoupdate `latest` без пина и отката. --- ## ADR-01: Технологический стек для сайта **Контекст:** MVP должен быть создан одним разработчиком за 80–90 часов. Нужен простой, поддерживаемый стек с быстрым временем до запуска. **Решение:** Статический сайт (Next.js/Astro или аналогичный SSG/SSG-фреймворк) + headless CMS (Notion/Airtable/JSON-файлы как источник данных) + Telegram Bot API. **Почему не другие варианты:** - Full-stack фреймворк (Django, Rails) — избыточно для сайта-витрины - WordPress — не подходит для каталога агентов с динамическими карточками - SPA без SSR — плохая SEO **Последствия:** - (+) Быстрый запуск; хорошая SEO; простая деплой - (+) CMS можно заменить без изменения кода сайта - (-) Ограниченная интерактивность (нет полноценного SPA) - (-) Фильтры могут потребовать клиентской логики --- ## ADR-02: Telegram Bot как канал доставки **Контекст:** Встроенная оплата отсутствует. Нужен канал для: приёма заявок, уведомлений администратора, подтверждения оплаты, выдачи архивов, поддержки. **Решение:** Telegram Bot API (python-telegram-bot или telebot). Хранение данных — SQLite или JSON-файлы. Деплой — на VPS (Vultr/Hetzner) или Railway. **Почему не другие варианты:** - WhatsApp Business API — дороже; сложнее интеграция - Веб-чат на сайте — не привязан к личному аккаунту; нет push-уведомлений - Email — медленнее; нет мгновенных уведомлений **Последствия:** - (+) Привязка к реальному аккаунту пользователя - (+) Push-уведомления; быстрая коммуникация - (-) Ограничения Telegram Bot API (размер файла, лимиты) - (-) Ручное подтверждение оплаты (handoff) *Уточнение ревизии 27.08:* Находка 10 (M,T1/T2) и кейс Симакова («Агентура» — агент на VPS, Telegram как front-end) показывают, что Telegram потенциально — не только доставка ZIP, но и control plane агента. Для MVP оставляем доставку, но API бота проектируем с запасом под команды `doctor`, `dry-run`, нотификации (задел под ADR-5/ADR-6). --- ## ADR-03: Формат хранения и выдачи архивов **Контекст:** Платные архивы не должны быть по публичным ссылкам. Нужен механизм безопасной выдачи. **Решение:** Архивы хранятся на защищённом хранилище (S3 с Signed URLs или VPS). Бот отправляет архив напрямую в Telegram-чат после подтверждения оплаты. Бесплатные архивы — автоматически. **Последствия:** - (+) Архивы не доступны по публичным ссылкам - (+) Бесплатные выдаются автоматически - (-) Ручное подтверждение оплаты (лямбда 1–24 часа) - (-) Ограничение размера файла в Telegram (50 МБ) *Уточнение ревизии 27.08:* ZIP остаётся fallback-каналом (см. ADR-5). Primary-канал — `npx` с пином версии; S3 хранит версионированные релизы (`stable`/`beta`), а не один `latest.zip`. --- ## ADR-04: Аналитика **Контекст:** Нужно фиксировать основные события воронки для проверки гипотез. **Решение:** Яндекс.Метрика (для сайта) + кастомные события в Telegram-боте (SQLite/JSON). Минимальный набор: catalog_view, package_view, platform_selected, buy_clicked, telegram_started, payment_confirmed, package_delivered, install_success, support_requested. **Последствия:** - (+) Бесплатно; простая интеграция - (+) Достаточно для MVP - (-) Нет когортного анализа (нужно строить вручную) - (-) Данные бота и сайта в разных системах *Уточнение ревизии 27.08:* Добавляются события для новых ADR: `install_started` / `install_failed` / `doctor_passed` / `doctor_failed` (ADR-5) и `guardrail_triggered` / `dry_run_executed` / `readback_confirmed` / `budget_capped` (ADR-6). Ключевая метрика воронки — `paid → first successful business outcome` (Находки 3,6; §7 базы, P0–P1), а не `download`. --- ## ADR-05: One-command installer strategy (npx-first + ZIP fallback, пин версий, stable/beta) **Контекст:** Установка — барьер №1 для ЦА (Находка 3, H,T1). Даже команда Claude Code убирает зависимость от Node.js (PR #37); пользователи «тупят в командную строку, гуглят термины» (Меркушев), ставят только с AI-коучем (QualCoder). При этом 4 независимых кейса не-программистов (Кузнецов, Xcom-shop, Василенко, Савелий) доказывают: **с one-command installer + doctor + поддержкой — ставят**. Вторая проблема — статика гниёт (Находка 9, H): «экосистема Claude Code развивается быстрее, чем один человек обновляет кит» (Масленников, 3000+ ч), миграция моделей ломает сценарии (Polza.ai → DeepSeek V4). Урок **ZIP 2.1.243**: SIGSEGV из-за тихого autoupdate без пина и без отката — клиент получил нерабочий бинарник без возможности вернуться. **Решение:** Двухканальная стратегия установки с жёстким версионированием. 1. **Primary — npx-first:** ```bash npx --yes @smarket/agent-kit@stable install # или для беты: npx --yes @smarket/agent-kit@beta install ``` - `npx` резолвит Node.js (или использует встроенный fallback без требования глобального `npm install -g`). - Тянет **pinned** релиз из реестра (npm + S3 mirror), проверяет checksum/signature. - Запускает `doctor` до любых изменений (см. п.3). 2. **Fallback — ZIP + install.sh/doctor.sh:** - Для офлайна, корпоративных прокси, РФ-ограничений (Находка 11). Выдаётся через Telegram-бота (ADR-02/03) как `agent--.zip` + `install.sh` + `doctor.sh` + `manifest.json`. - Установка — одна команда: `bash install.sh` (без `git clone` / `pip install` в первом шаге). 3. **Пин версий (обязательно):** - `manifest.json` в каждом релизе: `{ agent, transport, model, prompts, checksums }`. Никакого `latest` по умолчанию. - Агент пинит версию транспорта и модели LLM (защита от «гниения» из Находки 9). Смена модели — одной строкой в манифесте + `doctor --migrate`. 4. **Каналы stable / beta:** - `stable` — дефолт, обновляется только после ручного QA прогона (см. ADR-6 dry-run). `beta` — opt-in для ранних пользователей. Переключение: `npx @smarket/agent-kit@stable update` / `...@beta`. - Урок 2.1.243: никакого тихого autoupdate. Обновление — явной командой, с подтверждением и **откатом**: `doctor --rollback` возвращает предыдущую версию с диска (храним N-1). 5. **Doctor-скрипт — гейт готовности:** - Проверяет: Node/Python версия, зависимости, права на `~/.claude/skills/`, токены, сеть/прокси, подпись релиза. - Выдаёт «зелёную галочку: агент готов» или конкретную ошибку с командой-фиксом и ссылкой на Telegram-коуча (Находка 3: «пришли скриншот ошибки — подскажем»). - Метрика успеха — `time-to-first-successful-task`, не «скачал ZIP». **Почему не другие варианты:** - Только ZIP + PDF-инструкция (как у SkillPacks сейчас) — оставляет барьер терминала и не решает гниение; урок 2.1.243 повторяется. - Только `npm install -g` / `pip install` — требует глобальной установки, ломается на правах, несовместим с требованием «никаких глобальных шагов в первом шаге» (§7 базы, P0). - Тихое autoupdate `latest` — даёт SIGSEGV-подобные отказы без возможности отката (провал 2.1.243). **Обоснование через доказательную базу:** - **Находка 3 (H,T1)** — барьер установки и доказанная способность не-программистов ставить с guided setup → требуем one-command + doctor + Telegram-коуч. - **Находка 9 (H,T1/T2)** — статика гниёт, экосистема быстрее человека, поломки при миграции моделей → требуем пин версий + каналы + rollback вместо «раз и навсегда ZIP». - **Находка 6 (H,T1)** — ценность в закрытом цикле конкретной задачи → installer ставит не «роль», а конкретный JTBD-пакет с чек-листом данных (см. ADR-6). - Урок 2.1.243 (SIGSEGV) — эмпирическое подтверждение риска autoupdate без пина. **Последствия:** - (+) Снимает главный барьер покупки; повышает `install_success` и `paid → first outcome`. - (+) Защита от «гниения» и от инцидентов типа 2.1.243; воспроизводимость установок. - (+) ZIP остаётся для РФ-прокси/офлайна, но не единственный путь. - (-) Поддержка двух каналов и версионирования — +20–30% к объёму релиз-инфраструктуры. - (-) npm как зависимость — нужен S3-mirror и fallback-ZIP на случай недоступности реестра (Находка 11). - **NFR:** `install_success ≥80%` среди оплативших; `time-to-first-task <15 мин` с момента `npx`; `rollback <60 сек`. **Связи:** ADR-02/03 (доставка), ADR-04 (события установки), ADR-06 (guardrails проверяются doctor-ом), `00 §7 P0-1` (Agent Kit вместо ZIP). --- ## ADR-06: Guardrails architecture (hard-limits в коде транспорта, dry-run, лимиты бюджета, локальное хранение токенов, readback) **Контекст:** Без guardrails агенты наносят ущерб: 34 штрафа на ~$80k (Business Arena), массовое удаление писем (Саммер Юэ), галлюцинации «тесты проходят» без запуска (Масленников). Ключевой принцип — «запреты должны быть в коде транспорта, а не в промпте» (Волков, anilau); «честный статус неизвестности предпочтительнее догадки» (там же). No-code архитектор: «запишите, что агент НЕ делает, используйте human-in-the-loop». Находка 6 добавляет: ценность — в узком закрытом цикле с понятной границей ответственности, а не в «универсальном сотруднике». Без явных guardrails продажа пакетов с внешними действиями (Яндекс Директ, почта, платежи, CRM) — неприемлемый риск и причина возвратов. **Решение:** Архитектура безопасности на уровне транспорта (кода), а не промпта. 1. **Hard-limits в коде транспорта (не в промпте):** - Каждое внешнее действие (отправка письма, ставка в Директе, запись в CRM, публикация) проходит через `transport` — тонкий исполняемый слой между LLM и API. - Лимиты зашиты в код: allowlist actions, deny-by-default, rate limits, max rows/records per run, max external calls. Промпт может просить, транспорт — не даёт. 2. **Dry-run по умолчанию:** - Первый прогон любого нового пакета — `dry-run`: агент показывает план действий (что изменит/создаст/отправит) без записи. Подтверждение — явной командой или кликом в Telegram. - Для Директа/почты dry-run обязателен; для чтения/аналитики — опционален. 3. **Лимиты бюджета и объёма:** - На уровне транспорта: `max_cost_per_run` (токены × цена), `max_api_calls`, `max_records`, дневной/месячный cap. При превышении — пауза + уведомление в Telegram. - Пишется в карточке товара: «сколько стоит типовой прогон» (Находка 5, trust layer). 4. **Локальное хранение токенов:** - Токены/ключи — только локально: OS keychain или `.env.local` (gitignored), никогда в промпте/репозитории/облаке. Doctor проверяет наличие и права (`0600`). - Инструкция онбординга «Claude Code из РФ» (Находка 11) включает шаг про VPN/оплату, но не требует шарить ключи. 5. **Readback + human-in-the-loop:** - Перед необратимым действием — readback: агент возвращает diff/превью (например, «удалю 12 писем, вот список») и ждёт подтверждения. - Для каждого пакета — карта `что агент НЕ делает` + точки `что подтверждает человек` (карточка товара: «Кому подходит / Не подходит / Что НЕ делает» — Находка 5). 6. **Аудит и наблюдаемость:** - Локальный лог каждого внешнего действия (JSONL) + событие `guardrail_triggered` в аналитику (ADR-04). - `doctor --audit` показывает последние действия и сработавшие лимиты. **Почему не другие варианты:** - Только промпт-инструкции («не удаляй письма») — игнорируются моделью; доказано T1-кейсами (Волков: «запреты в коде транспорта»). - SaaS-прокси с хранением токенов в облаке — неприемлемо для ЦА из-за недоверия и РФ-платёжных барьеров; повышает риск утечки. - Без dry-run / без лимитов — повторяет инциденты $80k штрафов и массового удаления. **Обоснование через доказательную базу:** - **Находка 5 (H,T1/T2)** — killer-фича: без hard-limits продукт небезопасен; цитаты Волкова — прямой источник архитектурного принципа «в коде транспорта». - **Находка 6 (H,T1)** — ценность в закрытом цикле конкретной задачи с границей ответственности → guardrails определяют эту границу и делают обещание проверяемым («из 30 постов собрать план», а не «СММщик Сергей»). - **Находка 3 (H,T1)** — барьер доверия: явные ограничения и dry-run снижают страх «останусь один с ошибкой / агент что-то сломает». - **Находка 9 (H)** — guardrails версионируются вместе с пином транспорта (ADR-5), иначе «гниение» ломает и безопасность. **Последствия:** - (+) Снимает главное возражение к покупке («а вдруг удалит/потратит»); снижает возвраты; становится фичей в карточке («hard-limits, dry-run, локальные токены»). - (+) Делает узкие JTBD-пакеты продаваемыми: каждый пакет — документированный контракт «что делает / не делает / что подтверждает человек». - (-) +30–40% к разработке каждого пакета с внешними действиями (транспорт + тесты на лимиты). - (-) Часть «магии» пропадает — пользователь должен подтвердить readback; но это осознанный trade-off безопасности vs автономности. - **NFR:** 100% внешних действий через транспорт; 0 секретов в репозитории/промпте; dry-run — дефолт для новых установок; любой необратимый action — только после readback. **Связи:** ADR-05 (doctor проверяет токены/лимиты/версию транспорта), ADR-04 (события guardrails), PRD FR/NFR (installer, doctor, карточка с ограничениями), `00 §7 P0-2` (guardrails в коде + карточка «что НЕ делает»). --- ## Связь с доказательной базой и другими документами | ADR | Опирается на | Уровень | |---|---|---| | ADR-05 | Находка 3 (H,T1), Находка 9 (H), Находка 6 (H,T1), урок ZIP 2.1.243 (SIGSEGV) | T1/T2 | | ADR-06 | Находка 5 (H,T1/T2), Находка 6 (H,T1), Находка 3 (H,T1) | T1/T2 | | ADR-02/03/04 (уточнения) | Находка 10 (M), Находка 11 (H) | T1/T2 | Полная трассировка — `product/00-research-evidence-base.md` §3, §4, §7. Ограничения базы (§6) сохраняются: survivorship bias, нет данных о конверсии `скачал → бизнес-результат` и о WTP за standalone ZIP — валидация только через реальные транзакции MVP (`paid → first successful business outcome`). Документы, которые должны учесть ADR-5/ADR-6 следующими: `13-deliver-prd` (FR: installer, doctor, guardrails, карточка с ограничениями), `19-pricing-packaging` (Agent Kit как единица ценности), `24-measure-instrumentation-spec` (события установки и guardrails). --- *Ревизия 27.08.2026 подготовлена на основе консолидированной базы 00 (27.08.2026, ~70 источников, ~60 карточек). ADR-5 и ADR-6 — прямые следствия Находок 3, 5, 6, 9 и урока 2.1.243.*