Урок 3.1. Architecture как ограничение пространства решений

Зачем это нужно

Во втором модуле мы научились описывать behavior через specification. Но specification отвечает в первую очередь на вопрос "что должно быть построено". Следующий вопрос - "в каких архитектурных границах это можно строить".

AI особенно нуждается в architecture constraints. Человек-разработчик часто помнит негласные правила проекта: где находится бизнес-логика, какие зависимости запрещены, как принято оформлять API, где живут adapters, какие модули нельзя трогать. Агент этого не знает, пока правила не находятся в контексте или не закреплены проверками.

Без архитектуры агент может каждый раз выбирать новое решение:

добавить business logic в controller;
напрямую обратиться к database из UI handler;
создать второй email service рядом с существующим;
обойти domain layer ради быстрого fix;
смешать validation, persistence и orchestration в одном файле.

Код может даже пройти локальные тесты, но система начнет расползаться. Поэтому architecture в agentic development - это не украшение, а safety mechanism.

Основная идея

Architecture ограничивает пространство решений агента.

В обычной разработке architecture помогает людям координировать изменения. В AI-разработке она нужна еще сильнее, потому что агент не обладает стабильной проектной памятью и может выбирать "правдоподобный" подход каждый раз заново.

Формула урока:

Specification говорит: что должно работать.
Architecture говорит: где и как это допустимо разместить.

Пример:

Specification:
Пользователь может запросить reset password по email.

Architecture:
HTTP controller не генерирует token сам.
Controller вызывает AuthService.
AuthService использует ResetTokenRepository.
Email отправляется через existing EmailService.

Если в specification написано только behavior, агент может реализовать его технически неверно для данного проекта. Architecture сужает допустимые варианты.

Ключевые термины

Термин	Значение
Architecture	Набор решений, структур и ограничений, определяющих устройство системы.
Module	Логическая часть системы с понятной ответственностью.
Boundary	Граница между модулями, слоями или внешними системами.
Layer	Уровень приложения: controller, service, repository, database, UI, domain и т.д.
Dependency Direction	Разрешенное направление зависимостей между слоями и модулями.
Ownership	Ответственность модуля за данные, бизнес-логику или API.
Interface	Контракт взаимодействия между частями системы.
Data Flow	Путь данных через систему.
Architecture Drift	Постепенное отклонение кода от согласованной архитектуры.

Architecture как карта разрешенных решений

Агенту недостаточно знать, что нужно реализовать. Ему нужно знать, какие пути запрещены.

Пример layered architecture:

HTTP Controller
      ↓
Application Service
      ↓
Repository
      ↓
Database

Разрешено:

controller -> service
service -> repository
repository -> database

Запрещено:

controller -> database
controller -> email provider SDK
repository -> HTTP request
UI -> database

Для человека это может быть очевидно. Для агента это должно быть явно доступно.

Схема layers и boundaries

flowchart TD UI[Frontend UI] --> API[HTTP API / Controllers] API --> APP[Application Services] APP --> DOMAIN[Domain Logic] APP --> REPO[Repositories] REPO --> DB[(Database)] APP --> EMAIL[Email Service Adapter] EMAIL --> EXT[External Email Provider] API -. forbidden .-> DB UI -. forbidden .-> DB REPO -. forbidden .-> EXT

На такой схеме важно показывать не только разрешенные пути, но и запрещенные shortcuts. Именно shortcuts часто появляются в AI-generated code, когда агент оптимизирует локальную задачу.

Что агент должен знать об архитектуре

Для implementation task агенту не нужна вся история архитектуры проекта. Нужны факты, которые влияют на текущее изменение.

Минимальный набор:

Тип знания	Пример
Modules	Auth, Users, Email, Audit
Boundaries	Auth не пишет напрямую в Email provider, только через EmailService
Layers	Controller -> Service -> Repository
Ownership	Auth owns password reset token lifecycle
Interfaces	EmailService.sendPasswordReset(user, token)
Data flow	Request -> AuthController -> AuthService -> ResetTokenRepository -> EmailService
Dependencies	Auth can depend on Email interface, Email must not depend on Auth internals
Constraints	Не менять public API без approval

Эти факты могут жить в:

docs/architecture/architecture.md;
ADR;
project rules;
feature design.md;
task constraints;
review checklist;
static checks.

Specification vs architecture

Эти уровни легко смешать.

Вопрос	Specification	Architecture
Что описывает	Expected behavior	Structure and constraints
Пример	Expired token returns `TOKEN_EXPIRED`	Token validation lives in AuthService
Проверка	Acceptance criteria, tests	Review, static checks, architecture tests
Кто использует	Product, QA, agent, reviewer	Developers, agents, reviewers, CI
Риск при отсутствии	Agent реализует не то поведение	Agent реализует поведение не там и не так

