Хардкодинг PRO • Гайд №06

Архитектура ИИ-проекта и карта данных

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

Главное правило курса: тебе не надо запоминать архитектуру. Твоя работа - поставить цель, ограничения и критерии. ИИ должен построить карту системы, объяснить её простыми словами, сохранить в проекте и обновлять по мере изменений.

Что пройдём

1. Кто должен помнить систему 2. Шесть слоёв проекта 3. Карта движения данных 4. Источник истины 5. Пример Hermes 6. Память проекта 7. Промпты для ИИ 8. Архитектурный аудит 9. Чек-лист

Источники и дата проверки · 10.10.2026

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

Карту данных и архитектуру ИИ предлагает как проектную гипотезу; пользователь или владелец продукта принимает решения после проверки. Работа ИИ не заменяет тестирование, резервное копирование и контроль доступа.

1. Не держи архитектуру в голове

Новичок часто пытается помнить всё сам: где база, какой endpoint вызывает модель, куда сохраняются файлы, что запускается на VPS, где лежат настройки. Это тупиковый путь. Чем проект больше, тем быстрее человек становится единственной точкой знания.

Ты отвечаешь за

Цель продукта, приоритеты, ограничения, деньги, качество результата и финальные решения.

ИИ отвечает за

Карту модулей, связи, зависимости, описание данных, документацию, актуализацию схемы и восстановление контекста перед работой.

Правильный навык: не помнить архитектуру, а уметь в любой момент спросить ИИ: «объясни мне текущую систему, покажи слабые места и скажи, что делать дальше».

2. Шесть слоёв ИИ-проекта

У большинства прикладных ИИ-сервисов есть одни и те же смысловые слои. Стек может меняться, но вопросы почти всегда одинаковые.

1. ПользовательКто получает ценность и какой сценарий запускает.

2. ИнтерфейсTelegram, веб, мобильное приложение, админка, API.

3. Бизнес-логикаПравила продукта, статусы, расчёты, маршрутизация, ограничения.

4. AI-слойМодели, промпты, агенты, RAG, tool calls, fallback-модели.

5. ДанныеБаза, файлы, память, векторное хранилище, логи.

6. ИнфраструктураVPS, Docker, домен, reverse proxy, очереди, мониторинг, CI/CD.

Не выбирай стек по памяти. Опиши задачу ИИ, дай ему ограничения проекта и попроси предложить минимальную архитектуру для MVP. Затем отдельно попроси раскритиковать собственное решение.

3. Карта движения данных

Архитектура становится понятной, когда ты можешь проследить один реальный запрос от начала до конца. Это и есть поток данных (Data Flow).

Пользователь
отправляет запрос

→

Интерфейс
принимает и валидирует

→

Backend
решает, что делать

→

AI
обрабатывает

→

Данные
читаются или сохраняются

→

Ответ
возвращается пользователю

Но реальный проект сложнее одной стрелки. Поэтому ИИ должен ответить: откуда данные пришли, где преобразовались, что сохранилось, кто имеет право изменять запись, что происходит при ошибке и можно ли воспроизвести результат.

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

4. Источник истины: один тип данных - одно главное место

Источник истины (главное место хранения) - место, которое считается официальным состоянием конкретных данных. Копии допустимы, но должно быть понятно, какая версия главная.

Тип данных	Нормальный источник истины	Что часто делают неправильно
Пользователи и подписки	PostgreSQL / CRM	часть в JSON, часть в таблице, часть в Telegram
Файлы	S3 / Object Storage	хранить важные файлы внутри контейнера
Знания для RAG	исходные документы + индекс	считать векторную БД единственной оригинальной копией
Секреты	env / Secret Manager / Vault	ключи в коде или Git
Логи	централизованная система логирования	искать ошибки по разным терминалам

ИИ должен сам построить DATA_MAP.md: тип данных → кто создаёт → где хранится → кто читает → кто изменяет → backup → срок жизни → риски.

5. Пример: Telegram-бот / Hermes

Возьмём понятный живой AI-ассистент. Пользователь пишет в Telegram. Bot/Telethon принимает событие. Backend определяет сценарий. ИИ-модель формирует ответ. Память и RAG дают контекст. База хранит состояние. Логи позволяют понять, что происходило. VPS обеспечивает работу 24/7.

Важно

Telegram не должен становиться базой данных только потому, что сообщения там уже есть.

Важно

ИИ-модель не должна решать, где хранятся данные. Это ответственность архитектуры.

Важно

