Архитектура веб-систем: от стартапа до масштаба планеты
Часть VII: Архитектура + Искусственный интеллект — как не потерять голову
Глава 33

Промпт-инжиниринг как архитектурная дисциплина

"AI не читает твои мысли. Он читает твой промпт."

В предыдущей главе мы разобрали парадокс ускорения: AI пишет код в 2-3 раза быстрее, но без архитектурного каркаса это лишь ускоряет накопление технического долга. Теперь давай ответим на практический вопрос: как сделать так, чтобы AI-ассистент строил архитектуру, подходящую именно твоему проекту, а не «среднее арифметическое» своего обучения?

Проблема простая. Когда ты пишешь код руками — каждое решение осознанное. Ты помнишь, почему в этом проекте CQRS, а не просто CRUD. Ты знаешь, что здесь мы не используем наследование, а предпочитаем композицию. Ты помнишь, что в этом микросервисе нет прямых вызовов базы данных.

Когда пишет AI — он ничего этого не знает. Он обучен на миллионах репозиториев, и его «дефолтное» решение — это усредненное решение всех проектов в обучающей выборке. А усредненное решение — это всегда компромисс. Оно редко подходит именно твоему контексту.

Вывод: промпт — это не магия. Это архитектурная документация, которая исполняется. И относиться к ней нужно соответственно.

#1. Context is King

Представь, что ты нанял нового разработника. Сеньора, с десятью годами опыта. Ты сажаешь его за компьютер и говоришь: «Пиши код для нашего проекта». Что он сделает? Правильно — спросит: «Какой у нас стек? Какая архитектура? Какие правила?»

AI-ассистент не спросит. Он просто начнет писать. И напишет то, что считает правильным «в среднем». Твоя задача — дать ему контекст до того, как он начнет галлюцинировать архитектуру.

Domain context. Если твой проект работает в предметной области «логистика», AI должен знать термины: shipment, warehouse, route, carrier. Если это «телемедицина» — appointment, consultation, prescription, medical record. Это не просто слова — это bounded contexts из DDD. Когда ты говоришь AI: «В этом контексте слово Order означает заказ на поставку, а не заказ в интернет-магазине», — ты кодируешь ubiquitous language.

# Domain context: Logistics platform
# Terminology:
# - "Shipment" — a unit of goods being transported from A to B
# - "Route" — a planned path for a carrier
# - "Carrier" — a transportation company or driver
# - "Waybill" — a document accompanying a shipment
#
# Bounded contexts:
# - "Booking" — creating and managing shipment reservations
# - "Tracking" — real-time status updates for shipments
# - "Billing" — invoicing carriers and customers
# These are separate modules with their own data models.

Technology constraints. Какой у тебя стек? Какие версии? Какие библиотеки разрешены, какие запрещены? AI не должен гадать.

# Technology stack:
# - Python 3.12+, FastAPI, SQLAlchemy 2.x with async
# - PostgreSQL 16, Redis 7
# - Kafka for event-driven communication
#
# Rules:
# - No synchronous database calls in API handlers
# - No raw SQL unless performance-optimized
# - Only pydantic for validation (no marshmallow or attrs)
# - HTTP clients must use httpx, not requests

Architectural rules. Это самое важное. Какие паттерны ты используешь? Какие анти-паттерны запрещены? Какие принципы должны соблюдаться?

# Architectural rules:
# - CQRS: Commands change state, Queries return data — never both
# - Event-driven: services communicate via Kafka events, not HTTP calls
# - Idempotency: all command handlers must be idempotent
# - No anemic domain model: domain logic lives in domain entities, not services
# - Dependency rule: domain layer depends on NOTHING. Infrastructure depends on domain.

Style guide. Да, даже стиль кода. AI может генерировать код, который технически корректен, но выглядит чужеродным в твоем проекте.

# Style guide:
# - Repository pattern: always use repository interface in domain, implementation in infrastructure
# - Naming: use_underscores for functions, PascalCase for classes
# - File structure: one file per domain entity, one file per use case
# - No type hints? Always use type hints. No exceptions.

Когда ты собираешь все это вместе — ты получаешь не просто промпт. Ты получаешь архитектурный манифест, который AI будет исполнять строку за строкой.

#2. CLAUDE.md / AGENTS.md / инструкции проекта

В 2024-2025 годах в индустрии сформировался паттерн, который я называю «файлы-инструкции». Это файлы в корне проекта, которые описывают архитектуру, правила и конвенции специально для AI-ассистентов.

