nifodea/.agent/src/PROTOCOLS/02_DESIGN.md

Протокол 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. Модели данных

Описать основные сущности, их поля и связи:

{
  "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 обновлён