Если модель или внешний API недоступны, система должна иметь понятное поведение.

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

6. Память проекта: файлы, которые должен вести ИИ

Архитектура должна жить не в твоей голове и не в старом сообщении чата. Она должна лежать рядом с кодом и обновляться вместе с ним.

ARCHITECTURE.mdЧто за система, основные компоненты, ответственность модулей, инфраструктура и внешние интеграции.

DATA_MAP.mdКакие данные существуют, где хранятся, кто их меняет и какой источник считается главным.

SYSTEM_MAP.mdСвязи между компонентами, сервисами и зависимостями. Удобно хранить Mermaid-схему.

README.mdКак запустить проект, проверить его и быстро войти в контекст.

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

7. Готовые промпты для ИИ

Тебе не надо вручную чертить схему. Ниже набор промптов, которым можно передать архитектурную работу ИИ.

Промпт №1. Спроектировать архитектуру проекта

Ты выступаешь как AI-архитектор проекта.

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

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

Затем:
1. Сформулируй цель продукта и основного пользователя.
2. Выдели 5-8 ключевых модулей.
3. Для каждого модуля объясни его ответственность простыми словами.
4. Покажи связи и зависимости между модулями.
5. Опиши основные внешние интеграции и API.
6. Определи, где живут данные каждого типа.
7. Назначь один главный источник истины для каждого типа данных.
8. Опиши путь данных от входа пользователя до ответа и сохранения результата.
9. Отдели бизнес-логику, AI-логику, данные и инфраструктуру.
10. Предложи минимальную архитектуру для MVP и отдельно то, что нужно только после роста.
11. Укажи слабые места, риски и места, где архитектуру можно упростить.
12. В конце дай следующий конкретный шаг.

Результат оформи в двух уровнях:
- сначала простое объяснение для владельца проекта;
- затем техническую схему для разработчика/ИИ-кодера.

Не усложняй систему ради красоты. Если что-то можно сделать проще, предложи простой вариант.

Промпт №2. Построить карту данных

Ты отвечаешь за карту данных проекта. Не пиши код.

На основе описания проекта создай DATA_MAP.md.

Для каждого типа данных укажи:
1. Название данных.
2. Кто их создаёт.
3. Где они появляются впервые.
4. Где они должны храниться.
5. Какой источник является главным источником истины.
6. Кто может читать данные.
7. Кто может изменять данные.
8. Как долго их нужно хранить.
9. Нужно ли резервное копирование.
10. Содержат ли данные секреты или персональные данные.
11. Как они передаются между сервисами.
12. Что произойдёт при потере или дублировании этих данных.

Отдельно найди:
- дублирующиеся хранилища;
- данные без понятного владельца;
- данные, которые хранятся не там;
- секреты, которые могут попасть в Git;
- отсутствие backup/restore;
- зависимости, которые могут сломать проект.

В конце предложи более простую и надёжную карту данных.

Промпт №3. Создать и поддерживать память проекта

Изучи текущий репозиторий и создай или обнови проектную память.

Тебе нужно поддерживать четыре файла:
1. ARCHITECTURE.md - общая архитектура, модули, ответственность, интеграции и инфраструктура.
2. DATA_MAP.md - типы данных, источники истины, хранилища, чтение/запись, резервное копирование.
3. SYSTEM_MAP.md - связи и зависимости между модулями, сервисами и внешними системами.
4. README.md - как запустить проект, проверить его и понять основные компоненты.

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

Промпт №4. Провести архитектурный аудит

Проведи архитектурный аудит проекта до следующего этапа кодинга.

Не изменяй код, пока не закончишь аудит.

Проверь:
1. Понятна ли цель проекта и текущего релиза.
2. Есть ли чёткие границы модулей.
3. Нет ли двух модулей, которые делают одно и то же.
4. Не смешаны ли UI, бизнес-логика, работа с данными и AI-вызовы.
5. Для каждого типа данных есть ли один источник истины.
6. Понятен ли полный путь данных.
7. Есть ли неявные зависимости между сервисами.
8. Есть ли единые точки отказа.
9. Как система ведёт себя при timeout, недоступном API и ошибке AI-модели.
10. Где находятся секреты и конфигурация.
11. Есть ли backup и понятный путь восстановления критичных данных.
12. Есть ли логирование и health-checks для ключевых компонентов.
13. Не переусложнена ли архитектура для текущего MVP.
14. Совпадают ли ARCHITECTURE.md, DATA_MAP.md и SYSTEM_MAP.md с кодом.

