claude-bot
dbd8df6eb2
Create docs/operations/FAQ_STOP.md — a user-facing "вопрос → ответ" FAQ for Plane board users explaining the STOP status: what it does, how to cancel a task, step-by-step consequences (agent stops → jobs cancelled → working branch and worktree removed → task → cancelled → Telegram+Plane; docs artifacts preserved, main/prod untouched), deferred cancellation in the critical merge/deploy window, explicit "STOP does NOT revert merged/deployed code" (revert is a separate task), restart only via "To Analyse" from scratch, no-op causes, where to observe the result, and STOP/Approved/Confirm Deploy disambig. docs-only: src/**, STAGE_TRANSITIONS, QG_CHECKS, check_*, machine-verdict keys and the DB schema are byte-for-byte untouched. STOP behaviour source of truth remains ORCH-090 (adr-0026); the FAQ documents and links to it (link-first: machine details markers/lease/tombstone given by reference, not duplicated). Add two-way cross-links: docs/overview/business.md (Сценарий 6) and docs/overview/tech-pipeline.md (Отмена: STOP → cancelled) → FAQ; FAQ → overview + ADR ORCH-090. Structure guarded by deterministic anti-drift test tests/test_faq_stop_doc.py (offline, no network/LLM/subprocess; mirrors tests/test_lite_setup_doc.py): existence + 8 section anchors + fact bricks + cross-links + claim-level negative scan (sentence-level, not bare substrings, so it never false-fails on correctly negating phrases — TR-3, with a non-evergreen self-check). Full pytest tests/ green (2227 passed). Refs: ORCH-108 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
10 KiB
Бизнес-уровень: что это и зачем
Читатель этого документа — нетехнический: заказчик, руководитель, менеджер. Технические детали вынесены в тех-часть витрины и даются здесь только ссылками.
Проблема
Классическая разработка — это люди-бутылочное-горлышко на каждом шаге: аналитик, архитектор, разработчик, ревьюер, тестировщик, деплой-инженер. Каждая передача задачи между ними — потеря времени, контекста и денег. Мелкая фича или баг едут до прода днями: не потому, что работа сложная, а потому, что задача ждёт людей в очередях между ролями.
Решение
Orchestrator — конвейер из ИИ-агентов, который проводит задачу через все стадии разработки сам: анализ требований → проектирование → код → ревью → тестирование → репетиция выкладки → выкладка на прод. Человек в этой схеме — постановщик и приёмщик: он формулирует задачу, одобряет постановку и подтверждает выкладку на прод. Всё между — автономно.
Честность конвейера держат гейты качества: автоматические проверки на каждом переходе, которые не пускают задачу дальше, пока стадия не выполнена по-настоящему (тесты зелёные, ревью одобрено, репетиция выкладки успешна). Агент не может «уговорить» гейт — вердикты машинные, не прозой.
Что умеет платформа сегодня
Ниже — фактическое состояние, не планы (концепция развития — отдельный документ, Product Vision).
- Автономный конвейер «задача → прод». Задача, поставленная в трекере, проходит весь путь до выкладки без ручных пинков; человек участвует ровно в двух точках — одобрение постановки и подтверждение прод-выкладки.
- Мультипроектность. Один инстанс платформы ведёт несколько проектов (репозиториев) одновременно, с общей очередью и честным разделением работы.
- Самовосстановление. Фоновые механизмы находят и чинят зависшие задачи: упавший агент перезапускается, осиротевшая задача возвращается в очередь, переполненный диск чистится, а независимый сторож следит за самой платформой снаружи.
- Пакетный авто-режим. Задачи одного проекта выстраиваются в очередь и едут друг за другом без столкновений; специальными метками на задаче можно снять оба человеческих одобрения — и пакет задач уедет «за ночь» полностью автономно.
- Дешёвый багфикс-маршрут. Задача с меткой «баг» едет коротким путём — без тяжёлой аналитики и отдельной стадии проектирования, но через все те же гейты качества.
- Отмена задачи одной кнопкой. Перевод задачи в статус «STOP» в трекере останавливает работу, снимает её с очереди и прибирает за собой — безопасно даже посреди конвейера.
- Наблюдаемость. У каждой задачи — живая карточка в Telegram (стадия, время, стоимость); у платформы — служебные страницы состояния и машинные метрики; история отклонений пишется в журнал уроков.
- Самообслуживание (self-hosting). Платформа дорабатывает сама себя тем же конвейером, с обязательной репетицией на песочнице и ручным подтверждением выкладки.
- Тиражируемость. Платформа разворачивается на новой инфраструктуре без правки кода: вариант Lite (у заказчика своя инфраструктура) и вариант Bundled (весь стек одним комплектом) — по пошаговым инструкциям.
Ценность
- ⚡ Скорость. Полный цикл «постановка → прод» без очередей между ролями; по оценке из Product Vision — порядка 35 минут на типовую фичу без ручных вмешательств.
- 💰 Стоимость. Работа агентов в разы дешевле команды специалистов; стоимость каждой задачи видна в её карточке — расходы прозрачны.
- 🎯 Автономность. Ноль ручных пинков в штатном прогоне: человек принимает решения, а не двигает задачу.
- 🛡️ Надёжность. Многоуровневые гейты качества и репетиция выкладки на песочнице не пускают недоделку на прод; сломавшаяся выкладка откатывается, проект замораживается до разбора.
- 🔁 Масштаб. Одна платформа — несколько проектов; сама платформа тиражируется на новые хосты за часы по инструкции.
Сценарии использования
Сценарий 1: фича за вечер
Заказчик формулирует задачу в трекере и переводит её в работу. Конвейер собирает требования, проектирует, пишет код и тесты, проходит ревью и тестирование, репетирует выкладку. Человек дважды нажимает «одобрить» — на постановке и перед продом. Вечером фича на проде.
Сценарий 2: багфикс по короткому маршруту
На задачу ставится метка «баг» — конвейер пропускает тяжёлую аналитику и отдельное проектирование, сразу чинит и фиксирует дефект регресс-тестом. Все гейты качества — без исключений.
Сценарий 3: пакет задач на ночь
Несколько задач проекта получают метки авто-одобрения. Очередь проводит их друг за другом: каждая следующая стартует от свежей версии кода с результатом предыдущей. Утром — пакет изменений на проде и полный след по каждой задаче.
Сценарий 4: несколько проектов параллельно
Один инстанс платформы обслуживает несколько репозиториев: задачи разных проектов едут одновременно, не мешая друг другу; внутри одного проекта порядок строго последовательный.
Сценарий 5: развернуть платформу у себя
Заказчик получает платформу на своей инфраструктуре по инструкции Lite (есть свои трекер и git) или Bundled (весь стек одним комплектом, ~14 контейнеров), со свежими секретами и проверкой каждого шага.
Сценарий 6: остановить задачу
Передумали — переводите задачу в статус «STOP»: работа агента останавливается, ветка и рабочие материалы прибираются, задача помечается отменённой. Если задача в этот момент в необратимой фазе выкладки — отмена аккуратно откладывается до её честного завершения. Подробнее — FAQ по статусу STOP.
Технические детали каждой способности — в тех-части витрины: как устроен конвейер, кто такие агенты, как работает наблюдаемость.