CLAUDE.md — паспорт проекта orchestrator

TL;DR

Мульти-агентный оркестратор разработки. FastAPI-сервис: принимает webhooks от Plane и Gitea, ведёт задачи по конвейеру стадий через Quality Gates, запускает Claude CLI агентов (analyst → architect → developer → reviewer → tester → deployer) на каждой стадии. Оркестратор дорабатывает в том числе сам себя (self-hosting).

Стек

Backend: FastAPI + uvicorn (Python 3.12)
БД: SQLite (src/db.py)
Агенты: Claude CLI (ORCH_CLAUDE_BIN), по одному промпту на роль в .openclaw/agents/
Очередь задач: собственная (SQLite jobs, src/queue_worker.py, ORCH-1)
Контейнеризация: Docker + Compose
CI/CD: Gitea Actions (.gitea/workflows/)
Деплой: docker compose на mva154

Команды

uvicorn src.main:app --reload --port 8500 — поднять локально (dev)
pytest tests/ -q — все тесты
docker compose up -d --build — прод
docker compose --profile staging up -d orchestrator-staging — staging-песочница (8501)

Среды

prod — orchestrator (8500), внешний URL https://openclaw.mva154.duckdns.org/orchestrator/
staging — orchestrator-staging (8501), изолированная БД (./data/staging), только sandbox-проект

Структура

src/ — приложение (main, config, db, stages, stage_engine, queue_worker, projects, usage)
src/agents/launcher.py — запуск Claude CLI агентов
src/qg/checks.py — Quality Gate проверки
src/webhooks/ — приём вебхуков Plane/Gitea
tests/ — pytest
docs/ — документация, ADR, work-items, operations
scripts/ — утилиты (staging_check.py, orchestrator-deploy-hook.sh)

Конвейер (кратко; детали — docs/architecture/README.md)

created → analysis → architecture → development → review → testing → deploy-staging → deploy → done
                          ↑                          │
                          └──── REQUEST_CHANGES ──────┘  (откат на development, max 3)

Конвенции

Conventional Commits (feat:, fix:, docs:, refactor:, test:)
Ветки: feature/ORCH-NNN-slug, fix/ORCH-NNN-slug
ADR per work-item: docs/work-items/<plane-id>/06-adr/ADR-NNN-slug.md
Global ADR (сквозные решения): docs/architecture/adr/adr-NNNN-slug.md
Work items: docs/work-items/<plane-id>/
Машинные вердикты Quality Gate — строго YAML-frontmatter (verdict:, deploy_status:, staging_status:), никогда проза

Артефакты задачи (`docs/work-items/<plane-id>/`)

00-business-request.md, 01-brd.md, 02-trz.md, 03-acceptance-criteria.md, 04-test-plan.yaml, 06-adr/ADR-NNN-slug.md, 07-infra-requirements.md, 08-data-requirements.md, 10-tech-risks.md, 12-review.md, 13-test-report.md, 14-deploy-log.md, 15-staging-log.md.

Правила для агентов

Перед любым действием прочесть этот файл и docs/architecture/README.md.
Документация = golden source наравне с кодом. Изменил функционал → обнови доку В ТОМ ЖЕ PR. Архитектурное решение → заведи ADR. Обнови CHANGELOG.md.
Никогда не править артефакты других этапов.
Никогда не комментировать ТЗ задним числом — если ТЗ не годится, возвращай в Анализ.
Никогда не закрывать задачу самостоятельно — это делает CI / финальная стадия.
Reviewer проверяет: обновлена ли документация. Нет → REQUEST_CHANGES.
Не использовать --no-verify без явного одобрения Owner.
Секреты — только в .env/.env.staging на хосте, в гит НЕ коммитятся (канон — .env.example).

⚠️ Self-hosting — оркестратор правит САМ СЕБЯ

Задачи проекта ORCH меняют инструмент, который СЕЙЧАС работает в продакшене и обслуживает ДРУГИЕ проекты (enduro-trails) из ОДНОГО инстанса с ОБЩЕЙ БД и общей очередью.

НЕ перезапускать / не ронять прод-контейнер orchestrator в рамках задачи — встанет конвейер всех проектов.
Любой деплой/рестарт self = групповой риск. Детали и топология — docs/operations/INFRA.md.
Стадия deploy-staging (порт 8501) — обязательная страховка перед прод-деплоем орка.

Паспорт проекта orchestrator. Поддерживается агентами при каждой доработке. Изолирован: описывает только этот проект (канон per-repo, см. ORCH-9).

5.4 KiB Raw Blame History Unescape Escape