Как описать архитектуру ИИ

двадцать строк, которые экономят вечер

Что это

У ИИ нет памяти о твоём проекте. В каждом новом разговоре он знает только то, что видит прямо сейчас, — и если не видит структуру, придумывает свою. Отсюда берутся ответы вида «создайте файл helpers.py» при живой папке services/ и четвёртый по счёту способ читать настройки.

Лечится это одним коротким текстом — архитектурной справкой. Статья 3.14 говорила о файле контекста в целом: что за проект, какие команды, как запускать. Здесь — про ту его часть, которая отвечает на вопрос «как устроено» и которую стоит писать отдельно, потому что именно её ИИ нарушает чаще всего.

Как выглядит в коде

Шаблон

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

1. ЧТО ЭТО        — одно предложение, что делает программа
2. СТЕК           — язык, фреймворк, база, версии
3. СТРУКТУРА      — дерево папок, одна строка пояснения на папку
4. ЗАВИСИМОСТИ    — кто кого имеет право импортировать
5. ГДЕ ЧТО ЛЕЖИТ  — данные, настройки, секреты, логи
6. ЧЕГО НЕ ДЕЛАТЬ — решения, которые не обсуждаются

Шестой блок — самый недооценённый. Без него ИИ в каждом третьем ответе предлагает добавить библиотеку, сменить базу или «заодно отрефакторить».

Заполненный пример

ЧТО ЭТО
Телеграм-бот: подписка на погоду в выбранных городах,
утренняя рассылка.

СТЕК
Python 3.12, aiogram 3, SQLite, requests.
Запуск: python -m bot. Сервер — один, systemd.

СТРУКТУРА
bot/
├── handlers/   команды и кнопки, только разбор ввода и ответ
├── services/   логика: погода, подписки, рассылка
├── storage.py  весь доступ к базе, других обращений к БД нет
├── models.py   датаклассы City, Subscription
└── config.py   настройки через pydantic-settings

ЗАВИСИМОСТИ
handlers -> services -> storage -> models
Обратных импортов нет. models не импортирует ничего из проекта.

ГДЕ ЧТО ЛЕЖИТ
Данные: SQLite, файл data/bot.db
Настройки: переменные окружения, см. .env.example
Секреты: только в .env, в репозиторий не попадают
Логи: stdout, их забирает systemd

ЧЕГО НЕ ДЕЛАТЬ
- Не добавлять ORM и другие библиотеки без отдельного разговора.
- Не обращаться к БД из handlers напрямую.
- Не менять схему таблиц без скрипта переноса данных.
- Не добавлять async там, где его нет.

Двадцать с небольшим строк. Вставляются в начало запроса, когда задача крупная, и лежат в ARCHITECTURE.md или в файле контекста всё остальное время.

Почему это работает лучше, чем кажется

Справка снимает ровно ту неопределённость, которую ИИ иначе закрывает догадкой. Он не угадывает, где лежит доступ к базе, — написано. Не выбирает между SQLite и PostgreSQL — написано. Не придумывает имя для нового файла — есть схема.

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

Проверка, которая занимает минуту

Самый быстрый способ понять, понял ли ИИ архитектуру:

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

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

Когда справку обновлять

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

Признак, что справка устарела: ИИ делает «неправильно», но строго по написанному.

Как сказать ИИ

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

Указание про ? обязательно: без него пустоты заполняются правдоподобным вымыслом (статья 1.6).

Вот архитектурная справка проекта: <текст>.
Задача: <что нужно сделать>.
Сначала скажи, какие файлы затронешь и не нарушает ли
это правила зависимостей. Код пиши после моего «да».

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

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

На что смотреть

Справка написана ИИ и не прочитана тобой. В ней может быть описан не твой проект.

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

Справка устарела. ИИ делает по написанному, а написанное уже неправда.

Справка на три страницы. Такую не вставишь в запрос и не прочитаешь глазами; всё, что длиннее экрана, перестаёт работать.

Нет версий. «Python и телеграм-бот» — это и aiogram 2, и aiogram 3, и они несовместимы.

Справка есть, но в запросах не используется. Файл в репозитории сам себя в разговор не вставит — если только это не файл контекста, который инструмент подхватывает сам (статья 3.14).

Шпаргалка