| 1 | # ADR 0027: Узкая команда (человек + ассистент) и зрелость «для открытия» — две оси, не одна очередь |
| 2 | |
| 3 | **Статус:** Accepted |
| 4 | **Дата:** 2026-04-08 |
| 5 | **Обновлено:** 2026-04-08 — Accepted; discoverability и триггеры оси B. Подробности — [§ История](#adr0027-history). |
| 6 | ## Связанные ADR |
| 7 | |
| 8 | | ADR | Роль | |
| 9 | |-----|------| |
| 10 | | [0024](0024-ide-sdk-and-stable-contracts.md) | контракты и дисциплина границ без обещания SemVer «завтра» | |
| 11 | | [0005](0005-defer-dynamic-plugins-mef.md) | отложенный plugin-host | |
| 12 | | [0013](0013-command-surface-and-discoverability.md) | discoverability — отдельная ось от скорости ядра | |
| 13 | | [0010](0010-ui-modes-toml-configuration.md) | TOML как честный слой конфигурации | |
| 14 | | [0028](0028-user-settings-toml-localappdata-and-secrets.md) | канон пути и формата пользовательского `settings.toml` и секретов | |
| 15 | | [0029](0029-configuration-toml-canonical-ui-facade.md) | TOML-first; целостный центр настроек deferred; точечный UI — фасад канона | |
| 16 | |
| 17 | ## Резюме |
| 18 | |
| 19 | - Две оси: **границы** узкой команды (человек + ассистент) vs **очередь** публичной зрелости. |
| 20 | - Discoverability через доки, примеры и ADR — без обязательства «IDE для всех» в v1. |
| 21 | |
| 22 | |
| 23 | ### Вне ADR |
| 24 | |
| 25 | | Документ | Роль | |
| 26 | |----------|------| |
| 27 | | [README](README.md) | политика: крупные смены направления — отдельным коммитом + ADR | |
| 28 | | [onboarding-first-run-v1](../design/onboarding-first-run-v1.md) | живой чертёж first-run/онбординга — **не** обязательный объём для «открытия репо» по этому ADR; ориентир, когда осознанно углублять UI | |
| 29 | |
| 30 | --- |
| 31 | ## Контекст |
| 32 | |
| 33 | CascadeIDE целится в **зрелую десктопную IDE**, которую можно **открыть** для других разработчиков и интеграторов. Параллельно фактическая скорость разработки сейчас опирается на **очень малую «команду»**: автор(ы) плюс ассистент (LLM) в парной работе. |
| 34 | |
| 35 | Без явного разделения возникает риск: |
| 36 | |
| 37 | - либо **размазывания** — делать «как для магазина» (онбординг, установщики внешних тулов, полированный UI настроек) и терять темп на ядре; |
| 38 | - либо **технического долга на границах** — гнать фичи «только для себя» и потом переписывать контракты, пути конфигов и интеграции при первом внешнем потребителе. |
| 39 | |
| 40 | Нужна **одна зафиксированная модель**: как совмещать долгосрочную открытость и краткосрочный фокус без противоречия. |
| 41 | |
| 42 | --- |
| 43 | |
| 44 | ## Решение |
| 45 | |
| 46 | Развести два независимых измерения — **форма продукта** и **очередь поставки**. |
| 47 | |
| 48 | ### 1. Ось A — «форма» (зрелость границ) |
| 49 | |
| 50 | **Инвестируем заранее** в то, что дорого менять задним числом: |
| 51 | |
| 52 | - стабильные **контракты** расширения и протоколы (в духе [0024](0024-ide-sdk-and-stable-contracts.md): слои, capabilities, out-of-proc интеграции); |
| 53 | - **одна точка правды** для конфигурации (глобальный `settings.toml`, репозиторный `workspace.toml` и т.д. — см. [0010](0010-ui-modes-toml-configuration.md)); |
| 54 | - **ADR** и навигатор ([architecture-policy.md](../architecture-policy.md)) при смене направления — чтобы внешний читатель и будущий ты видели *почему*, а не только *что* в коде. |
| 55 | |
| 56 | Это **не** обязательство сегодня делать полный онбординг или маркетинговую «упаковку»; это обязательство **не ломать доверие к границам** без осознанного шага. |
| 57 | |
| 58 | ### 2. Ось B — «очередь» (что в спринте у пары человек–ассистент) |
| 59 | |
| 60 | **Жёстко приоритизируем** то, что даёт ценность **текущим** пользователям процесса (включая парную работу с ассистентом): отладка, редактор, диагностики, LSP, предсказуемые пути файлов. |
| 61 | |
| 62 | В **отложенный бэклог** (см. **триггеры** ниже) относим типичные «магазинные» вещи, если они **не** разблокируют ядро: |
| 63 | |
| 64 | - отдельное приложение настроек, тяжёлый установщик внешних серверов из IDE, расширенный first-run wizard; |
| 65 | - полировку discoverability ради незнакомого пользователя ([0013](0013-command-surface-and-discoverability.md) остаётся направлением, но **не** блокером скорости ядра). |
| 66 | |
| 67 | **Минимально достаточная** discoverability для «открытия репозитория» на оси B: **документация** (в т.ч. по TOML и путям конфигов), **примеры** в репозитории, **ADR** с обоснованием решений — без возражений как базовый пакет v1; полноценный мастер в UI не требуется, пока не сработал триггер. Дополнительный ориентир по более богатому first-run/онбордингу (когда созреет очередь): чертёж [onboarding-first-run-v1](../design/onboarding-first-run-v1.md) — **не** часть минимума по этому ADR, а место для будущей проработки. |
| 68 | |
| 69 | ### Триггеры: когда трогать отложенное по оси B |
| 70 | |
| 71 | Поднимать задачи «для незнакомца» (мастера, установщики, сильная полировка discoverability) из отложенного бэклога **осознанно**, если выполняется **хотя бы одно**: |
| 72 | |
| 73 | 1. **Первый внешний контрибьютор** (не из круга текущих авторов репо) с реальным PR/issue — сигнал, что путь «клонировать и собрать» уже проверяется чужим контекстом. |
| 74 | 2. **Релиз-кандидат** или иная явная веха «показываем сборку шире, чем себе» — появляется оправдание тратить время на трение входа. |
| 75 | 3. **Явная боль или запрос** от пользователя/интегратора (в т.ч. повторяющийся) — не ждать «магазина», если уже горит. |
| 76 | 4. **Инфраструктурная необходимость** — задача по оси B разблокирует ядро или тесты (тогда это не «только аудитория», а смешанный платёж; см. §3). |
| 77 | |
| 78 | Пока ни один триггер не сработал, очередь остаётся на ядре и границах (оси A и «свои» пользователи). |
| 79 | |
| 80 | ### 3. Правило согласования осей |
| 81 | |
| 82 | - Если задача **укрепляет границы** (контракт, протокол, формат файла) — её можно брать **раньше**, даже при малой команде. |
| 83 | - Если задача **только снижает трение для незнакомца** — брать **после** стабилизации ядра для «своих», либо когда сработал **триггер** из §2 (внешний контрибьютор, RC, явная боль, инфраструктурная необходимость). |
| 84 | |
| 85 | ### 4. Явная эвристика для обсуждения в чате / ревью |
| 86 | |
| 87 | Вопрос к любой крупной работе: *«Это платёж по оси A (границы) или по оси B (аудитория)?»* |
| 88 | Если оба — разбить на два коммита/два подхода по смыслу (политика логических коммитов в корневых правилах репозитория Cursor). |
| 89 | |
| 90 | --- |
| 91 | |
| 92 | ## Последствия |
| 93 | |
| 94 | - **Планирование:** в issue/заметках можно помечать метками в духе `boundary` vs `audience-friction` (имена — на усмотрение репо); не смешивать в одной фразе «надо успеть к открытию» без уточнения оси. |
| 95 | - **SDK и [0024](0024-ide-sdk-and-stable-contracts.md):** «малая команда» **не** освобождает от дисциплины контрактов; наоборот, контракты экономят время пары «человек + ассистент» на согласовании границ. |
| 96 | - **Открытие исходников и «IDE для других»:** готовность измеряется не только количеством мастеров, а **предсказуемостью** конфигов, документированными решениями и тестируемыми границами — это совместимо с узкой командой, если очередь честна. |
| 97 | |
| 98 | --- |
| 99 | |
| 100 | ## Отклонённые альтернативы |
| 101 | |
| 102 | - **«Сначала только хак для себя, потом всё переложим под людей»** — отклонено как источник дорогого переписывания на границах; оси A/B разделяют «быстро внутри» и «аккуратно снаружи» без отказа от второго. |
| 103 | - **«Зрелость = сейчас делаем UI для массового пользователя»** — отклонено: смешивает оси и губит темп ядра при малой полосе пропускания. |
| 104 | - **«Пока нас двое — ADR не нужны»** — отклонено: ADR как раз дешёвее для пары, чем устная память и расхождение контекста между сессиями ассистента. |
| 105 | |
| 106 | --- |
| 107 | |
| 108 | ## История изменений |
| 109 | |
| 110 | <a id="adr0027-history"></a> |
| 111 | |
| 112 | | Дата | Изменение | |
| 113 | |------|-----------| |
| 114 | | 2026-04-08 | Accepted; уточнён минимум discoverability (дока + примеры + ADR, ссылка на чертёж онбординга); добавлены **триггеры** вывода задач оси B из отложенного бэклога. | |
| 115 | |