Files

claude-bot 6d798c01ef docs(overview): витрина системы docs/overview/ — бизнес+тех, 3 аудитории, презентация (ORCH-011)

Единая точка входа в документацию платформы (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>

2026-06-11 09:36:40 +03:00

7.1 KiB

Raw Blame History

Витрина системы — Orchestrator

Что это за система. Orchestrator — автономная фабрика разработки: конвейер из шести ИИ-агентов (аналитик → архитектор → разработчик → ревьюер → тестировщик → деплойер), который проводит задачу от бизнес-постановки до выкладки на прод. Человек ставит задачу и принимает результат; всё между — автономно, под защитой машинных гейтов качества. Платформа ведёт несколько проектов из одного инстанса, дорабатывает сама себя (self-hosting) и тиражируется на новые хосты.

Зачем эта витрина. Это единая точка входа в документацию системы: связное описание на двух уровнях — бизнес (для нетехнического читателя) и технический (7 блоков), с маршрутами чтения для трёх аудиторий и слайдо-готовой основой для презентации. Витрина — обзор; за деталями она ведёт ссылками в инженерные golden sources, не подменяя их.

Состав витрины

Файл	О чём
business.md	Бизнес-уровень: проблема, решение, что умеет, ценность, сценарии
tech-architecture.md	Блок 1: компоненты и связи, схема потока
tech-pipeline.md	Блок 2: конвейер, стадии, гейты, откаты, человеческие гейты
tech-agents.md	Блок 3: 6 ролей агентов, артефакты, модель/эффорт
tech-data-model.md	Блок 4: каноническая модель объектов, словарь терминов
tech-integrations.md	Блок 5: Plane, Gitea, LLM, Telegram
tech-quality-security.md	Блок 6: гейты качества, безопасность, секреты
tech-observability.md	Блок 7: наблюдаемость, аналитика, журнал уроков
presentation.md	Слайдо-источник презентации + сборка `.pptx`

Маршруты чтения

Я заказчик

business.md — проблема, решение, ценность.
business.md → Сценарии использования — как это выглядит в работе.
presentation.md — слайдовая версия рассказа (собирается в PowerPoint).
Развернуть у себя: LITE_SETUP (своя инфраструктура) или BUNDLED_SETUP (весь стек одним комплектом).

Я менеджер проекта

business.md — что платформа делает и где в процессе человек.
tech-pipeline.md — конвейер, статусная модель Plane, человеческие гейты (одобрение постановки, подтверждение прод-деплоя).
tech-observability.md — как следить за ходом: живая Telegram-карточка, статусы, стоимость.

Я разработчик

Тех-блоки 1→7: архитектура → конвейер → агенты → модель объектов → интеграции → качество/безопасность → наблюдаемость.
Инженерный справочник архитектуры и internals — детали реализации.
Стандарты (структура доков конвейера), HANDOFF_PROTOCOL (машинный контракт стадий), TRACEABILITY (маркеры решений).
Реестр сквозных ADR — история архитектурных решений.
CLAUDE.md — паспорт проекта и правила для агентов.

Норматив сопровождения

Изменил функциональность платформы → обнови витрину docs/overview/ в том же PR.

Какой файл правится при каком классе изменений:

Класс изменения	Файл витрины
Новый компонент / демон / поток данных	tech-architecture.md
Стадии, гейты, под-гейты, маршруты задач	tech-pipeline.md
Роли агентов, промпты, модель/эффорт	tech-agents.md
Таблицы БД, объекты, термины	tech-data-model.md
Plane / Gitea / LLM / Telegram	tech-integrations.md
Гейты качества, секреты, self-hosting-страховки	tech-quality-security.md
Эндпоинты наблюдаемости, метрики, уроки	tech-observability.md
Новая способность уровня продукта	business.md + при необходимости presentation.md

Каркас и машинно-проверяемые факты витрины (перечень стадий, имена гейтов, полнота агентов, валидность ссылок) защищены структурными тестами tests/test_system_docs.py — дрейф рвёт CI. Прозу проверяет reviewer: необновлённая витрина при изменении описанной в ней функциональности — finding ≥ P1 (расширение оси обзорных доков).

Витрина — обзорный слой документации. Текущее состояние и реестр доработок — CLAUDE.md; концепция развития — Product Vision.

7.1 KiB Raw Blame History Unescape Escape