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>
90 lines
7.1 KiB
Markdown
90 lines
7.1 KiB
Markdown
# Витрина системы — Orchestrator
|
||
|
||
**Что это за система.** Orchestrator — автономная фабрика разработки: конвейер из шести
|
||
ИИ-агентов (аналитик → архитектор → разработчик → ревьюер → тестировщик → деплойер), который
|
||
проводит задачу от бизнес-постановки до выкладки на прод. Человек ставит задачу и принимает
|
||
результат; всё между — автономно, под защитой машинных гейтов качества. Платформа ведёт
|
||
несколько проектов из одного инстанса, дорабатывает сама себя (self-hosting) и тиражируется
|
||
на новые хосты.
|
||
|
||
**Зачем эта витрина.** Это единая точка входа в документацию системы: связное описание на двух
|
||
уровнях — бизнес (для нетехнического читателя) и технический (7 блоков), с маршрутами чтения
|
||
для трёх аудиторий и слайдо-готовой основой для презентации. Витрина — обзор; за деталями она
|
||
ведёт ссылками в инженерные golden sources, не подменяя их.
|
||
|
||
---
|
||
|
||
## Состав витрины
|
||
|
||
| Файл | О чём |
|
||
|------|-------|
|
||
| [business.md](business.md) | Бизнес-уровень: проблема, решение, что умеет, ценность, сценарии |
|
||
| [tech-architecture.md](tech-architecture.md) | Блок 1: компоненты и связи, схема потока |
|
||
| [tech-pipeline.md](tech-pipeline.md) | Блок 2: конвейер, стадии, гейты, откаты, человеческие гейты |
|
||
| [tech-agents.md](tech-agents.md) | Блок 3: 6 ролей агентов, артефакты, модель/эффорт |
|
||
| [tech-data-model.md](tech-data-model.md) | Блок 4: каноническая модель объектов, словарь терминов |
|
||
| [tech-integrations.md](tech-integrations.md) | Блок 5: Plane, Gitea, LLM, Telegram |
|
||
| [tech-quality-security.md](tech-quality-security.md) | Блок 6: гейты качества, безопасность, секреты |
|
||
| [tech-observability.md](tech-observability.md) | Блок 7: наблюдаемость, аналитика, журнал уроков |
|
||
| [presentation.md](presentation.md) | Слайдо-источник презентации + сборка `.pptx` |
|
||
|
||
---
|
||
|
||
## Маршруты чтения
|
||
|
||
### Я заказчик
|
||
1. [business.md](business.md) — проблема, решение, ценность.
|
||
2. [business.md → Сценарии использования](business.md#сценарии-использования) — как это выглядит в работе.
|
||
3. [presentation.md](presentation.md) — слайдовая версия рассказа (собирается в PowerPoint).
|
||
4. Развернуть у себя: [LITE_SETUP](../deployment/LITE_SETUP.md) (своя инфраструктура) или
|
||
[BUNDLED_SETUP](../deployment/BUNDLED_SETUP.md) (весь стек одним комплектом).
|
||
|
||
### Я менеджер проекта
|
||
1. [business.md](business.md) — что платформа делает и где в процессе человек.
|
||
2. [tech-pipeline.md](tech-pipeline.md) — конвейер, статусная модель Plane, человеческие гейты
|
||
(одобрение постановки, подтверждение прод-деплоя).
|
||
3. [tech-observability.md](tech-observability.md) — как следить за ходом: живая Telegram-карточка,
|
||
статусы, стоимость.
|
||
|
||
### Я разработчик
|
||
1. Тех-блоки 1→7: [архитектура](tech-architecture.md) → [конвейер](tech-pipeline.md) →
|
||
[агенты](tech-agents.md) → [модель объектов](tech-data-model.md) →
|
||
[интеграции](tech-integrations.md) → [качество/безопасность](tech-quality-security.md) →
|
||
[наблюдаемость](tech-observability.md).
|
||
2. [Инженерный справочник архитектуры](../architecture/README.md) и
|
||
[internals](../architecture/internals.md) — детали реализации.
|
||
3. [Стандарты](../_standards/PIPELINE_DOCS.md) (структура доков конвейера),
|
||
[HANDOFF_PROTOCOL](../_standards/HANDOFF_PROTOCOL.md) (машинный контракт стадий),
|
||
[TRACEABILITY](../_standards/TRACEABILITY.md) (маркеры решений).
|
||
4. [Реестр сквозных ADR](../architecture/adr/) — история архитектурных решений.
|
||
5. [CLAUDE.md](../../CLAUDE.md) — паспорт проекта и правила для агентов.
|
||
|
||
---
|
||
|
||
## Норматив сопровождения
|
||
|
||
> **Изменил функциональность платформы → обнови витрину `docs/overview/` в том же PR.**
|
||
|
||
Какой файл правится при каком классе изменений:
|
||
|
||
| Класс изменения | Файл витрины |
|
||
|-----------------|--------------|
|
||
| Новый компонент / демон / поток данных | [tech-architecture.md](tech-architecture.md) |
|
||
| Стадии, гейты, под-гейты, маршруты задач | [tech-pipeline.md](tech-pipeline.md) |
|
||
| Роли агентов, промпты, модель/эффорт | [tech-agents.md](tech-agents.md) |
|
||
| Таблицы БД, объекты, термины | [tech-data-model.md](tech-data-model.md) |
|
||
| Plane / Gitea / LLM / Telegram | [tech-integrations.md](tech-integrations.md) |
|
||
| Гейты качества, секреты, self-hosting-страховки | [tech-quality-security.md](tech-quality-security.md) |
|
||
| Эндпоинты наблюдаемости, метрики, уроки | [tech-observability.md](tech-observability.md) |
|
||
| Новая способность уровня продукта | [business.md](business.md) + при необходимости [presentation.md](presentation.md) |
|
||
|
||
Каркас и машинно-проверяемые факты витрины (перечень стадий, имена гейтов, полнота агентов,
|
||
валидность ссылок) защищены структурными тестами `tests/test_system_docs.py` — дрейф рвёт CI.
|
||
Прозу проверяет reviewer: необновлённая витрина при изменении описанной в ней функциональности —
|
||
finding ≥ P1 (расширение оси обзорных доков).
|
||
|
||
---
|
||
|
||
*Витрина — обзорный слой документации. Текущее состояние и реестр доработок — [CLAUDE.md](../../CLAUDE.md);
|
||
концепция развития — [Product Vision](../PRODUCT_VISION.md).*
|