Часть 5. Первичная настройка проекта

Первичная настройка нужна, чтобы агент и человек работали не из памяти чата, а из файлов репозитория. В дата-проекте это особенно важно: одна забытая договорённость о grain или PII может сделать зелёный SQL неверным.

Минимальная структура

specs/
  mission.md
  tech-stack.md
  roadmap.md
  models/
  validation/
models/
  staging/
  intermediate/
  marts/
tests/
AGENTS.md
dbt_project.yml
profiles.yml

Не нужно сразу создавать платформу, готовую к боевому контуру. Нужно создать места, куда будут попадать решения. Если нет папки specs/validation/, проверочные факты почти наверняка останутся в чате или PR-описании.

Что записать в AGENTS.md

Минимальные правила:

Перед изменением dbt-моделей:
1. Прочитай mission, tech-stack, roadmap и нужные спецификации моделей.
2. Не раскрывай прямые PII-поля в marts.
3. Не меняй grain, SLA или поля контракта без подтверждения.
4. Запускай `dbt build`, когда dbt доступен.
5. Отчитывайся проверочными фактами, а не обещаниями.

Эти правила не заменяют спецификации. Они задают поведение агента. Продуктовое обещание, поля контракта и приёмочные факты должны жить в specs/.

Дорожная карта

Дорожную карту в дата-проекте лучше вести по артефактам, а не по «слоям ради слоёв». Например:

1. raw/staging воспроизводимы;
2. контракт Customer 360 утверждён;
3. mart Customer 360 проверен;
4. витрины риска, кредитов и согласий проверены ревьюером;
5. доказательства релиза для практического зачёта готовы.

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

Qwen-запрос

Прочитай текущую структуру проекта.
Проверь, есть ли места для mission, tech-stack, roadmap, спецификаций моделей,
проверочных фактов, dbt-моделей и отчётов ревьюера.
Составь список пробелов настройки. Файлы не меняй.

После списка пробелов можно попросить агента создать только недостающие директории и пустые шаблоны. Не просите писать SQL в этой главе.

Разбор для читателя

Первичная настройка кажется скучной, потому что в ней мало результата, который можно показать на экране. Но именно здесь формируется память проекта. Если агент не знает, где искать миссию, стек, дорожную карту и спецификации, он будет использовать память чата. Такая память удобна до первого /clear, но бесполезна для следующего человека и следующего ревьюера.

В дата-проекте структура папок важнее, чем в маленьком приложении. SQL можно написать за минуту, но если заранее нет места для заметок о проверке, источник истины появится там, где удобнее агенту: в комментарии, в выводе команды, в тексте ответа. Потом это трудно восстановить. Папки specs/models/, specs/validation/ и specs/reviewer-reports/ говорят агенту: смысл, проверка и ревью — отдельные слои, а не послесловие к SQL.

AGENTS.md в этой главе не должен превращаться в энциклопедию. Его задача - задать поведение агента перед изменениями: что прочитать, чего не трогать без подтверждения, какие проверки запускать, как отчитываться. Чем короче эти правила, тем выше шанс, что агент и человек действительно будут ими пользоваться. Остальные детали живут в спецификациях.

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

Практика

Проверьте каркас примера и выпишите, где лежат правила агента, память проекта, спецификации моделей, заметки о проверке и отчёты ревьюера. Если какого-то места нет в вашем проекте, добавьте его до первой SQL-модели.

Минимальный выход

После главы должны существовать:

• AGENTS.md;
• specs/mission.md;
• specs/tech-stack.md;
• specs/roadmap.md;
• директории для спецификаций моделей, заметок о проверке и отчётов ревьюера;
• каркас dbt-проекта.

Типичная ошибка

Сразу просить агента «собери lakehouse». Это слишком широко. На этапе настройки нужно создать контейнеры для решений, а не принимать сами решения.

Контрольные вопросы

1. Чем AGENTS.md отличается от specs/tech-stack.md?
2. Почему дорожную карту лучше вести по доказательствам, а не только по слоям?
3. Какие решения нельзя оставлять только в чате?