Оба уровня нужны. Specification без architecture может привести к working mess. Architecture без specification может привести к красивой системе, которая решает не ту задачу.

Пример: boundaries для Password Reset

Feature:

Пользователь может запросить password reset и установить новый пароль по token.

Возможные modules:

Auth
Users
Email
Audit
RateLimit

Границы:

Module	Ответственность
Auth	Password reset token lifecycle, password update, auth-related validation
Users	User identity, account status, user lookup
Email	Отправка email через provider
Audit	Запись security-sensitive событий
RateLimit	Ограничение частоты запросов

Data flow:

sequenceDiagram participant User participant API as AuthController participant Auth as AuthService participant Tokens as ResetTokenRepository participant Email as EmailService participant Audit as AuditLog User->>API: POST /password-reset/request API->>Auth: requestPasswordReset(email) Auth->>Tokens: create reset token Auth->>Email: send reset email Auth->>Audit: record PASSWORD_RESET_REQUESTED Auth-->>API: request accepted API-->>User: HTTP 202

Architecture notes для агента:

- Controller не создает token.
- Controller не отправляет email напрямую.
- ResetTokenRepository не знает об HTTP.
- Email provider SDK доступен только через EmailService.
- Audit event создается на уровне AuthService.

Теперь агент может реализовывать task в нужном месте, а не просто "где получилось".

Как architecture попадает в context

У агента есть ограниченный context window, поэтому architecture docs нужно подавать слоями.

Для task "добавить endpoint request reset" достаточно:

1. Relevant spec sections:
   REQ/AC по request reset.

2. Relevant architecture facts:
   controller -> service -> repository;
   EmailService is the only email boundary;
   AuditLog required for security actions.

3. Relevant code:
   existing AuthController;
   existing AuthService;
   existing EmailService usage.

4. Constraints:
   do not modify login flow;
   do not add email provider dependency.

Не нужно каждый раз вставлять полный документ на 50 страниц. Но stable architecture source должен существовать, чтобы агент мог его прочитать при необходимости.

Практика: нарисовать boundaries

Возьмите feature:

Password Reset

Сделайте короткий architecture sketch:

docs/architecture/password-reset-boundaries.md

Заполните:

# Password Reset Boundaries

## Modules

## Responsibilities

## Allowed dependencies

## Forbidden dependencies

## Data flow

## Architecture notes for agent tasks

Минимальные требования:

минимум 4 modules;
минимум 5 allowed dependencies;
минимум 3 forbidden dependencies;
одна Mermaid sequence или flowchart diagram;
минимум 5 architecture notes для будущих agent tasks.

Типичные ошибки

Ошибка 1. Считать architecture только диаграммой

Диаграмма полезна, но агенту нужны конкретные constraints: что разрешено, что запрещено, где живет ответственность.

Ошибка 2. Описывать architecture слишком абстрактно

Фразы "используем clean architecture" недостаточно. Нужно показать, какие imports, calls и dependencies допустимы в этом проекте.

Ошибка 3. Не указывать forbidden paths

Агент часто выбирает shortcut. Если shortcut запрещен, его нужно назвать явно.

Ошибка 4. Давать агенту весь architecture document всегда

Для маленькой task нужен релевантный subset. Полный документ нужен для design/review, но не для каждого edit.

Ошибка 5. Путать module ownership

Если непонятно, кто owns token lifecycle или email sending, агент может размазать logic между слоями.

Критерии готовности

После урока студент должен уметь:

объяснить, почему architecture особенно важна для AI agents;
назвать modules, boundaries, layers, ownership, interfaces, data flow и dependencies;
отличить specification от architecture;
нарисовать простую layered architecture;
сформулировать allowed и forbidden dependencies;
подготовить architecture notes для agent task.

Краткое резюме

Architecture в agentic development - это карта разрешенных решений. Она помогает агенту понять, где должна жить логика, какие зависимости допустимы, какие shortcuts запрещены и какие модули отвечают за конкретные данные и процессы.

Без architecture agent может реализовать правильное behavior неправильным способом. С architecture он получает не только цель, но и границы движения.

Вопросы для самопроверки

Почему specification недостаточно для безопасной реализации?
Чем boundary отличается от module?
Почему forbidden dependencies нужно записывать явно?
Какие architecture facts нужны агенту для Password Reset task?
Чем architecture drift опасен, даже если тесты проходят?

Что дальше

В следующем уроке мы разберем ADR - Architecture Decision Record. Architecture constraints должны откуда-то появляться и где-то фиксироваться. ADR помогает записать важное решение так, чтобы будущий агент не предложил противоположную архитектуру через несколько недель.