Claude Code читает CLAUDE.md (или .claude/CLAUDE.md) при старте. Cursor использует cursorrules. Copilot использует .github/copilot-instructions.md. Идея одна и та же: дать AI контекст до того, как он начнет генерировать код.

Вот пример хорошего набора инструкций для проекта с event-driven архитектурой:

# Project: Logistics Platform

## Architecture
Event-driven microservices with CQRS. Services communicate exclusively via Kafka.
API Gateway (FastAPI) handles external HTTP requests and translates them to commands/queries.

## Key Principles
1. **CQRS**: Every handler is either a Command or a Query. Never both.
2. **Eventual consistency**: Commits are local; cross-service consistency is via events.
3. **Idempotency**: All event handlers must handle duplicates gracefully.
4. **Fail-fast validation**: Validate input before processing. If invalid — reject immediately.

## Coding Conventions
- Use `@command_handler` and `@query_handler` decorators.
- Commands return `CommandResult(status, event_stream)`. Queries return `QueryResult(data)`.
- Domain events are defined in `events/` directory, grouped by aggregate.
- Use `Result[T, E]` pattern instead of exceptions for expected errors.
- No circular dependencies between modules (enforced by `import-linter`).

## Anti-patterns (never do these)
- NEVER make HTTP calls from one service to another. Use events.
- NEVER put business logic in API handlers. Handlers parse input and delegate.
- NEVER use `try-except` for flow control. Use `Result` type or explicit error handling.
- NEVER create shared libraries between services. Duplication is acceptable for bounded contexts.

## Testing
- Unit tests: domain logic only, no mocks for infrastructure.
- Integration tests: one per saga, covering the full event flow.
- Property-based testing for domain invariants.

Обрати внимание: здесь нет абстрактных «следует применять принципы SOLID». Здесь конкретные, проверяемые правила. AI может их исполнить. И — что не менее важно — их может проверить код-ревью.

Shared context через файлы памяти. В больших проектах один файл инструкций может стать слишком большим. Паттерн, который хорошо работает: разбить инструкции на несколько файлов.

.claude/
  CLAUDE.md              # Основные правила, архитектура, стек
  domain-logic.md        # Детали предметной области, ubiquitous language
  api-conventions.md     # REST/GraphQL conventions, версионирование
  event-catalog.md       # Каталог доменных событий и их схемы
  database.md            # Миграции, соглашения об именовании, N+1 rules

Каждый файл фокусируется на одном аспекте. AI может прочитать нужный по контексту. Это как главы в документации — только документация, которая реально влияет на генерируемый код.

#3. Архитектурные гвардрейлы через промпты

Файлы-инструкции — это пассивная защита. AI их читает и (в идеале) соблюдает. Но есть situации, когда нужны активные гвардрейлы — промпты, которые явно запрещают или предписывают определенное поведение.

#Negative prompts

Самый недооцененный инструмент. Сказать AI, что делать — половина дела. Сказать, чего не делать — вторая половина.

NEVER:
- Use synchronous database calls in async handlers
- Create circular dependencies between modules
- Put business logic in __init__ methods or constructors
- Catch Exception (as opposed to specific exceptions)
- Use `from module import *`
- Hardcode configuration values

Почему это работает? Потому что AI обучен на коде, где эти анти-паттерны встречаются сплошь и рядом. Если явно не запретить — он их повторит. Negative prompts срезают целые классы ошибок за одну строку.

#Constraint-based prompts

Иногда нужно не просто запретить, а наложить ограничение. Например:

- Commands return void. They don't return data. If you need data, make a Query.
- All event handlers MUST be idempotent. Check deduplication before processing.
- Every public function MUST have a type hint and a docstring.
- Migrations must be backward-compatible. No column drops without a deprecation period.

Эти ограничения не субъективны. Они либо соблюдены, либо нет. И их можно автоматически проверять.

#Review prompts

Один из самых мощных паттернов — попросить AI проверить свой же код на соответствие архитектурным правилам.

Review the following code against our architectural rules:
1. Do handlers respect CQRS? (Commands don't return data, Queries don't mutate)
2. Are all async functions properly awaited?
3. Are there any synchronous DB calls in async context?
4. Is domain logic separated from infrastructure?
5. Are event handlers idempotent?
List every violation with file:line reference.

