> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nightshift.sh/llms.txt
> Use this file to discover all available pages before exploring further.

# General Best Practices

> Habits that make agent-driven data work go well

Nightshift's design does most of the safety work for you — every action is
[governed](/policies), every change is [auditable and reversible](/audits). What's left
is a handful of habits that make the difference between an agent that flails and an agent
that ships.

## Ground the agent before you build

Start sessions with a look around:

> "What data do I have in Nightshift? Describe the tables I'd need for revenue analysis."

An agent that has listed your objects and read your schemas writes correct SQL on the
first try far more often than one working from your description of the data. This costs
one prompt and pays for itself immediately.

## Build durable shape, not piles of copies

The order of preference for making data useful:

1. **Views first.** They're free, always current, and they turn "the query Claude figured
   out last Tuesday" into a named object every future conversation can build on.
2. **Tables when you mean it** — materialize when the transform is expensive or you need
   a stable snapshot to work against.
3. **Avoid one-off copies.** `sales_final_v2_new` is how warehouses rot. If an agent
   session produced clutter, say so — cleanup is one prompt, and [rollback](/audits)
   has your back.

Name objects for what they mean (`daily_pageviews`, `active_customers`), not for when
they were made. The names become the vocabulary you and the agent share.

## Put work where it lives longest

* **A question** → just ask; a query in chat is fine.
* **A read on the data right now** → ask for a dashboard in chat.
* **Analysis you'll rerun or hand off** → have Claude save it as a [notebook](/notebooks).
* **Something the team opens every week** → have Claude publish an [app](/apps).

The common failure mode is stopping one level short: a great analysis that lives only in
a chat transcript. If it was worth doing, it's usually worth one more sentence — "save
that as a notebook."

## Let the agent act as you — scope tokens for automation

For interactive work, connecting Claude through the standard flow (acting as you) is the
right default: full visibility, full attribution in the [audit log](/audits), zero
setup. Reach for a scoped [token](/policies#tokens) when:

* something runs **unattended** (scheduled jobs, CI, a server),
* you're handing access to a **narrower context** and want a smaller blast radius,
* an **app or integration** needs its own standing identity.

When you mint one: fewest grants that do the job, set an expiry, and check the Tokens
page occasionally — last-used timestamps make dead credentials obvious.

## Review like it's cheap — because it is

Don't pre-approve every step of an agent's work; review it afterward instead. The
platform is built for exactly this:

* The **Audit** log shows every change from the session as snapshots.
* Notebook cells keep the queries *and* their results.
* **Restore** undoes anything, without losing history.

Trusting the agent with real writes and reviewing after is faster than supervising every
statement — and in Nightshift it's just as safe.

## Bring data in the front door

External data enters through **Add Data** (or your connectors) — not through SQL. Queries
can't read files, URLs, or credentials by design, so don't ask the agent to `COPY` from a
bucket; ask it to load the data through a connector instead. Credentials live in Add
Data's managed configuration, never in SQL text.

## Share the artifact, not the warehouse

When someone needs numbers, share the [app or notebook](/sharing) that presents them —
not read access to the underlying tables. Apps in particular are built for this: viewers
see the output with no grants on the source data. Save table-level grants for people who
genuinely need to query the data themselves, and review **Access → Grants** now and then.