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

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

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

```text
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

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

```markdown
Перед изменением 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-запрос

```text
Прочитай текущую структуру проекта.
Проверь, есть ли места для 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. Какие решения нельзя оставлять только в чате?