Этот промпт превращает AI из генератора кода в код-ревьюера. И это меняет динамику: AI сначала пишет, потом проверяет себя. Мы подробнее разберем этот подход в Главе 34, а пока — запомни главное: review prompts — это самый дешевый способ поймать архитектурные violations до того, как они попали в PR.

#Промпты для разных архитектурных стилей

Один и тот же промпт не работает для всех архитектур. Вот как выглядят гвардрейлы для разных стилей.

Monolith:

- All code lives in a single deployable unit
- Module boundaries are enforced by Python packages, not services
- Shared database, shared cache — but separate schemas per module
- No network calls between modules (direct function calls only)

Modular Monolith:

- Modules communicate via interfaces, never via direct imports of internals
- Each module has its own database tables (shared database, but no cross-module queries)
- Domain events for cross-module communication
- Modules are independently testable
- Strict dependency direction: core -> modules -> adapters

Microservices:

- Each service owns its data — no direct DB access across services
- Inter-service communication only via Kafka events or API Gateway
- Each service has its own CI/CD pipeline
- No shared code between services (duplicate if needed)
- Service boundaries follow bounded contexts

Event-Driven:

- Events are the primary communication mechanism
- Event schemas are versioned and backward-compatible
- Event handlers are idempotent
- Event ordering is not guaranteed — handlers must tolerate out-of-order events
- Dead letter queue for failed events
- Event sourcing for audit-critical aggregates

Каждый набор правил отражает компромиссы конкретного стиля. AI не может угадать, какой стиль ты используешь. Ты должен сказать ему явно.

#4. Chain-of-Thought для архитектурных решений

Самая опасная вещь, которую можно попросить AI сделать — это «напиши мне микросервис для заказов». AI напишет. И это будет «средний микросервис для заказов» из обучающей выборки. Возможно, он будет работать. Возможно, нет. Но он точно не будет отражать твои архитектурные решения.

Решение: заставь AI думать, прежде чем писать код.

Chain-of-Thought (CoT) — это техника промпт-инжиниринга, при которой AI сначала рассуждает, а потом отвечает. В контексте архитектуры это означает:

Прежде чем писать код, сделай следующее:
1. **Design**: Опиши архитектурное решение. Какие компоненты нужны? Как они взаимодействуют? Какие паттерны применяются?
2. **Review**: Проверь свой дизайн на соответствие правилам проекта. Есть ли нарушения? Есть ли лучшие альтернативы?
3. **Implement**: Только после утверждения дизайна — пиши код.
4. **Verify**: Проверь код на соответствие дизайну и правилам проекта.

Вот как это выглядит в реальном промпте:

Task: Add a "cancel shipment" feature.

First, design the solution:
- What commands/events are involved?
- What happens to related aggregates (invoices, routes)?
- What are the error cases and how are they handled?
- How does idempotency work?

After design, review it against our CQRS rules and event-driven principles.

Only after review — implement.

Finally, verify that the implementation matches the design.

Let me see your design first.

Этот подход радикально меняет качество результата. Вместо того чтобы получить 200 строк кода, которые нужно ревьюить и переписывать, ты получаешь сначала страницу рассуждений, потом код, который уже обдуман.

Multi-step workflow в промптах:

Step 1: Analyze the problem
- What bounded contexts are involved?
- What existing aggregates/entities exist?
- What events already flow through the system?

Step 2: Design the solution
- Component diagram (text-based)
- Event flow
- Error scenarios
- Consistency model

Step 3: Identify trade-offs
- What are the alternatives?
- Why did you choose this approach?
- What are the downsides?

Step 4: Implementation plan
- Files to create/modify
- Order of changes

Step 5: Code
- Follow the plan
- One file at a time

Step 6: Self-review
- Check against architectural rules
- Check for violations from negative prompts

Промпты для исследования trade-offs:

You proposed using a saga pattern for the order fulfillment flow. 
Before implementing, analyze three alternatives:

Option A: Saga with choreography (current proposal)
Option B: Saga with orchestration
Option C: Two-phase commit (X/TA transaction)

For each, evaluate:
- Consistency guarantees
- Resilience to failures
- Operational complexity
- Alignment with our event-driven architecture

Recommend one with explicit reasoning.

Этот промпт заставляет AI делать то, что делает хороший архитектор — рассматривать альтернативы и принимать осознанные решения. Не просто «как сделать», а «почему именно так».

#6. Новые правила контекстного инжиниринга для Claude 5

В середине 2026 Anthropic выпустила Claude Opus 5, который изменил правила игры в промпт-инжиниринге. Ключевое: сильные модели требуют меньше правил и больше контекста.

