План инженерных работ

Работа идёт короткими пакетами. Каждый пакет должен быть понятен без чтения всей истории проекта.

Как проходит один пакет

1. Записать одно ожидаемое поведение простыми словами.
2. Добавить маленький тест и увидеть, что он падает по нужной причине.
3. Написать минимальный код для прохождения теста.
4. Упростить имена и код без изменения поведения.
5. Запустить тесты, style checks и сборку документации.
6. Обновить README или ADR, если изменились границы либо команды.
7. Создать отдельный коммит с одним смыслом и передать его на ревью.

Документация и настройки CI не всегда имеют шаг с падающим unit-тестом. Для них сначала добавляется проверка, которая умеет найти ошибку, а затем минимальное исправление.

Порядок пакетов

0. Локальная рабочая среда

Состояние: готово локально.

• назначить пять папок Portable Agent как отдельные Git roots в IntelliJ;
• проверить .git, origin и ветку main в каждой папке;
• не объединять сервисы в один репозиторий.

1. Общие правила

Состояние: готово для существующих репозиториев; правило применяется к новым репам.

• русская документация;
• простой английский уровня A2–B1 в именах;
• TDD: тест, код, улучшение;
• AGENTS.md в каждом репозитории;
• запрет придумывать бизнес-правила без владельца продукта.

2. Python-каркас agent-runtime

Состояние: готово и проверено в backend acceptance.

• папки controllers, services, repositories, models, schemas, config, exceptions;
• Ruff, format, strict mypy, pytest и покрытие сервисного слоя не ниже 90%;
• строгая сборка MkDocs;
• без выбора AI-модели и реальных правил риска.

3. Java-каркас action-service

Состояние: готово и расширено до рабочего Temporal-сценария.

• обычные MVC-папки: controller, service, repository, model, config, exception;
• HTTP interface и models создаются из закреплённой версии OpenAPI только в build/;
• jOOQ и SQL migrations, без JPA и Hibernate;
• unit-тесты сервиса и интеграционные тесты PostgreSQL через Testcontainers;
• Checkstyle/Spotless и строгая сборка MkDocs;
• без решений о реальных подтверждениях и денежных операциях.

4. Контракты и документация

Состояние: основа готова; правило действует для каждого нового API.

• единый README, AGENTS.md, MkDocs/TechDocs и catalog-info.yaml;
• OpenAPI, AsyncAPI и JSON Schema проверяются автоматически;
• SemVer release bundle, oasdiff и generated API для реальных потребителей;
• общие решения хранятся как ADR в platform;
• описание каждого репозитория отражает только уже существующий код.

5. CI/CD и защита GitHub

Состояние: общая основа готова; подключение продолжается для новых реп.

• reusable workflows для Java, Python, contracts, docs и контейнеров;
• одинаковые имена обязательных checks;
• Dependabot, CODEOWNERS и минимальные permissions;
• защита main включается только после зелёного CI каждого репозитория.

5.1 Платформа разработки

Состояние: локальный Compose и первый сквозной smoke готовы. Preview-окружения, полная наблюдаемость и проверки отказов остаются следующими инженерными пакетами.

• локальные зависимости через Compose без секретов в Git;
• общий Helm chart и GitOps-каталог окружений;
• OpenTofu-фабрика репозиториев;
• test-lab с k6 и безопасной заготовкой Chaos Mesh;
• автоматическая регистрация нового сервиса;
• production остаётся за отдельным ADR.

6. Первый продуктовый срез

Состояние: backend-срез, общий текстовый вход и renderer-neutral Widget SDK готовы. Conversation Service, адаптер и реальный календарь ещё не реализованы.

Выбран сценарий создания события календаря с явным подтверждением. Обязательны название, начало, конец и часовой пояс. Сначала пишется сквозной acceptance-тест с fake-calendar, и только затем добавляется настоящая интеграция.

Что смотреть на ревью

• один коммит решает одну задачу;
• тест объясняет ожидаемое поведение;
• имя можно понять с базовым английским;
• контроллер не содержит правила бизнеса;
• репозиторий не принимает решения за сервис;
• документация совпадает с кодом;
• в каркасе нет выдуманного поведения продукта.