План инженерных работ
Работа идёт короткими пакетами. Каждый пакет должен быть понятен без чтения всей истории проекта.
Как проходит один пакет
- Записать одно ожидаемое поведение простыми словами.
- Добавить маленький тест и увидеть, что он падает по нужной причине.
- Написать минимальный код для прохождения теста.
- Упростить имена и код без изменения поведения.
- Запустить тесты, style checks и сборку документации.
- Обновить README или ADR, если изменились границы либо команды.
- Создать отдельный коммит с одним смыслом и передать его на ревью.
Документация и настройки 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 случайными полями.
Что смотреть на ревью
- один коммит решает одну задачу;
- тест объясняет ожидаемое поведение;
- имя можно понять с базовым английским;
- контроллер не содержит правила бизнеса;
- репозиторий не принимает решения за сервис;
- документация совпадает с кодом;
- в каркасе нет выдуманного поведения продукта.