Перейти к основному содержимому

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

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

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

  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, общий Helm chart, preview-каркас и сквозной smoke готовы. Все версии сервисов закреплены полными Git SHA. Полная наблюдаемость и проверки отказов остаются следующими инженерными пакетами.

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

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

Состояние: backend-срез, Conversation Service, Telegram Adapter, renderer-neutral Widget SDK, Connection Service и Google Calendar provider реализованы. Автоматический acceptance на fake-провайдере проходит на актуальных версиях всех сервисов. Ручной Google sandbox N2N требуется повторить после обновления локальной Temporal history.

Выбран сценарий создания события календаря с явным подтверждением. Обязательны название, начало, конец и часовой пояс. fake-calendar остаётся обязательным автономным CI-провайдером. Google использует тот же контракт и выбирается только при доступном подключении пользователя.

6.1 Общий виджет подключения​

Состояние: контракт и реализация готовятся отдельными pull request.

  • Conversation Service проверяет подключение до создания внешнего действия;
  • одноразовая OAuth-ссылка не сохраняется в состоянии диалога;
  • Channel Gateway передаёт общий ответ connection;
  • Widget SDK и адаптеры каналов отображают один контракт;
  • Test Lab проверяет путь через fake OAuth без настоящего Google аккаунта;
  • после подключения MVP просит повторить команду.

7. Следующий продуктовый срез​

Состояние: требуется RFC до изменения контрактов.

  • одно пользовательское сообщение может содержать несколько действий;
  • Agent Runtime возвращает типизированный упорядоченный план, а не выполняет его;
  • каждое действие сохраняет собственные input, output, статус и идемпотентный ключ;
  • Temporal показывает понятное имя плана и результаты каждого шага;
  • политика остановки, повтора и компенсации согласуется отдельно;
  • первый пример: событие Google Calendar, затем запись в Notion.

До RFC не создаётся Notion MCP и не расширяется Action API случайными полями.

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

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