Тема: Часть 5. Первичная настройка проекта
Уровень сложности: Средний
Расчётное время изучения: 1,5–2 часа
Предварительные требования: Базовое понимание dbt и слоёв моделей (staging, intermediate, marts)
Знакомство с концепцией AI-агента как участника разработки
Понимание принципов версионирования (Git) и работы с репозиторием
Опыт работы с реляционными хранилищами данных и SQL
Понимание, что такое спецификация модели и контракт витрины
Цели обучения: Объяснить, почему первичная настройка проекта важнее в дата-проектах, чем в обычных приложениях
Создать минимальную структуру каталогов проекта согласно стандарту курса
Сформулировать пять коротких поведенческих правил агента в AGENTS.md
Различать зоны ответственности AGENTS.md и specs/tech-stack.md
Составить дорожную карту проекта по артефактам и проверочным фактам
Сформулировать Qwen-запрос для аудита каркаса проекта без изменения файлов
Проверить настройку проекта критерием «после /clear новый агент понимает проект без пересказа чата»
Обзор: Глава описывает минимальную, но обязательную первичную настройку дата-проекта, в котором AI-агент и человек работают как пара. Цель настройки — перенести память решений из чата в файлы репозитория: миссию, технологический стек, дорожную карту, спецификации моделей, заметки о проверке и отчёты ревьюера. Глава разбирает, зачем нужны директории specs/, models/ и tests/, что именно писать в AGENTS.md, чем плоха дорожная карта по слоям и какой запрос использовать, чтобы поручить агенту аудит каркаса. После главы в репозитории должны существовать AGENTS.md, specs/mission.md, specs/tech-stack.md, specs/roadmap.md, директории для спецификаций моделей, заметок о проверке и отчётов ревьюера, а также каркас dbt-проекта. Глава учит главному принципу: на этапе настройки создаются не готовые артефакты, а «места», куда эти артефакты будут попадать. Настройка закончена не тогда, когда папки созданы, а тогда, когда они начинают удерживать решения.
Ключевые концепции: Память проекта vs память чата: Память проекта — это структура папок и файлы (mission.md, tech-stack.md, roadmap.md, спецификации моделей, заметки о проверке, отчёты ревьюера). Память чата — это содержимое диалога с агентом, которое исчезает при первом /clear. До сброса контекста память чата кажется удобной, но для следующего человека и следующего ревьюера она бесполезна. Первичная настройка нужна, чтобы решения жили в файлах, а не в окне диалога.
Минимальная структура каталогов: Стандартная раскладка репозитория: specs/ (с файлами mission.md, tech-stack.md, roadmap.md и подкаталогами models/, validation/, reviewer-reports/), models/ (с подкаталогами staging/, intermediate/, marts/), tests/, AGENTS.md, dbt_project.yml, profiles.yml. На этапе настройки нужны не готовые к боевому контуру артефакты, а «места», куда будут попадать решения. Если, например, нет папки specs/validation/, проверочные факты почти наверняка останутся в чате или в описании PR.
Agents.md как поведенческий файл: Это короткий файл, который задаёт поведение агента перед изменениями: что прочитать (mission, tech-stack, roadmap, нужные спецификации), чего не делать (не раскрывать прямые PII, не менять grain, SLA и поля контракта без подтверждения), какие проверки запускать (dbt build), как отчитываться (проверочными фактами, а не обещаниями). AGENTS.md — не энциклопедия, а список поведенческих правил. Чем короче правила, тем выше шанс, что агент и человек будут ими пользоваться.
Разделение agents.md и specs: AGENTS.md описывает, как агент должен себя вести. specs/mission.md описывает, ради чего делается проект. specs/tech-stack.md описывает, какой стек разрешён и почему. specs/roadmap.md описывает, какие артефакты должны появиться. specs/models/ хранит контракты моделей. specs/validation/ хранит заметки о проверке. specs/reviewer-reports/ хранит отчёты ревьюера. Продуктовое обещание, поля контракта и приёмочные факты должны жить в specs/, а не в AGENTS.md.
Дорожная карта по артефактам: В дата-проекте дорожную карту лучше вести по доказательствам, а не по слоям. Пример плохой формулировки — «написана модель marts/customer_360.sql». Пример хорошей формулировки — «mart Customer 360 проверен ревьюером». Так видно, что «модель написана» не равно «продукт готов». Конкретный пример из главы: 1) raw/staging воспроизводимы; 2) контракт Customer 360 утверждён; 3) mart Customer 360 проверен; 4) витрины риска, кредитов и согласий проверены ревьюером; 5) доказательства релиза для практического зачёта готовы.
Слои смысла, проверки и ревью: Папки specs/models/, specs/validation/ и specs/reviewer-reports/ говорят агенту, что смысл, проверка и ревью — это отдельные слои, а не послесловие к SQL. Если этих папок нет, источник истины появится там, где удобнее агенту: в комментарии, в выводе команды, в тексте ответа. Восстановить это потом очень трудно.
Контейнеры для решений: На этапе настройки нужно создать контейнеры для решений, а не принимать сами решения. Задача — заранее договориться, где будут лежать миссия, стек, дорожная карта, спецификации, заметки о проверке и отчёты. Содержимое этих папок принимается позже, в следующих главах курса.
Qwen-запрос для аудита настройки: Запрос, который поручает агенту прочитать текущую структуру проекта, проверить наличие мест для mission, tech-stack, roadmap, спецификаций моделей, проверочных фактов, dbt-моделей и отчётов ревьюера и составить список пробелов настройки без изменения файлов. После списка пробелов можно попросить агента создать только недостающие директории и пустые шаблоны. Просить писать SQL на этом этапе нельзя.
Критерий готовности настройки: Хорошая настройка даёт простой тест: после очистки контекста новый агент должен понять, где находится миссия, какой стек разрешён, какие витрины строятся и как доказывается готовность. Если для продолжения работы нужно пересказывать чат, значит проект ещё не настроен. Настройка закончена не тогда, когда папки созданы, а когда они начинают удерживать решения.
Типичная ошибка настройки: Сразу просить агента «собери lakehouse» — это слишком широкий запрос. На этапе настройки нужно создавать контейнеры для решений, а не принимать сами решения. Такой запрос уводит агента в обсуждение стека, форматов и оркестраторов в чате, а в репозитории не появляется ни одной структурной единицы.
Практические упражнения: Название: Создание минимального каркаса проекта
Проблема: В пустом репозитории создайте следующую структуру каталогов: specs/ (с подкаталогами models/, validation/, reviewer-reports/), models/ (с подкаталогами staging/, intermediate/, marts/), tests/. Добавьте пустые файлы-заготовки: specs/mission.md, specs/tech-stack.md, specs/roadmap.md, AGENTS.md, dbt_project.yml, profiles.yml. Опишите, какие команды вы используете и в каком порядке, и поясните, почему порядок создания каталогов имеет значение для дальнейшей работы с агентом.
Решение: Шаг 1. Создайте корневые каталоги одной командой: mkdir -p specs/models specs/validation specs/reviewer-reports models/staging models/intermediate models/marts tests. Флаг -p нужен, чтобы создать вложенные директории одной командой. Шаг 2. Создайте пустые файлы-заготовки: touch specs/mission.md specs/tech-stack.md specs/roadmap.md AGENTS.md dbt_project.yml profiles.yml. Шаг 3. Зафиксируйте структуру в Git: git init && git add . && git commit -m 'scaffold: минимальная структура проекта'. Шаг 4. Объясните порядок: specs/ — это контракт, models/ — это реализация, tests/ — это проверка. Создание specs/ раньше models/ фиксирует приоритет смысла над кодом. Если сначала создать models/, агент начнёт писать SQL до того, как появятся места для миссии и спецификаций, и источник истины переедет в комментарии и ответы чата.
Сложность: intermediate
Название: Написание AGENTS.md по минимальному шаблону
Проблема: Заполните AGENTS.md пятью правилами из главы. Сформулируйте их однозначно и коротко: 1) что агент должен прочитать перед изменением dbt-моделей; 2) что нельзя раскрывать; 3) что нельзя менять без подтверждения; 4) какую команду запускать; 5) как отчитываться. Поясните, почему каждое правило должно быть коротким и почему AGENTS.md — плохое место для описания витрин.
Решение: Шаг 1. Первое правило — предварительное чтение: «Перед изменением dbt-моделей прочитай mission, tech-stack, roadmap и нужные спецификации моделей». Шаг 2. Второе правило — ограничение по PII: «Не раскрывай прямые PII-поля в marts». Шаг 3. Третье правило — запрет на тихие изменения контракта: «Не меняй grain, SLA или поля контракта без подтверждения». Шаг 4. Четвёртое правило — обязательная проверка: «Запускай dbt build, когда dbt доступен». Шаг 5. Пятое правило — формат отчёта: «Отчитывайся проверочными фактами, а не обещаниями». Шаг 6. Пояснение: правила должны быть короткими, потому что длинный AGENTS.md превращается в энциклопедию, которую никто не читает — ни человек, ни агент. Описание витрин должно жить в specs/models/, а не в AGENTS.md, потому что это продуктовое знание, а не поведение агента.
Сложность: intermediate
Название: Аудит каркаса через Qwen-запрос
Проблема: Сформулируйте запрос к AI-агенту, который должен: 1) прочитать текущую структуру проекта; 2) проверить наличие мест для mission, tech-stack, roadmap, спецификаций моделей, проверочных фактов, dbt-моделей и отчётов ревьюера; 3) составить список пробелов настройки без изменения файлов. Затем сформулируйте второй запрос, который на основе списка пробелов создаёт только недостающие директории и пустые шаблоны, без написания SQL и без заполнения содержимого спецификаций.
Решение: Шаг 1. Первый запрос (только чтение): «Прочитай текущую структуру проекта. Проверь, есть ли места для mission, tech-stack, roadmap, спецификаций моделей, проверочных фактов, dbt-моделей и отчётов ревьюера. Составь список пробелов настройки. Файлы не меняй». Шаг 2. Второй запрос (только контейнеры): «На основе списка пробелов создай только недостающие директории и пустые шаблоны. SQL не пиши, содержимое спецификаций не заполняй». Шаг 3. Объяснение: первый запрос отделён от мутаций, поэтому агент не сможет случайно перезаписать существующие файлы и команда увидит чистый список пробелов. Второй запрос ограничен созданием пустых контейнеров, поэтому агент не уйдёт в написание моделей и обсуждение стека раньше времени. Это и есть принцип «контейнеры для решений, а не сами решения».
Сложность: intermediate
Название: Составление дорожной карты по артефактам
Проблема: Для вымышленного банковского дата-проекта «Customer 360» составьте дорожную карту из пяти пунктов. Каждый пункт должен называть артефакт или проверочный факт, а не слой. Объясните, почему формулировка «написана модель marts/customer_360.sql» — плохая, а «mart Customer 360 проверен ревьюером» — хорошая. Добавьте к каждому пункту ожидаемое доказательство (где оно будет лежать).
Решение: Шаг 1. Пункт 1: «raw/staging воспроизводимы» — доказательство лежит в specs/validation/ (отчёт о воспроизводимом запуске) и в tests/ (пройденные тесты dbt build). Шаг 2. Пункт 2: «контракт Customer 360 утверждён» — доказательство лежит в specs/models/customer_360.md с подписью владельца витрины. Шаг 3. Пункт 3: «mart Customer 360 проверен» — доказательство лежит в specs/validation/customer_360.md (отчёт о проверке полей, grain и SLA). Шаг 4. Пункт 4: «витрины риска, кредитов и согласий проверены ревьюером» — доказательство лежит в specs/reviewer-reports/. Шаг 5. Пункт 5: «доказательства релиза для практического зачёта готовы» — это сборный пункт, ссылающийся на все предыдущие папки. Шаг 6. Объяснение: формулировка «написана модель» описывает действие, а не результат; формулировка «проверен ревьюером» описывает доказательство. Дорожная карта по артефактам сразу показывает, какие доказательства ещё не собраны и где они должны лежать.
Сложность: intermediate
Название: Разделение зон AGENTS.md и specs
Проблема: Вам даны четыре утверждения: 1) «PostgreSQL — разрешённый слой хранения, потому что уже используется в банке»; 2) «Агент не должен запускать dbt build без прочтения mission.md»; 3) «Customer 360 содержит поля customer_id, full_name, birth_date, risk_score»; 4) «Каждый PR по витрине должен сопровождаться отчётом ревьюера». Распределите их по правильным файлам в репозитории и поясните, почему AGENTS.md — плохое место для утверждения 1 и хорошее для утверждения 2.
Решение: Шаг 1. Утверждение 1 («PostgreSQL разрешён, потому что используется в банке») идёт в specs/tech-stack.md — это описание разрешённого стека и обоснование выбора, а не поведение агента. Шаг 2. Утверждение 2 («агент не должен запускать dbt build без прочтения mission.md») идёт в AGENTS.md — это правило поведения агента перед действием. Шаг 3. Утверждение 3 («Customer 360 содержит поля…») идёт в specs/models/customer_360.md — это контракт конкретной модели, а не правило поведения. Шаг 4. Утверждение 4 («каждый PR должен сопровождаться отчётом ревьюера») идёт в AGENTS.md как поведенческое правило для агента и в specs/roadmap.md как требование процесса. Шаг 5. Объяснение: AGENTS.md — плохое место для утверждения 1, потому что оно описывает стек, а не поведение; смешение рождает раздутый AGENTS.md, который агент перестаёт читать. AGENTS.md — хорошее место для утверждения 2, потому что это правило «перед действием прочитать», то есть поведение.
Сложность: advanced
Кейсы: Название: Банковский Customer 360: как чат «съел» забытое ограничение по PII
Сценарий: Команда из трёх аналитиков и AI-агента строила витрину Customer 360 для риск-отдела банка. В начале проекта команда договорилась в чате, что поле email нельзя выгружать в marts без маскирования, а grain витрины — «один клиент — одна строка на дату среза». Договорённости остались в окне диалога. Через две недели в репозиторий пришёл новый аналитик и подключил к агенту свежий контекст.
Задача: После команды /clear агент не нашёл в проекте упоминаний о маскировании email и о grain витрины. Он сгенерировал mart, в котором email выводился в открытом виде, а grain размылся до «одна строка на каждую операцию клиента» — потому что так было удобнее для текущего запроса риск-отдела. SQL проходил все тесты dbt build и давал зелёный результат, но нарушал договорённости, которые жили только в чате. Риск-отдел получил витрину с PII и неверным grain, что делало любые агрегаты бессмысленными.
Решение: Команда остановила релиз, восстановила историю чата вручную и зафиксировала две новые папки в репозитории: specs/models/customer_360.md с grain, SLA, списком полей и явным запретом на открытый email, и specs/validation/ для заметок о проверке. В AGENTS.md добавили два правила: «Не раскрывай прямые PII-поля в marts» и «Не меняй grain, SLA или поля контракта без подтверждения». В specs/tech-stack.md записали, что маскирование PII — обязательный шаг пайплайна, а не опциональный. Дорожную карту переписали по артефактам: «контракт утверждён → mart проверен → витрина одобрена ревьюером».
Результат: Через неделю витрина была переписана: email выводился только в маскированном виде, grain был восстановлен до «один клиент — одна строка на дату среза». Новый аналитик, подключившийся к проекту впервые, смог продолжить работу без пересказа чата: он прочитал specs/models/customer_360.md и сразу увидел ограничения. Зелёный dbt build перестал быть признаком готовности — теперь готовность доказывалась содержимым specs/validation/ и specs/reviewer-reports/.
Извлечённые уроки: Договорённости, оставшиеся в чате, исчезают при первом /clear и невидимы для нового человека
Зелёный dbt build не равен продуктовой готовности — нужны спецификации и проверочные факты
AGENTS.md должен быть коротким списком поведенческих правил, а не копией спецификаций
Дорожная карта по артефактам сразу показывает, какие доказательства ещё не собраны
Папки specs/models/, specs/validation/ и specs/reviewer-reports/ должны существовать до первой SQL-модели
Связанные концепции: Память проекта vs память чата
Разделение AGENTS.md и specs
Слои смысла, проверки и ревью
Дорожная карта по артефактам
Критерий готовности настройки
Название: E-commerce аналитика: попытка «сразу собрать lakehouse»
Сценарий: Менеджер e-commerce проекта попросил AI-агента «собрать lakehouse для аналитики продаж». У проекта не было ни mission.md, ни tech-stack.md, ни specs/. Репозиторий содержал только пустой README и папку data/ с сырыми выгрузками.
Задача: Агент начал с того, что попытался выбрать между Spark, ClickHouse, BigQuery и Snowflake, обсуждал модели данных, форматы файлов и оркестраторы прямо в чате. Через час диалог разросся до сотен сообщений, но в репозитории по-прежнему не появилось ни одной структурной единицы, кроме README. Когда пришёл второй аналитик, он не смог понять, какие решения уже приняты, потому что они были размазаны по чату. Любой /clear стирал контекст, и работу приходилось начинать заново.
Решение: Менеджер остановил диалог и начал с настройки проекта по правилам главы. Он создал specs/mission.md («аналитика продаж e-commerce, фокус — повторные покупки»), specs/tech-stack.md («ClickHouse как хранилище, dbt как слой трансформации, Airflow как оркестратор»), specs/roadmap.md по артефактам и AGENTS.md с пятью короткими правилами поведения. После этого агенту был отправлен Qwen-запрос для аудита каркаса: «Прочитай текущую структуру проекта. Проверь, есть ли места для mission, tech-stack, roadmap, спецификаций моделей, проверочных фактов, dbt-моделей и отчётов ревьюера. Составь список пробелов настройки. Файлы не меняй». На основе списка пробелов агенту поручили создать только недостающие директории и пустые шаблоны, без написания SQL.
Результат: Через 30 минут каркас был готов, и второй аналитик зашёл в проект уже после настройки. Он прочитал mission.md, tech-stack.md и roadmap.md за 10 минут и сразу понял, что делается и зачем. После этого команда перешла к спецификациям моделей и только потом к SQL. Время на онбординг нового члена команды сократилось с нескольких дней до одного часа. Новый агент после /clear также понимал проект без пересказа чата, что подтвердило критерий готовности настройки.
Извлечённые уроки: Слишком широкий запрос к агенту («собери lakehouse») приводит к диалогу без артефактов в репозитории
Настройка проекта — это создание контейнеров для решений, а не принятие самих решений
Qwen-запрос с запретом на изменения хорошо подходит для аудита каркаса
Дорожная карта по артефактам помогает не свалиться в «слои ради слоёв»
Короткий AGENTS.md работает лучше, чем длинная инструкция
Связанные концепции: Контейнеры для решений
Qwen-запрос для аудита настройки
Минимальная структура каталогов
Дорожная карта по артефактам
Типичная ошибка настройки
Название: Маркетплейс: AGENTS.md как энциклопедия и сломанный онбординг
Сценарий: Аналитик маркетплейса написал AGENTS.md на 12 страниц: туда вошли инструкции по работе с dbt, описания всех витрин, требования по безопасности, схемы данных и даже куски SQL. Файл регулярно обновлялся, но никто его целиком не читал — ни человек, ни агент.
Задача: Когда в проект пришёл новый агент, он проигнорировал длинный AGENTS.md и стал опираться на собственный «здравый смысл». В частности, он начал менять grain витрины заказов без подтверждения, потому что правило о запрете на изменение grain утонуло между описанием схем и SQL-примерами. Ревьюер заметил проблему только после того, как витрина ушла в продакшен и сломала отчёт по выручке. Проверочные факты при этом были разбросаны по комментариям PR и по чату, поэтому восстановить ход рассуждений агента было невозможно.
Решение: Команда переписала AGENTS.md по правилам главы: оставила пять коротких поведенческих правил (что прочитать, чего не раскрывать, чего не менять без подтверждения, какую команду запускать, как отчитываться). Все продуктовые описания, описания витрин, поля контракта и приёмочные факты были перенесены в specs/: в specs/mission.md, specs/tech-stack.md, specs/roadmap.md, specs/models/ и specs/validation/. Папка specs/reviewer-reports/ была создана заново, и ревьюер получил инструкцию писать отчёты туда, а не в чат. Дорожная карта была переписана по артефактам с явной ссылкой на specs/validation/ как хранилище доказательств.
Результат: Через месяц количество нарушений контракта (изменение grain, утечки PII, изменение SLA без подтверждения) снизилось почти до нуля. Новый агент стал следовать коротким правилам AGENTS.md и обращаться к specs/ за деталями. Время ревью одного PR сократилось, потому что проверочные факты лежали в specs/validation/, а не были разбросаны по чату и комментариям. Команда впервые смогла проверить критерий готовности настройки: новый агент после /clear понимал проект без пересказа чата.
Извлечённые уроки: Длинный AGENTS.md превращается в энциклопедию, которую никто не читает
Поведенческие правила и продуктовые описания должны жить в разных файлах
Проверочные факты должны быть в specs/validation/, а не в комментариях PR
Короткий AGENTS.md повышает вероятность того, что агент и человек будут им пользоваться
Отчёт ревьюера — это отдельный артефакт (specs/reviewer-reports/), а не сообщение в чате
Связанные концепции: AGENTS.md как поведенческий файл
Разделение AGENTS.md и specs
Слои смысла, проверки и ревью
Дорожная карта по артефактам
Память проекта vs память чата
Советы по изучению: Не пытайтесь сразу наполнять specs/ содержанием — на этапе настройки нужны только пустые контейнеры и заголовки
Перед каждым изменением в проекте спрашивайте себя: «Если сейчас сделать /clear, новый агент поймёт, где искать это решение?» Если ответ «нет» — решение должно жить в файле, а не в чате
Держите AGENTS.md коротким: лучше пять коротких правил, чем двенадцать страниц инструкций
Составляйте дорожную карту по артефактам и проверочным фактам, а не по «слоям ради слоёв»
Используйте Qwen-запрос из главы как шаблон для аудита каркаса: первый запрос — только чтение, второй — только создание пустых директорий
Разделяйте поведение агента (AGENTS.md) и продуктовое описание (specs/); смешение рождает раздутые файлы, которые никто не читает
Проверяйте критерий готовности настройки: новый агент после /clear должен понять миссию, стек, витрины и способ доказать готовность без пересказа чата
Делайте настройку до первой SQL-модели; иначе источник истины появится в комментариях и тексте ответов агента, и его будет трудно восстановить
Избегайте широких запросов вроде «собери lakehouse» — на этапе настройки нужны контейнеры для решений, а не сами решения
Фиксируйте каждое существенное решение в specs/ сразу после принятия, а не «когда будет время»
Дополнительные ресурсы: Dbt documentation — project structure: https://docs.getdbt.com/docs/build/projects — официальное руководство по структуре dbt-проекта, файлам dbt_project.yml и profiles.yml
Dbt labs — model contracts: https://docs.getdbt.com/docs/collaborate/govern/model-contracts — описание контрактов моделей, фиксации grain и состава полей
Anthropic — claude documentation: https://docs.anthropic.com — рекомендации по формулировке поведенческих правил для AI-агентов
Conventional commits: https://www.conventionalcommits.org — стандарт оформления коммитов, полезный для фиксации этапов настройки каркаса
Markdown guide: https://www.markdownguide.org — справочник по разметке для mission.md, tech-stack.md, roadmap.md и AGENTS.md
Git book — recording changes to the repository: https://git-scm.com/book — основы работы с Git, необходимые для фиксации каркаса и его версионирования
Резюме: Глава «Часть 5. Первичная настройка проекта» учит переносить память решений из чата в файлы репозитория. Минимальный каркас — это specs/ (mission.md, tech-stack.md, roadmap.md и подкаталоги models/, validation/, reviewer-reports/), models/ (staging, intermediate, marts), tests/, AGENTS.md, dbt_project.yml и profiles.yml. AGENTS.md задаёт короткие поведенческие правила: что прочитать перед изменением, чего не раскрывать, чего не менять без подтверждения, какую команду запускать и как отчитываться проверочными фактами. Спецификации миссии, стека, дорожной карты, контрактов моделей и приёмочных фактов живут в specs/, а не в AGENTS.md. Дорожную карту лучше вести по артефактам и проверочным фактам, чтобы было видно, что «модель написана» не равно «продукт готов». Для аудита каркаса используется Qwen-запрос с запретом на изменения; после списка пробелов агенту поручают создать только недостающие директории и пустые шаблоны, без написания SQL. Типичная ошибка — слишком широкий запрос вроде «собери lakehouse», который уводит агента в обсуждение стека в чате, а в репозитории не появляется ни одной структурной единицы. Настройка закончена тогда, когда после /clear новый агент понимает миссию, стек, витрины и способ доказать готовность без пересказа чата: папки начинают удерживать решения.