metaagent updated

2026-07-22 01:27:17 +03:00
parent 5afea8238c
commit 685d3262d8
31 changed files with 2820 additions and 355 deletions
@@ -0,0 +1,173 @@
+# Протокол 02: Архитектурное проектирование (DESIGN)
+
+## Цель
+
+Спроектировать архитектуру, модули, данные и интерфейсы для greenfield/scaffold-проекта на основе требований из analysis-report.
+
+## Вход
+
+- `.agent/analysis-report.md` (project_type: greenfield или scaffold)
+- `.agent/metaagent-request.md` (конфигурация сессии: adr, alternative_arch, risk_register)
+- `.agent/checkpoints.json` (фаза design: pending)
+
+## Правила
+
+1. **Реалистичность** — архитектура должна быть реализуема исполнительным агентом за 1 сессию (до 10 задач)
+2. **Документируемость** — каждый модуль, модель и интерфейс описывается в design-report.md
+3. **Тестируемость** — каждый компонент проектируется с учётом того, как его тестировать
+4. **Итеративность** — первая версия должна быть минимально рабочей (MVP), расширения — отдельными задачами
+
+## Шаги
+
+### 2.1. Технологический стек
+
+Если стек не указан в README — предложить обоснованный выбор. Если указан — зафиксировать.
+
+Для каждого компонента указать:
+- Язык и версия
+- Фреймворк / библиотека
+- База данных (движок, схема)
+- Инфраструктура (Docker, CI/CD, хостинг)
+
+### 2.2. High-level архитектура
+
+Описать общую структуру системы:
+
+- **Архитектурный паттерн** — монолит, модульный монолит, микросервисы, слоистая, луковая и т.д.
+- **Компоненты и их ответственность** — что делает каждый модуль/сервис
+- **Схема взаимодействия** — текстовое описание потоков данных
+
+Формат (text diagram):
+
+```
+[Client] → HTTP → [API Gateway] → [Auth Service]
+                                         ↓
+                              [Core Service] → [Database]
+                                         ↓
+                              [External API] → [3rd Party]
+```
+
+### 2.3. Модули проекта
+
+Разбить систему на модули/пакеты. Для каждого:
+
+| Поле | Описание |
+|---|---|
+| **Имя модуля** | `app/services/cashflow.py` |
+| **Ответственность** | Что делает |
+| **Ключевые классы/функции** | Только сигнатуры (без реализации) |
+| **Зависимости** | Какие модули нужны этому |
+| **Контракт** | Что экспортирует/предоставляет |
+
+### 2.4. Модели данных
+
+Описать основные сущности, их поля и связи:
+
+```json
+{
+  "entity": "Transaction",
+  "fields": [
+    {"name": "id", "type": "UUID", "pk": true},
+    {"name": "amount", "type": "Decimal"},
+    {"name": "date", "type": "datetime"},
+    {"name": "category_id", "type": "UUID", "fk": "Category"}
+  ]
+}
+```
+
+Если используется ORM — указать аннотации/декораторы.
+Если БД — схему таблиц, индексы, ключи.
+
+### 2.5. API интерфейсы
+
+Если проектируется API — описать эндпоинты:
+
+| Метод | Путь | Описание | Request | Response | Статусы |
+|---|---|---|---|---|---|
+| GET | /transactions | Список транзакций | ?page, ?limit | [Transaction] | 200 |
+| POST | /transactions | Создать транзакцию | CreateTransactionDTO | Transaction | 201, 400 |
+
+Если GUI — описать ключевые страницы/экраны.
+Если CLI — описать команды.
+
+### 2.6. Обработка ошибок
+
+- Стратегия ошибок: исключения, Result-тип, коды ошибок
+- Формат ошибок в API: `{ "error": "...", "code": "...", "details": {} }`
+- Логирование: какой уровень для каких событий
+
+### 2.7. Стратегия тестирования
+
+- Какие тесты нужны (unit, integration, e2e)
+- Как изолировать зависимости (mocks, fakes, testcontainers)
+- Команда запуска тестов
+
+### 2.8. Alternative Architecture (если config.alternative_arch = yes)
+
+Описать **минимум одну принципиально иную архитектуру** и причину отказа:
+
+| Критерий | Выбранная архитектура | Альтернатива |
+|---|---|---|
+| Название | Модульный монолит | Микросервисы / Событийная / и т.д. |
+| Сложность реализации | Низкая | Высокая (3+ сервиса) |
+| Масштабирование | Вертикальное | Горизонтальное |
+| Почему не выбрана | — | Избыточно для MVP |
+
+Это снижает риск архитектурной инерции: решение становится осознанным, а не единственным возможным.
+
+### 2.9. ADR (если config.adr = yes)
+
+Для каждого ключевого архитектурного решения (стек, БД, паттерн, структура модулей) создать отдельный ADR-файл:
+
+```
+.agent/layer-1/adr/001-технологический-стек.md
+.agent/layer-1/adr/002-модульный-монолит.md
+.agent/layer-1/adr/003-json-хранение.md
+```
+
+Формат — по шаблону `TEMPLATES/adr-NNNN.md`.
+
+### 2.10. Risk Register (если config.risk_register = yes)
+
+Создать `.agent/layer-1/risk-register.md` по шаблону `TEMPLATES/risk-register.md`:
+
+| # | Assumption | Impact if wrong | Mitigation | Review trigger |
+|---|---|---|---|---|
+
+Задокументировать **неявные допущения**, на которых держится архитектура. Это даёт future-агентам знать, что можно пересматривать в первую очередь.
+
+### 2.11. Группировка в задачи
+
+На основе спроектированных модулей и моделей предварительно наметить группировку в задачи (по модулям). Это будет входом для DECOMPOSITION.
+
+```
+T1: Инициализация проекта + зависимости
+T2: Модель данных (сущности, миграции)
+T3: Cashflow Service (core logic)
+T4: API endpoints
+...и т.д.
+```
+
+## Выход
+
+- `.agent/design-report.md` по шаблону `TEMPLATES/design-report.md`
+- `.agent/layer-1/adr/*.md` (если adr=yes)
+- `.agent/layer-1/risk-register.md` (если risk_register=yes)
+- Предварительная группировка задач (для передачи в DECOMPOSITION)
+
+Обновить checkpoints.json: `phases.design = "completed"`.
+
+## Критерии завершения фазы
+
+- [ ] Технологический стек определён
+- [ ] High-level архитектура описана
+- [ ] Модули и их ответственность описаны
+- [ ] Модели данных спроектированы
+- [ ] API/интерфейсы описаны (если применимо)
+- [ ] Стратегия тестирования определена
+- [ ] Alternative Architecture описана (если config требует)
+- [ ] ADR созданы (если config требует)
+- [ ] Risk Register создан (если config требует)
+- [ ] Задачи предварительно сгруппированы
+- [ ] `.agent/design-report.md` создан
+- [ ] checkpoints.json обновлён