claude-bot
6d798c01ef
Единая точка входа в документацию платформы (ADR-001 D1–D9): - docs/overview/ — 10 файлов: индекс (маршруты «Я заказчик / Я менеджер / Я разработчик» + норматив «изменил функциональность → обнови витрину в том же PR»), business.md (без жаргона, 6 сценариев), 7 тех-блоков (link-first), presentation.md (16 слайдов + процедура сборки «команда + Проверка:»). - scripts/build_presentation.py — генератор .pptx в тёмном дизайне (python-pptx; чистый stdlib-парсер parse_slides + ленивый import pptx; бинарь не коммитится, build/ в .gitignore; зависимость НЕ в прод-образе — машинный гард TC-09). - tests/test_system_docs.py — структурный анти-дрейф: derive-сверки стадий/ гейтов/агентов импортом STAGE_TRANSITIONS/QG_CHECKS/glob промптов/config, валидность ссылок, FORBIDDEN-скан + секрет-эвристика, слайды каноническим парсером, NFR-2, указатели. - reviewer.md — ось обзорных доков ORCH-079 расширена на витрину (D7; канон 52d байт-в-байт, только текст внутри секций) + анти-регресс ассерт в test_agent_prompts_canon.py. - Указатели: README.md, CLAUDE.md (правила №2/№6, «Структура»), PRODUCT_VISION.md (врезка-ссылка), CHANGELOG.md. Рантайм байт-в-байт: src/**, docker-compose.yml, Dockerfile, requirements* — ноль изменений (docs+tests+dev-скрипт, паттерн ORCH-102/103). pytest: 1873 passed. Refs: ORCH-011 Co-Authored-By: Claude Opus 4.8 <noreply@anthropic.com>
191 lines
13 KiB
Markdown
191 lines
13 KiB
Markdown
# Презентация системы: слайдо-источник
|
||
|
||
> Источник истины презентации. Каждый слайд — блок `## Слайд N: Заголовок` с тезисами
|
||
> (3–6 на слайд) и опциональной подписью визуала. Из этого файла собирается редактируемый
|
||
> PowerPoint в тёмном дизайне — процедура в конце файла («Как собрать .pptx»). Собранный
|
||
> бинарь в git не коммитится: меняешь рассказ — правишь этот файл и пересобираешь.
|
||
|
||
## Слайд 1: Orchestrator — автономная фабрика разработки
|
||
|
||
- Конвейер из ИИ-агентов: от постановки задачи до выкладки на прод
|
||
- Человек ставит задачу и принимает результат — всё между автономно
|
||
- Платформа уже работает: ведёт несколько проектов и дорабатывает сама себя
|
||
|
||
> Визуал: тёмный титул, логотип-конвейер из шести звеньев
|
||
|
||
## Слайд 2: Проблема
|
||
|
||
- Классическая разработка — люди-бутылочное-горлышко на каждом шаге
|
||
- Каждая передача между ролями — потеря времени, контекста и денег
|
||
- Мелкая фича или баг едут до прода днями — из-за очередей, не сложности
|
||
|
||
> Визуал: цепочка из шести человек с песочными часами между ними
|
||
|
||
## Слайд 3: Решение
|
||
|
||
- Шесть ИИ-агентов проводят задачу через все стадии разработки сами
|
||
- Аналитик → архитектор → разработчик → ревьюер → тестировщик → деплойер
|
||
- Человек принимает два решения: одобрить постановку и подтвердить прод
|
||
- Честность держат машинные гейты качества — их нельзя «уговорить»
|
||
|
||
> Визуал: та же цепочка, но из агентов; человек над ней с двумя кнопками
|
||
|
||
## Слайд 4: Как это работает — конвейер
|
||
|
||
- Задача из трекера едет по стадиям: анализ → проектирование → код → ревью → тесты → репетиция → прод
|
||
- На каждом переходе — гейт: машинная проверка честности стадии
|
||
- Не прошёл гейт — задача возвращается на доработку с замечаниями
|
||
- Каждая задача — своя ветка и изолированная рабочая копия кода
|
||
|
||
> Визуал: горизонтальная схема стадий со шлагбаумами-гейтами
|
||
|
||
## Слайд 5: Гейты качества
|
||
|
||
- Вердикты машинные: зелёный CI, одобрение ревью, отчёт тестов — только структурированные ключи
|
||
- Перед продом — четыре дополнительных проверки: безопасность, слияние, покрытие тестами, свежесть сборки
|
||
- Покрытие тестами не может деградировать: базовая линия растёт только вверх
|
||
- Слияние в основную ветку — только через PR; прямой push запрещён всем
|
||
|
||
> Визуал: четыре шлагбаума подряд перед воротами «прод»
|
||
|
||
## Слайд 6: Роли агентов
|
||
|
||
- Аналитик: требования, критерии приёмки, тест-план
|
||
- Архитектор: проектные решения с фиксацией в ADR
|
||
- Разработчик: код + тесты + документация одним PR
|
||
- Ревьюер и тестировщик: независимые машинные вердикты
|
||
- Деплойер: репетиция на песочнице, затем прод
|
||
|
||
> Визуал: шесть карточек-ролей с артефактами на выходе
|
||
|
||
## Слайд 7: Человек в контуре
|
||
|
||
- Постановщик и приёмщик, а не оператор: ноль ручных пинков в штатном прогоне
|
||
- Решение 1: одобрить постановку после аналитики
|
||
- Решение 2: подтвердить выкладку на прод отдельным статусом
|
||
- Живая карточка задачи в Telegram показывает, когда конвейер ждёт вас
|
||
|
||
> Визуал: человек с двумя кнопками и карточка задачи в телефоне
|
||
|
||
## Слайд 8: Пакетный автономный режим
|
||
|
||
- Задачи одного проекта едут строго друг за другом — без столкновений
|
||
- Каждая следующая стартует от свежего кода с результатом предыдущей
|
||
- Метки авто-одобрения снимают оба человеческих гейта — пакет уезжает «за ночь»
|
||
- Технические проверки при этом не ослабляются ни на одну
|
||
|
||
> Визуал: ночная очередь задач, утром — стопка готовых
|
||
|
||
## Слайд 9: Багфикс за полцены
|
||
|
||
- Метка «баг» — и задача едет коротким маршрутом
|
||
- Пропускаются тяжёлая аналитика и отдельное проектирование
|
||
- Обязателен регресс-тест, фиксирующий дефект
|
||
- Все гейты качества — без исключений
|
||
|
||
> Визуал: развилка маршрутов — длинный и короткий путь к одному финишу
|
||
|
||
## Слайд 10: Самовосстановление
|
||
|
||
- Упавший агент перезапускается, осиротевшая задача возвращается в очередь
|
||
- Зависшие состояния находит и чинит фоновый сверщик
|
||
- Независимый сторож следит за платформой снаружи и шлёт алерты отдельным каналом
|
||
- Деградация прода после выкладки замораживает проект до разбора человеком
|
||
|
||
> Визуал: платформа с автоподзаводом и внешним сторожем
|
||
|
||
## Слайд 11: Наблюдаемость
|
||
|
||
- Одна задача — одна живая карточка: стадия, агент, стоимость, время
|
||
- Служебные страницы: снимок очереди и машинные метрики для мониторинга
|
||
- Журнал уроков копит отклонения конвейера — фундамент самообучения
|
||
- Стоимость каждой задачи и каждой роли видна по фактам
|
||
|
||
> Визуал: дашборд из карточки, очереди и графика стоимости
|
||
|
||
## Слайд 12: Одна платформа — много проектов
|
||
|
||
- Несколько репозиториев из одного инстанса с общей очередью
|
||
- Внутри проекта — строгий порядок, между проектами — параллельность
|
||
- Платформа дорабатывает сама себя тем же конвейером (self-hosting)
|
||
- Своя доработка репетируется на песочнице и требует явного подтверждения
|
||
|
||
> Визуал: один конвейер, несколько лент с разными проектами
|
||
|
||
## Слайд 13: Сценарии использования
|
||
|
||
- Фича за вечер: постановка → прод с двумя кликами человека
|
||
- Пакет задач на ночь: метки авто-одобрения, утром всё на проде
|
||
- Багфикс по короткому маршруту с обязательным регресс-тестом
|
||
- Остановить задачу: статус STOP — безопасная отмена с уборкой
|
||
- Несколько проектов параллельно без пересечений
|
||
|
||
> Визуал: пять пиктограмм-сценариев
|
||
|
||
## Слайд 14: Тираж платформы
|
||
|
||
- Разворачивается на новой инфраструктуре без правки кода — только конфиг
|
||
- Lite: у заказчика свои трекер и git — ставятся только оркестратор и сторож
|
||
- Bundled: весь стек одним комплектом (~14 контейнеров) и бутстрап-скрипт
|
||
- Свежие секреты, пошаговые инструкции с проверкой каждого шага
|
||
|
||
> Визуал: коробка-дистрибутив в двух размерах
|
||
|
||
## Слайд 15: Статус платформы сегодня
|
||
|
||
- В проде: автономный конвейер, мультипроектность, самовосстановление
|
||
- В проде: пакетный авто-режим, багфикс-маршрут, отмена задач, журнал уроков
|
||
- Тираж Lite и Bundled — готовые инструкции и инструменты
|
||
- Платформа развивает сама себя: документация и гейты растут с каждой задачей
|
||
|
||
> Визуал: чек-лист способностей с отметками «в проде»
|
||
|
||
## Слайд 16: Итог
|
||
|
||
- Разработка без очередей между ролями: задача → прод за один проход
|
||
- Человек принимает решения — конвейер делает работу
|
||
- Качество держат машинные гейты, прозрачность — живая карточка и метрики
|
||
- Следующий шаг: поставить первую задачу или развернуть платформу у себя
|
||
|
||
> Визуал: тёмный финальный слайд с одной фразой-приглашением
|
||
|
||
---
|
||
|
||
## Как собрать .pptx
|
||
|
||
Сборка выполняется **вне рантайма платформы** — в одноразовом dev-окружении на хосте
|
||
разработчика (зависимость генерации не входит в прод-образ). Скрипт —
|
||
`scripts/build_presentation.py`; формат слайдов выше парсится им же (один парсер — один
|
||
источник истины).
|
||
|
||
**Шаг 1. Создать venv и поставить python-pptx:**
|
||
|
||
```bash
|
||
python3 -m venv .venv-pptx
|
||
.venv-pptx/bin/pip install python-pptx
|
||
```
|
||
|
||
Проверка: `.venv-pptx/bin/pip show python-pptx` печатает версию пакета — PASS; ошибка
|
||
установки — FAIL (проверьте доступ к PyPI).
|
||
|
||
**Шаг 2. Собрать презентацию (из корня репозитория):**
|
||
|
||
```bash
|
||
.venv-pptx/bin/python scripts/build_presentation.py
|
||
```
|
||
|
||
Проверка: скрипт печатает `Собрано слайдов: <N> → build/orchestrator-overview.pptx`, где
|
||
`<N>` равно числу слайдов в этом файле — PASS; `ОШИБКА: …` — FAIL (текст подскажет причину).
|
||
|
||
**Шаг 3. Открыть и проверить результат:**
|
||
|
||
Откройте `build/orchestrator-overview.pptx` в PowerPoint/LibreOffice. Проверка: тема тёмная
|
||
(тёмный фон, светлый текст, акцентные заголовки), кириллица отображается точно, текст слайдов
|
||
выделяется и редактируется — PASS. Каталог `build/` в `.gitignore`: собранный бинарь в git
|
||
не попадает.
|
||
|
||
---
|
||
|
||
*Нарратив слайдов опирается на [business.md](business.md); технические утверждения — на
|
||
тех-блоки витрины ([конвейер](tech-pipeline.md), [агенты](tech-agents.md)).*
|