Проблема, знакомая каждому
Большинство AI-проектов выглядят одинаково на старте и одинаково пугающе через три месяца.
Сначала был просто main.py. Потом появился utils.py. Затем — random_prompt_buried_in_a_string.py. Где-то рядом затерялись test.py (который уже сломан) и notebook_final_v3_actually_final.ipynb.
Звучит знакомо? Вы не одиноки.
Проблема не в моделях. Модели работают. Проблема в организации. В том, что промпты захардкожены в пяти местах, данные перемешаны с кодом, агенты описаны в одном гигантском файле, а проверить, работает ли система — невозможно, потому что нет даже одного теста.
Решение: четыре папки
Вот структура, которая работает для соло-разработчиков, команд из 20 человек, RAG-систем, агентов и пайплайнов:
```
ai-project/
├── prompts/
├── data/
├── agents/
└── evals/
```
Четыре папки. У каждой одна задача. Никакого смешения.
1. prompts/ — где живут промпты
Правило: один промпт — один файл. Markdown или .txt.
Что здесь хранить:
· prompts/system/ — системные промпты (роль, инструкции)
· prompts/tasks/ — промпты под конкретные задачи (извлечение сущностей, суммаризация, генерация)
· prompts/tools/ — описания инструментов для агентов
Почему это важно:
Промпты — ваш самый ценный актив. Они меняются чаще кода. Их нужно версионировать, диффить, откатывать и ревьюить. Когда промпт лежит в Python-строке внутри ноутбука — вы не можете этого сделать.
Что запрещено:
· Промпты внутри Python-строк
· Промпты в ячейках ноутбуков
· Один промпт, скопированный в пять мест
2. data/ — всё, что читает AI
Правило: данные воспроизводимы. Сырые данные никогда не редактируются вручную.
Рекомендуемая структура:
```
data/
├── raw/ # исходные файлы — только read-only
├── processed/ # результат обработки (пересоздаётся скриптом)
└── samples/ # маленькие тестовые наборы для разработки
```
Почему это важно:
Если ваши оценки упали — вы должны знать, что изменилось: модель, промпт или данные. Без разделения raw/processed вы никогда этого не узнаете.
Золотое правило:
Любое изменение данных → запуск скрипта, который заново создаёт processed/ из raw/. Никаких ручных правок в processed.
3. agents/ — артефакты агентов
Правило: агент — это не скрипт, а набор файлов.
Рекомендуемая структура:
```
agents/
├── definitions/ # конфигурации агентов (YAML/JSON)
├── skills/ # SKILL.md — описание возможностей
└── tools/ # реализации инструментов (или ссылки на src/tools)
```
Почему это важно:
В 2024–2025 годах «агент» стал реальным артефактом. У него есть своё поведение, свои инструменты, свои границы. Если всё это описано в одном файле agent.py — вы не можете переиспользовать агента, не можете протестировать его изолированно, не можете передать коллеге.
Что появляется здесь же:
· Конфиги MCP-серверов (обычно в configs/mcp/)
· Hooks и middleware
4. evals/ — самое важное, что вы будете игнорировать до первого кризиса
Правило: без этой папки у вас демо. С ней — продукт.
Рекомендуемая структура:
```
evals/
├── test_cases/ # input + expected output — ваши «юнит-тесты для AI»
├── traces/ # реальные прогоны с запросами и ответами
├── scorecards/ # метрики: точность, задержка, стоимость токенов
└── failures/ # логи того, что сломалось в продакшене
```
Почему это важнее всего:
Вы можете идеально организовать промпты, данные и агентов, но без оценок вы летите вслепую. Модель обновилась — вы не знаете, стало лучше или хуже. Промпт изменился — не знаете, ничего ли не сломалось.
Минимальный старт:
Создайте 10 ручных тест-кейсов. Напишите скрипт, который их прогоняет. Это уже лучше, чем у 90% проектов.
Чего не хватает в четырёх папках? (расширение для продакшена)
Четыре папки — это база. Для реальных систем добавьте ещё несколько:
```
ai-project/
├── specs/ # ← зачем мы это строим?
│ ├── vision.md # какую ценность создаём
│ ├── use_cases.md # что система делает, а что нет
│ └── roadmap.md # будущие сценарии
│
├── configs/ # окружение и конфигурация
│ ├── dev.yaml
│ ├── staging.yaml
│ └── prod.yaml
│
├── src/ # код, который не ноутбук
│ ├── core/ # независимая от LLM логика
│ ├── retrieval/ # векторные БД, поиск
│ ├── llm/ # клиент, кэш, телеметрия
│ ├── tools/ # реализации инструментов
│ └── orchestration/# пайплайны
│
├── api/ # FastAPI/Flask роуты
├── monitoring/ # дрейф, затраты, алерты
├── infra/ # Docker, k8s, cloud
└── tests/ # юнит-тесты (отличаются от evals!)
```
Но если вы возьмёте только четыре папки — возьмите prompts/, data/, agents/ и обязательно evals/.
Главные правила, которые нельзя нарушать
Правило Почему
Одна папка — одна ответственность Никаких utils.py, которые отвечают за всё
Один файл — одна задача Никаких god-файлов на 2000 строк
Всё в git Включая промпты и конфиги
Новый участник понимает проект за 5 минут Клонировал, открыл — всё понятно
Тест на нового разработчика:
Попросите коллегу склонировать репозиторий и найти:
· основной системный промпт
· тест-кейс для главного сценария
· конфиг агента
Всё заняло больше 10 минут? Значит, структура не работает.
Что делать прямо сейчас
Если вы начинаете новый проект:
1. Создайте четыре папки: prompts/, data/, agents/, evals/
2. Добавьте specs/vision.md — один абзац про ценность
3. Напишите 5–10 тест-кейсов в evals/ до того, как написали первую строчку кода
Если вы спасаете существующий проект:
1. Найдите все промпты в коде и вынесите в prompts/
2. Создайте папку evals/ и добавьте хотя бы 5 smoke-тестов
3. Разделите data/ на raw/ и processed/
4. Убедитесь, что проект собирается из чистого клона
Если у вас команда:
1. Добавьте в Code Review правило: «Промпты не хардкодятся»
2. Настройте CI: прогон evals/ при каждом коммите
3. Заведите привычку: новый сценарий → сначала тест-кейс, потом код
Итог
В 2023 году AI-проекты были ноутбуками.
В 2024 — Python-скриптами.
Сейчас — это системы со структурой.
Структура бесплатна. Дисциплина — это единственное, что отличает прототип от продукта.
Начните с четырёх папок.
Добавьте evals/ в первую очередь.
И спите спокойно, зная, что завтра ваша система не развалится.
Эта статья основана на реальном опыте и анализе сотен AI-проектов — от соло-разработчиков до enterprise-команд.