Part 5. Initial Project Setup

Initial setup is needed so that the agent and the person work not from chat memory, but from repository files. In a data project this is especially important: a single forgotten agreement about grain or PII can make green SQL incorrect.

Minimum structure

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

You don't need to immediately create a platform ready for the production environment. You need to create places where decisions will end up. If there is no specs/validation/ folder, verification facts will almost certainly remain in chat or the PR description.

What to record in AGENTS.md

Minimum rules:

Before changing dbt models:
1. Read mission, tech-stack, roadmap, and the relevant model specifications.
2. Don't expose direct PII fields in marts.
3. Don't change grain, SLA, or contract fields without confirmation.
4. Run `dbt build` when dbt is available.
5. Report using verification facts, not promises.

These rules don't replace specifications. They define agent behavior. The product promise, contract fields, and acceptance facts should live in specs/.

Roadmap

In a data project, it's better to keep the roadmap by artifacts, not by "layers for the sake of layers". For example:

1. raw/staging are reproducible;
2. Customer 360 contract is approved;
3. Customer 360 mart is verified;
4. risk, credit, and consent dashboards are reviewed by a reviewer;
5. release evidence for the practical assessment is ready.

This way you can see that "the model is written" is not the same as "the product is ready".

Qwen query

Read the current project structure.
Check whether there are places for mission, tech-stack, roadmap, model specifications,
verification facts, dbt models, and reviewer reports.
Compose a list of setup gaps. Do not modify files.

After the gap list, you can ask the agent to create only the missing directories and empty templates. Don't ask it to write SQL in this chapter.

Breakdown for the reader

Initial setup seems boring because there is little result that can be shown on screen. But this is exactly where project memory is formed. If the agent doesn't know where to look for the mission, stack, roadmap, and specifications, it will use chat memory. Such memory is convenient until the first /clear, but useless for the next person and the next reviewer.

In a data project, folder structure is more important than in a small application. SQL can be written in a minute, but if there is no place for verification notes in advance, the source of truth will appear where it's more convenient for the agent: in a comment, in command output, in the response text. Then it's hard to restore. The specs/models/, specs/validation/, and specs/reviewer-reports/ folders tell the agent: meaning, verification, and review are separate layers, not an epilogue to SQL.

AGENTS.md in this chapter should not turn into an encyclopedia. Its task is to define agent behavior before changes: what to read, what not to touch without confirmation, what checks to run, how to report. The shorter these rules, the higher the chance that the agent and the person will actually use them. Other details live in specifications.

A good setup gives a simple test: after clearing the context, a new agent should understand where the mission is, what stack is allowed, what dashboards are being built, and how readiness is proven. If you need to retell the chat to continue work, the project is not yet set up. Setup is finished not when the folders are created, but when they start holding decisions.

Practice

Check the example scaffold and write down where the agent rules, project memory, model specifications, verification notes, and reviewer reports are located. If any place is missing in your project, add it before the first SQL model.

Minimum output

After the chapter must exist:

• AGENTS.md;
• specs/mission.md;
• specs/tech-stack.md;
• specs/roadmap.md;
• directories for model specifications, verification notes, and reviewer reports;
• dbt project scaffold.

Typical mistake

Immediately asking the agent to "build a lakehouse". This is too broad. At the setup stage, you need to create containers for decisions, not make the decisions themselves.

Control questions

1. How does AGENTS.md differ from specs/tech-stack.md?
2. Why is it better to keep the roadmap by evidence, not just by layers?
3. What decisions cannot be left only in chat?