Архитектура промптов: Как я строю "конвейер создания кода" через документы, цепочки и ИИ-агентов

Если вы не можете описать систему на бумаге, вы не сможете написать её в коде. А если вы не можете описать задачу для ИИ в цепочке промптов — вы просто играете в лотерею с генеративными моделями.

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

Спойлер: без правильно написанного ТЗ и Технической Спецификации (ТС) никакой AI не спасет проект. Но с ними — AI становится вашим лучшим архитектором.

🧩 Проблема «промпта-близнеца» Большинство разработчиков (и даже я на старте) подходят к ИИ так:

Открывают чат.

Пишут: «Сделай мне фичу X».

Получают код.

Вставляют его в проект.

... и через три часа переписывают всё руками, потому что код не учитывал 99% реальных требований.

Почему так происходит? Потому что ИИ не экстрасенс. Он не знает вашего бизнес-контекста, архитектурных ограничений, стеков, договоренностей с заказчиком и edge-cases, которые вы выявили за годы опыта.

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

📄 Документы как источник архитектуры промптов В своем портфолио я предлагаю клиентам полный цикл: от идеи до работающего продукта. И этот цикл базируется на четырех ключевых документах. Я создаю их сам или с помощью ИИ, но всегда — прежде чем написать первую строку кода.

Вот как выглядит мой «конвейер»:

1️⃣ Техническое Задание (ТЗ) Что это: Ответ на вопрос «ЧТО мы делаем?». Описание бизнес-потребности, пользовательских сценариев, функциональных требований без привязки к технологиям. Как я использую ИИ: Я даю ИИ сырые заметки, мысли, требования заказчика и говорю:

Структурируй это в формат ТЗ. Разбей на: Цели, Целевую аудиторию, Функциональные требования (по приоритетам МоСкоВ), Нефункциональные требования (производительность, безопасность, доступность). Исключи любые технологические решения — только бизнес-логика.

2️⃣ Техническое Описание (или Техническая Спецификация — ТС) Что это: Ответ на вопрос «КАК это будет устроено?». Проектирование системы: выбор технологий, архитектура модулей, схема БД, API-эндпоинты, описание интеграций, безопасность. Это моя первая "архитектурная проба пера". Как я использую ИИ: Я загружаю в ИИ готовое ТЗ и говорю:

На основе ТЗ спроектируй архитектуру. Выбери технологический стек (я использую React/Node.js/PostgreSQL/Redis, но предложи обоснование). Опиши все сущности, их связи, ключевые эндпоинты Rest API. Опиши, как мы будем обеспечивать производительность (кэширование, индексы). Предложи структуру папок проекта.

3️⃣ Дорожная Карта (Roadmap) Что это: Ответ на вопрос «В какой последовательности и за какой срок мы это сделаем?». Разбивка на этапы, вехи, спринты. Это управление ожиданиями и ресурсами. Как я использую ИИ: Я загружаю ТЗ и ТС и говорю:

Разбей реализацию на этапы по 2 недели. Выдели: настройка инфраструктуры, создание моделей данных, реализация авторизации, реализация основного функционала, интеграция платежей, тестирование, деплой. Оцени трудоемкость в человеко-часах (обосновав).

4️⃣ Юридический Договор Что это: Ответ на вопрос «Каковы правила игры?». Ответственность, сроки, оплата, авторские права, конфиденциальность. Как я использую ИИ: Я даю ИИ шаблон договора и говорю:

Адаптируй этот шаблон под условия ТЗ и Дорожной карты. Пропиши ответственность сторон, гарантии, порядок приемки работ. Убедись, что юридическая терминология корректна для РФ.

🔗 Цепочки промптов: Когда один промпт — это слишком мало Теперь самое интересное. Когда у меня есть ТЗ и ТС, я не захожу в Cursor и не прошу «напиши весь бэкенд». Я создаю цепочку промптов, где каждый следующий промпт опирается на результат предыдущего. Это позволяет построить систему без противоречий.

Пример цепочки для модуля "Когорты" в Re:Coursia:

Промпт 1 (Планировщик моделей):