#Сдвиг 1: От правил к суждениям (Rules → Judgment)

Со старыми моделями (Claude 3, GPT-4) работал подход: «запиши 50 правил, какие паттерны использовать, а какие нет». Каждое правило — ограничение, которое модель соблюдает, но без понимания «почему».

С Claude 5 подход изменился: вместо сотни конкретных запретов — несколько принципов и мета-правил, а модель сама применяет их по контексту.

Было (Claude 3 / GPT-4):

- Всегда используй Repository Pattern
- Никогда не используй наследование
- Все сервисы должны быть stateless

Стало (Claude 5):

- Архитектурные принципы: SRP, DIP, композиция перед наследованием
- Критические ограничения: идемпотентность для всех state changes
- Контекст проекта: bounded contexts, термины, стек

Результат: ~80% сокращение объёма system prompt. Меньше правил = меньше противоречий = выше качество.

⚠️ Caveat: Независимые измерения показывают менее драматичную разницу — в среднем около 50% сокращения. Эффект сильнее для простых правил (стиль, форматирование) и слабее для сложных архитектурных ограничений. Практический вывод: сокращайте промпт, но не выбрасывайте критически важные правила.

#Сдвиг 2: От примеров к интерфейс-дизайну (Examples → Interface Design)

Раньше лучшим способом научить AI архитектуре были примеры: «посмотри, как написан этот модуль, и делай так же». Claude 5 требует иного — вместо примеров кода достаточно описать интерфейсы и контракты.

Было: «Вот пример контроллера, сервиса и репозитория — следуй этому стилю».

Стало: «Вот спецификация API. Вот контракты между модулями. Вот модель данных. Реализуй в соответствии с принципами проекта».

Модель сама генерирует структуру, согласованную с контрактами. Примеры кода не нужны — они, наоборот, могут ограничивать модель, заставляя повторять устаревшие паттерны.

⚠️ Важный caveat: независимые измерения показывают, что разница между «правильным» промптом для Claude 5 и «средним» промптом менее драматична, чем заявляется в маркетинговых материалах Anthropic. Практический вывод: обновляйте промпты под новые модели, но не ждите чуда — базовая архитектурная дисциплина всё ещё важнее формы промпта.

#Сдвиг 3: Context window budgeting для архитектуры

Современные модели имеют контекст 200K+ токенов, но архитектурно важная информация должна быть в начале контекста, не в середине.

Практическое правило для Claude 5:

  1. System prompt (первые 2K токенов): только архитектурные принципы и критические ограничения
  2. Project context (следующие 5K): структура проекта, bounded contexts, ключевые термины
  3. Current task context (дальше): конкретная задача с референсами на соседние модули
  4. Reference (всё остальное): детальные спецификации, ADR, протоколы

Чем сильнее модель, тем меньше инструкций ей нужно. Но тем точнее должен быть контекст.

Источник: The New Rules of Context Engineering for Claude 5, июль 2026

#7. Анти-паттерны промпт-инжиниринга

Когда промпт-инжиниринг стал модным, индустрия наступила на все возможные грабли. Вот основные — чтобы ты не наступал на те же.

#«Магический промпт»

Версия, что если найти «идеальный промпт» — он решит все архитектурные проблемы раз и навсегда. Спойлер: такого промпта не существует.

Промпт — это не заклинание. Это инструкция. Как документация. Она требует поддержки, обновления, адаптации. Если ты пишешь промпт и забываешь о нем — архитектура «уплывет», и промпт станет не просто бесполезным, а вредным (он будет убеждать AI делать то, что уже неактуально).

Anti-pattern: «Я нашел идеальный system prompt для микросервисов на Reddit, скопировал, вставил — и магия случилась».

Solution: Промпты — это код. Они должны быть в репозитории, под версионированием, с историей изменений.

#Prompt rot

Архитектура проекта эволюционирует. Сегодня вы используете Kafka, завтра — RabbitMQ. Сегодня CQRS, завтра — event sourcing только для аудита. А промпт остался прежним.

Промпты устаревают так же, как код. Если ты добавил новый архитектурный принцип, но не обновил CLAUDE.md — AI будет генерировать код по старым правилам. Это незаметно, потому что код синтаксически корректен и даже работает. Но архитектурно он уже не соответствует проекту.

Anti-pattern: Написать CLAUDE.md один раз, при старте проекта, и больше никогда не открывать.