Для каждой проблемы дай:
- серьёзность: критично / важно / потом;
- почему это проблема;
- самое простое исправление;
- что проверить после исправления.

В конце дай вердикт: ГОТОВО К КОДИНГУ / НУЖНА ДОРАБОТКА / СТОП.

Промпт №5. ИИ как навигатор проекта

Работай как техническая память и навигатор проекта.

Я не хочу держать архитектуру и весь контекст в голове. Каждый раз перед работой сам восстанови контекст из репозитория и проектных файлов.

Перед началом:
1. Прочитай README.md, ARCHITECTURE.md, DATA_MAP.md и SYSTEM_MAP.md, если они существуют.
2. Сверь их с фактическим кодом.
3. Определи текущее состояние проекта.
4. Назови один ближайший проверяемый шаг.
5. Объясни простыми словами, зачем именно он нужен.

После выполнения задачи:
6. Проверь результат.
7. Обнови затронутую документацию.
8. Зафиксируй, что изменилось в системе и данных.
9. Назови следующий шаг.
10. Не заставляй меня запоминать детали, которые можешь хранить и восстанавливать сам.

Если документация устарела, сначала предложи её синхронизировать.

Промпт №6. Безопасно выполнить одну архитектурную задачу

Выполни одну архитектурно ограниченную задачу в существующем проекте.

Перед изменениями:
1. Изучи ARCHITECTURE.md, DATA_MAP.md и SYSTEM_MAP.md.
2. Найди фактические файлы и модули, которых касается задача.
3. Покажи краткий план и назови, что НЕ будешь трогать.

Во время реализации:
4. Не меняй архитектуру вне текущей задачи без необходимости.
5. Не создавай новое хранилище данных, если уже существует источник истины.
6. Не дублируй бизнес-логику.
7. Не добавляй новый сервис, если задача решается существующим слоем.
8. Сохраняй обратную совместимость, если нет прямого требования её нарушить.

После:
9. Запусти релевантные тесты.
10. Проверь путь данных end-to-end.
11. Обнови архитектурные документы, если схема реально изменилась.
12. Покажи список изменённых файлов, доказательства проверки и следующий шаг.

Если видишь архитектурный конфликт, остановись и сначала объясни его.

8. Архитектурный аудит перед кодингом

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

ИИ проверяет

модули, связи, путь данных, источник истины, интеграции, секреты, точки отказа, backup, логи, масштабирование.

Ты проверяешь

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

Принцип: хорошая архитектура для MVP чаще проще, чем хочется AI-модели. Проси ИИ доказывать необходимость каждого нового сервиса.

Практика: сделай карту своего проекта через ИИ

Опиши проект в 3-5 предложениях. Не пытайся сразу перечислить технологии.

Запусти промпт №1. Пусть ИИ предложит архитектуру и объяснит её простыми словами.

Запусти промпт №2. Получи карту данных и источники истины.

Запусти промпт №3. Пусть ИИ создаст ARCHITECTURE.md, DATA_MAP.md, SYSTEM_MAP.md и обновит README.

Запусти промпт №4. Попроси ИИ найти слабые места до кодинга.

Только потом переходи к реализации. Пусть AI-кодер работает по одному проверяемому изменению и сам обновляет память проекта.

Итог урока: сильный вайбкодер не тот, кто помнит каждый сервис. Сильный вайбкодер строит среду, в которой ИИ сам знает карту системы, видит данные, обновляет документацию и каждый раз возвращает человека в нужный контекст.

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

Архитектура ИИ-проекта и карта данных

Что пройдём

1. Не держи архитектуру в голове

Ты отвечаешь за

ИИ отвечает за

2. Шесть слоёв ИИ-проекта

3. Карта движения данных

4. Источник истины: один тип данных - одно главное место

5. Пример: Telegram-бот / Hermes

Важно

Важно

Важно

6. Память проекта: файлы, которые должен вести ИИ

7. Готовые промпты для ИИ

Промпт №1. Спроектировать архитектуру проекта

Промпт №2. Построить карту данных

Промпт №3. Создать и поддерживать память проекта

Промпт №4. Провести архитектурный аудит

Промпт №5. ИИ как навигатор проекта

Промпт №6. Безопасно выполнить одну архитектурную задачу

8. Архитектурный аудит перед кодингом

ИИ проверяет

Ты проверяешь

9. Интерактивный чек-лист

Практика: сделай карту своего проекта через ИИ

Непонятные слова простыми словами