Вот ТС проекта. На основе описанных сущностей (Курс, Когорта, Пользователь, Прогресс) спроектируй схему PostgreSQL. Напиши миграцию для создания таблиц, включая индексы по внешним ключам и полям сортировки. Объясни выбор типов данных для каждого поля.

Промпт 2 (Архитектор бизнес-логики):

Отлично. Теперь на основе этих таблиц опиши сервисный слой на TypeScript (Node.js/Express). Создай класс CohortService с методами: createCohort, addUserToCohort, getCohortProgress. Реализуй транзакции, чтобы добавление пользователя в когорту атомарно обновляло две таблицы (Cohort и UserCohort). Используй паттерн Repository.

Промпт 3 (Контроллер и API):

Теперь напиши REST-контроллер для этих методов. Опиши валидацию входных данных (Joi/Zod), обработку ошибок и возврат стандартизированных ответов (code, message, data). Используй HTTP-статусы: 201, 400, 404, 500.

Промпт 4 (Тесты):

Напиши интеграционные тесты для CohortController с использованием Supertest. Покрой сценарии: успешное создание, попытка создать с невалидными данными, попытка добавить пользователя в несуществующую когорту. Используй тестовую БД и транзакции для отката после каждого теста.

Промпт 5 (Документация):

Сгенерируй OpenAPI (Swagger) спецификацию для созданных эндпоинтов, используя комментарии из кода контроллера.

Что происходит: На выходе я получаю не разрозненные куски кода, а связный модуль, где модель, бизнес-логика, API, тесты и документация согласованы между собой.

🧠 Мой секретный ингредиент: "Архитектурный промпт" В каждом проекте у меня есть один супер-важный промпт, который я использую перед всей цепочкой. Я называю его «Установка контекста» или «Архитектурный манифест».

Вот как он выглядит (привожу реальный пример из Re:Coursia):

Ты — ведущий архитектор ПО с 15-летним опытом. Ты работаешь над образовательной платформой Re:Coursia. Вот её ключевые принципы: - Чистая архитектура (Domain-Driven Design) — бизнес-логика не должна зависеть от фреймворков. - Мы используем паттерны: Репозиторий, Сервис, Фабрика. - Все ошибки должны быть типизированы (custom Error classes). - Все функции должны быть покрыты TypeScript строго (без any). - Мы используем функциональное программирование где это упрощает читаемость. - Безопасность: все входные данные проходят валидацию и санитизацию. - Производительность: Критические запросы должны выполняться <100 мс. - При принятии решений всегда аргументируй выбор и предлагай альтернативы. * Теперь, имея этот контекст, ты будешь генерировать код, соответствующий этим стандартам. Все последующие промпты — это часть этого проекта.

После этого промпта я могу давать команды вроде «Реализуй модуль X», и ИИ автоматически будет применять мои архитектурные правила. Это как будто я нанял джуниора, которому уже объяснил все Code Style и Architecture Guidelines.

💎 Почему это работает и как начать Этот подход работает, потому что он убирает неопределенность. ИИ перестает гадать. Он получает четкие инструкции, формальные документы и архитектурные ограничения. Он становится не «генератором кода», а генератором решений в рамках заданной системы.

Как начать внедрять это прямо сейчас:

Напишите свой «Архитектурный манифест». Опишите свой идеальный проект: правила, паттерны, стек, подходы к безопасности. Сохраните это в файл ARCHITECTURE.md.

Прежде чем кодить, документируйте. Заставьте себя (или ИИ) написать ТЗ и ТС. Даже для пет-проекта. Это дисциплинирует мышление.

Создайте шаблоны промптов. У вас должно быть 5-10 готовых промптов для типовых задач: создание модели, создание CRUD, написание тестов, рефакторинг.

Практикуйтесь в декомпозиции. Не просите ИИ сделать сразу всё. Разбивайте задачу на микрозадачи и давайте их цепочкой.

И главное: всегда проверяйте результат. ИИ гениален в 80% случаев, но дьявол, как всегда, в деталях. Ваша роль — контроль, ревью и принятие финальных архитектурных решений.