Solution: Промпты ревьюятся при каждом архитектурном ревью. Изменилась архитектура — обнови инструкции. Добавился новый паттерн — добавь гвардрейл. Удалился устаревший принцип — убедись, что он не остался в промптах.

#Over-prompting

Промпт на 500 строк, который пытается покрыть все возможные случаи. В результате AI тратит больше контекста на чтение правил, чем на генерацию кода. И начинает игнорировать правила — просто потому, что их слишком много.

Промпты — как законы. Чем их больше, тем меньше они соблюдаются. Каждое правило должно быть обосновано. Если правило не ловит реальную ошибку — удали его.

Anti-pattern: CLAUDE.md на 300 строк, где 200 строк — общие принципы программирования, которые AI и так знает.

Solution: Только специфичные для твоего проекта правила. «Не используй print()» — не нужно, AI и так знает. «Не используй синхронные вызовы в async-контексте» — нужно, потому что это специфично для твоего стека.

#Context window poisoning

Когда ты работаешь с AI в длинной сессии, контекст заполняется старыми решениями, фрагментами кода, которые уже неактуальны, и архитектурными компромиссами, которые были приняты «на время». AI начинает опираться на этот старый контекст, а не на свежие правила из CLAUDE.md.

Anti-pattern: В середине большой рефакторинг-сессии AI предлагает решение, основанное на коде, который ты удалил три часа назад. Потому что этот код все еще в контексте.

Solution:

  • Начинай новую сессию для новой архитектурной задачи
  • Используй context resets или эквиваленты в твоем AI-инструменте
  • Держи файлы-инструкции короткими и актуальными
  • Если контекст замусорился — начни заново с чистым контекстом

#Чек-лист: что должно быть в архитектурном промпте

Прежде чем написать или обновить архитектурный промпт (CLAUDE.md, cursorrules, copilot-instructions), проверь его по этому списку.

  1. Domain context: Описана ли предметная область? Есть ли bounded contexts и ubiquitous language?
  2. Technology stack: Указаны ли язык, фреймворк, база данных, очереди и их версии?
  3. Architectural style: Явно ли указан стиль (monolith/modular monolith/microservices/event-driven)?
  4. Core patterns: Какие паттерны обязательны (CQRS, Repository, Event Sourcing)? Какие запрещены?
  5. Negative rules: Есть ли явный список «never do» с объяснением, почему?
  6. Idempotency requirements: Указано ли, какие операции должны быть идемпотентными?
  7. Dependency rules: Описаны ли направления зависимостей между слоями и модулями?
  8. Consistency model: Явно ли указано, где strong consistency, где eventual?
  9. Style conventions: Naming, file structure, type hints, docstrings?
  10. Review criteria: Что проверять при код-ревью? Какие violations критичны?

Если хотя бы трех пунктов нет — твой промпт не покрывает архитектуру проекта. И AI будет додумывать сам. А его додумки — это «среднее арифметическое» всех проектов в обучающей выборке. Которое, скорее всего, не подходит твоему.

#Ключевые выводы

  1. Промпт — это исполняемая архитектурная документация. Относись к нему как к коду: версионируй, ревьюй, обновляй. Промпт, написанный год назад и забытый, хуже, чем отсутствие промпта.

  2. Negative prompts важнее positive prompts. Сказать AI, чего не делать — эффективнее, чем говорить, что делать. Запрети целые классы анти-паттернов одной строкой.

  3. Chain-of-Thought — не роскошь, а необходимость для архитектурных решений. Заставь AI спроектировать, прежде чем писать код. Многошаговый workflow (design -> review -> implement -> verify) ловит архитектурные ошибки до того, как они стали тысячей строк кода.

  4. Контекст — это король, но контекст отравляется. Архитектурные правила должны быть в файлах-инструкциях, а не в истории диалога. Начинай новую сессию для новых архитектурных задач.

  5. Нет «магического промпта». Архитектурный промпт требует постоянной поддержки, как и любой другой архитектурный артефакт. Если твоя архитектура эволюционирует — промпт должен эволюционировать вместе с ней. (Подробнее про анти-паттерны AI-assisted разработки — в Главе 37.)

  6. AI-assisted генерация интерфейсов меняет фронтенд-архитектуру. Дизайн-системы и компонентная архитектура (см. Главу 8 «Фронтенд-архитектура») становятся входными данными для промптов — качество UI, которое генерирует AI, напрямую зависит от качества вашей компонентной модели.

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