Changes for content/handbook/enterprise-data/ai/agent-setup.md: 100 added lines, 222 removed lines.
Original line number
Diff line number
Diff line
@@ -9,25 +9,86 @@ description: "Data Team guide for setting up agentic AI tools for development"
The data team doesn't have a standard approach for AI-assisted development — this guide fills that gap. It's based on what's already been working for several teammates, so everyone has a solid starting point rather than figuring it out from scratch.
Two terminal-based agents are documented here: **Claude Code** and **OpenCode**. Both are supported and neither is the team default — use whichever fits your workflow. The team's shared skills follow the [Agent Skills format](https://agentskills.io/specification), so one local clone works in either tool.
This guide covers setup for:
-**OpenCode** — a terminal-based AI coding agent
-**Snowflake/dbt MCP servers**(optional, but highly recommended)
-**Claude Code** and **OpenCode** — terminal-based AI coding agents
-**Snowflake CLI and the dbt MCP server**— data access during an agent session
A more comprehensive guide is available in the [internal handbook](https://internal.gitlab.com/handbook/ai-security-at-gitlab/guides/setup-guides/claude-code-setup/). The steps below are a simplified, data-team-specific version.
Install Claude Code by following the [Claude Code setup guide](https://internal.gitlab.com/handbook/ai-security-at-gitlab/guides/setup-guides/claude-code-setup/), which covers installation, authentication with your GitLab account, and the approved usage policy.
Verify the installation:
```bash
claude --version
```
You should see the installed version number.
**Step 2: Start Claude Code from the analytics repo**
```bash
jump analytics
claude
```
**Step 3: Add the GitLab MCP server**
Add the GitLab MCP server by following the [GitLab MCP setup guide](https://internal.gitlab.com/handbook/ai-security-at-gitlab/guides/setup-guides/gitlab-mcp-setup/).
The GitLab MCP server lets an agent work with GitLab directly during a session — reading issues, opening and updating merge requests, reading review comments, and checking pipeline and job status. Several Data Team skills depend on it.
To verify the connection, run `/mcp` inside Claude Code. The GitLab server should be listed as connected.
**Step 4: Set `plan` as your default mode**
Run `/config` inside a Claude Code session to review and change your settings. Anything you change there is written to your Claude Code settings file automatically, so there is no config file to hand-edit.
Set `defaultMode` to `plan`. This keeps you in the safer, more deliberate mode by default — you switch to an editing mode explicitly when you're ready to execute. It is the Claude Code equivalent of the OpenCode default agent setting below.
The model and output style are also worth reviewing in `/config` while you're there.
**Step 5: Review the Agent Usage Guide**
Before you start using Claude Code, review the [Agent Usage Guide](agent-usage-guide.md) to understand:
- How agents and MCPs work
- Configuration best practices (global vs project-level)
- When to use plan mode
- Prompting best practices and context management
- Available skills and agents
</details>
---
## OpenCode Setup
A more comprehensive guide is available in the [internal handbook](https://internal.gitlab.com/handbook/ai-security-at-gitlab/guides/setup-guides/opencode-setup/). The steps below are a simplified, data-team-specific version.
### Step 3: Start OpenCode from the analytics repo
**Step 3: Start OpenCode from the analytics repo**
```bash
jump analytics
opencode
```
### Step 4: Configure GitLab Duo as your AI provider
**Step 4: Configure GitLab Duo as your AI provider**
GitLab Duo uses OAuth — no token to create or manage.
1. Run `/connect` inside OpenCode and select **GitLab Duo**
2. OpenCode will open your browser to complete the OAuth flow
3. Sign in with your `@gitlab.com` account and authorise the app
4. You'll be redirected back to OpenCode automatically
### Step 4.5: Test the connection
1. OpenCode will open your browser to complete the OAuth flow
1. Sign in with your `@gitlab.com` account and authorise the app
1. You'll be redirected back to OpenCode automatically
Once connected, test it by saying `hi` to verify OpenCode responds.
### Step 5: Apply the Golden Config
**Step 5: Apply the Golden Config**
Apply the config from the [OpenCode Golden Path](https://internal.gitlab.com/handbook/ai-security-at-gitlab/guides/golden-configs/opencode/#golden-path-config).
> **Note:** Use `~/.config/opencode/opencode.jsonc` rather than `opencode.json` — the `.jsonc` extension allows comments, which is useful for annotating your config.
### Step 6: Set `plan` as your default agent
**Step 6: Set `plan` as your default agent**
Open `~/.config/opencode/config.json` (this is a separate file from the `opencode.jsonc` Golden Config in Step 5) and add `default_agent`:
@@ -89,7 +148,7 @@ Open `~/.config/opencode/config.json` (this is a separate file from the `opencod
This keeps you in the safer, more deliberate mode by default — you switch to Build explicitly when you're ready to execute.
### Step 7: Review the Agent Usage Guide
**Step 7: Review the Agent Usage Guide**
Before you start using OpenCode, review the [Agent Usage Guide](agent-usage-guide.md) to understand:
@@ -99,251 +158,70 @@ Before you start using OpenCode, review the [Agent Usage Guide](agent-usage-guid
### Snowflake MCP Server (Optional but Highly Recommended)
Connecting OpenCode to Snowflake MCP allows an LLM agent to query Snowflake directly during an OpenCode session.
To set up, run the [setup_mcp_analytics.sh script](https://gitlab.com/gitlab-data/analytics/-/blob/master/admin/setup_mcp_analytics.sh?ref_type=heads) with these commands:
The script will prompt you for your GitLab username and analytics repo path.
## Connecting to Other Applications
> **Important:** The script will prompt for your computer login password and request keychain access. Enter your password and click **"Always Allow"** when prompted.
An agent gets more useful the more of your toolchain it can reach. The sections below cover the connections the data team relies on day to day — querying Snowflake, and awareness of the dbt project.
**Verify the connection:**
### Snowflake CLI
Start OpenCode (`jump analytics && opencode`), type `hi`, then look to the right side of the interface. You should see the Snowflake MCP name listed with a green dot indicating "connected".
Agents query Snowflake through the [Snowflake CLI](/handbook/enterprise-data/platform/snowflake/snowflake-cli/) (`snow`), which is the Data Team standard for local Snowflake access. Follow that page to install and configure it.
<details>
<summary>More detail on what gets created</summary>
Once `snow connection test` passes, both Claude Code and OpenCode can query Snowflake during a session — Claude Code by running `snow sql` in the terminal, OpenCode through its built-in `snowflake` tool.
The script generates two files:
> **Note:** The Snowflake MCP server previously described here is no longer maintained and has been replaced by the Snowflake CLI. If you set the MCP server up earlier, there is no migration step — install the CLI and use it instead.
Controls which Snowflake tool groups are enabled and which SQL statement types are permitted. The defaults enable object inspection and query execution while disabling destructive operations (`Drop`, `Delete`).
The dbt MCP server gives an agent awareness of the dbt project — model structure, lineage, and node details. It is only relevant in the analytics repo.
The only other prerequisite is having the dbt virtualenv set up. To verify or set it up:
```bash
jump analytics
make run-dbt
ls .venv/bin/dbt # Should show the dbt executable
```
If `ls .venv/bin/dbt` returns the file path, you're good to go.
Run `source ~/.zshrc` in the shell where you plan to start your agent.
**Verify the connection:**
Start OpenCode (`jump analytics && opencode`), type `hi`, then look to the right side of the interface. You should see the dbt MCP name listed with a green dot indicating "connected".
Run `/mcp` in Claude Code or `/mcps` in OpenCode — the dbt server should be listed as connected.
---
## MacWhisper for Voice Prompting (Optional)
Typing out detailed prompts is slow. [MacWhisper](https://goodsnooze.gumroad.com/l/macwhisper) is a macOS voice-to-text app that makes it much faster to describe context and work through problems out loud — particularly for longer prompts where you'd otherwise spend more time typing than thinking.
It's noticeably more accurate than built-in macOS Dictation app, and unlike cloud-based transcription it runs entirely on-device, so nothing leaves your machine.
## Skills Setup
Skills provide reusable workflows and conventions that agents can automatically invoke. To use all available Data Team skills:
1. Complete the OpenCode setup steps above
2. Complete the MCP setup steps above (Snowflake/dbt)
3. Clone and symlink the `data-team-agentic-skills` repo by following the [setup instructions](https://gitlab.com/gitlab-data/data-team-agentic-skills#setup-opencode)
## OpenCode Plugins
### OpenCode Notify
[OpenCode Notifier](https://github.com/mohak34/opencode-notifier) is a plugin that sends native macOS system notifications when OpenCode prompts you for something.
#### Install Steps
1. Add the `opencode-notifier` plugin to your `~/.config/opencode/opencode.jsonc`. It should look something like this:
```jsonc
{
"$schema":"https://opencode.ai/config.json",
"share":"disabled",
"autoupdate":true,
"plugin":["@mohak34/opencode-notifier@latest"],
```
When you run an agent inside a repo, that repo's own skills need no setup — the agent reads their frontmatter and invokes them when a task matches.
1. Optional (but recommended): by default, this plugin notifies on every event, which gets noisy fast. To customize which events trigger notifications, create a file `~/.config/opencode/opencode-notifier.json` and paste in the following config:
Skills shared across repos are different. They live in [`data-team-agentic-skills`](https://gitlab.com/gitlab-data/data-team-agentic-skills) and have to be symlinked into your local skills directory before an agent can see them — including when a repo's own skill calls one. Follow the setup steps in that repo's README.
"user_message":"User sent a message: {sessionTitle}",
"client_connected":"OpenCode connected"
},
"sounds":{
"permission":null,
"complete":null,
"subagent_complete":null,
"error":null,
"question":null,
"user_cancelled":null,
"plan_exit":null,
"session_started":null,
"user_message":null,
"client_connected":null
},
"volumes":{
"permission":0.5,
"complete":1,
"subagent_complete":1,
"error":1,
"question":0.5,
"user_cancelled":1,
"plan_exit":1,
"session_started":1,
"user_message":1,
"client_connected":1
}
}
```
## MacWhisper for Voice Prompting (Optional)
</details>
Typing out detailed prompts is slow. [MacWhisper](https://goodsnooze.gumroad.com/l/macwhisper) is a macOS voice-to-text app that makes it much faster to describe context and work through problems out loud — particularly for longer prompts where you'd otherwise spend more time typing than thinking.
1. Restart OpenCode to load the `opencode-notifier` plugin.
1. Validate: trigger a permission prompt (e.g. ask OpenCode to run `rm ~/Downloads/some-file.csv`). You should hear a sound and see a notification banner in the top right of your screen. No notification should fire on task completion.
It's noticeably more accurate than built-in macOS Dictation app, and unlike cloud-based transcription it runs entirely on-device, so nothing leaves your machine.
Changes for content/handbook/enterprise-data/ai/agent-usage-guide.md: 25 added lines, 16 removed lines.
Original line number
Diff line number
Diff line
@@ -13,19 +13,28 @@ For a deeper dive, see Anthropic's [building effective agents](https://www.anthr
## How MCPs Work
MCP (Model Context Protocol) servers extend what an agent can do by connecting it to external tools and data sources — think Snowflake, GitLab, dbt, Slack. Each active MCP adds to the agent's context window, so only enable what you actually need for the task at hand.
MCP (Model Context Protocol) servers extend what an agent can do by connecting it to external tools and data sources — think GitLab, dbt, Slack. Each active MCP adds to the agent's context window, so only enable what you actually need for the task at hand.
Not every integration is an MCP server. The Snowflake MCP server is no longer maintained, so Snowflake access goes through the [Snowflake CLI](/handbook/enterprise-data/platform/snowflake/snowflake-cli/) (`snow`), which an agent calls like any other command-line tool.
## Configuration
OpenCode uses two config files that merge at runtime — a global config (`~/.opencode/config.json`) and a project-level config (`.opencode/config.json` at the repo root). Project settings override global ones when they collide.
Both tools merge a global config with a project-level one, and project settings override global ones when they collide:
| | Global | Project-level |
| --- | --- | --- |
| Claude Code | `~/.claude/settings.json`, `~/.claude.json` | `.claude/settings.json`, `.mcp.json` at the repo root |
| OpenCode | `~/.config/opencode/opencode.jsonc` | `.opencode/config.json` at the repo root |
Keep your global config minimal. The main thing worth putting there is MCPs you need in every session regardless of what you're working on. Everything else — especially repo-specific MCPs like `dbt-mcp` — belongs in the project config. For example, `dbt-mcp` lives only in the analytics repo config since it's only relevant there.
A good rule of thumb: if you'd want the MCP active even when you open OpenCode outside of any project, it goes global. Otherwise, keep it local.
A good rule of thumb: if you'd want the MCP active even when you open your agent outside of any project, it goes global. Otherwise, keep it local.
In Claude Code, prefer `/config` over hand-editing — it writes the settings file for you.
## Best Practices
Keep context lean. Start a new conversation any time you shift focus — a new feature, a different bug, an unrelated review. When in doubt, fresh window. In OpenCode, use the `/new` command to do that. This improves quality of responses as well as costs
Keep context lean. Start a new conversation any time you shift focus — a new feature, a different bug, an unrelated review. When in doubt, fresh window. Use `/clear` in Claude Code or `/new` in OpenCode to do that. This improves quality of responses as well as costs
If a skill exists for what you're doing, use it — skills give the agent domain-specific context it wouldn't otherwise have.
@@ -39,29 +48,29 @@ The AE team uses OpenCode across the full development lifecycle — building and
- For well-understood tasks, go directly to **Build** or the AE agent
- Begin prompts with "I want to…" and describe the change, review comment, or question you are working through
- For MR reviews, open a fresh session scoped to that review
- For more detail on the two modes, see [When to Use Plan vs Build Mode](#when-to-use-plan-vs-build-mode) below
- For more detail on the two modes, see [When to Use Plan Mode](#when-to-use-plan-mode) below
#### Session Management, Model Selection, and Cost Efficiency
- Start a new session per MR, topic, or day — the guiding question is whether the prior context is actually needed for the next task; if not, start fresh
- A medium sized model, like **Sonnet 4.6**, is the recommended default model — they offer a good balance of quality, speed, and cost; larger models are slower and more expensive without proportional gains for most AE tasks
- Input tokens seem to be the most expensive component of a session — keep context lean, use `/compact` when it grows large, and start a new session before reaching the 200K token threshold
- Only enable the MCPs needed for the current task — use the `/mcps` command and press `space` to toggle MCPs on or off
- Only enable the MCPs needed for the current task — in OpenCode, `/mcps` toggles servers on or off with `space`; in Claude Code, `/mcp` lists the connected servers and which ones load is set in config
#### MCP Setup
#### Data Access Setup
Snowflake MCP is required for most AE development work. If you run into issues configuring it, refer to the setup and troubleshooting video: **[placeholder — link to Snowflake MCP setup video coming soon]**
The [Snowflake CLI](/handbook/enterprise-data/platform/snowflake/snowflake-cli/) is required for most AE development work — it is how an agent queries Snowflake during a session. The [dbt MCP server](agent-setup.md#dbt-mcp-server) is worth adding on top of it for dbt model structure, lineage, and node details.
## When to Use Plan vs Build Mode
## When to Use Plan Mode
OpenCode has two primary modes:
Both tools separate planning from execution:
-**Plan** — reviews your request and relevant code, then proposes a detailed approach *before* making any changes
-**Build** — executes changes directly
-**Plan mode** — reviews your request and relevant code, then proposes a detailed approach *before* making any changes
-**Execution** — Build mode in OpenCode, the default or edit-accepting modes in Claude Code — makes changes directly
Always run Plan first for anything non-trivial. It's surprisingly good at catching design issues before you're already mid-implementation.
Always run plan mode first for anything non-trivial. It's surprisingly good at catching design issues before you're already mid-implementation.
If you've set `plan` as your default agent (recommended in the [setup guide](agent-setup.md#step-6-set-plan-as-your-default-agent)), you'll be in Plan mode by default. Switch to Build mode explicitly when you're ready to execute.
The setup guide recommends making plan the default for both tools — see [Claude Code Setup](agent-setup.md#claude-code-setup) for `defaultMode` and [OpenCode Setup](agent-setup.md#opencode-setup) for the default agent. You then leave plan mode explicitly when you're ready to execute.
Skills are automatically invoked by AI coding tools like OpenCode when the task described in your prompt matches the skill's frontmatter metadata. Well-written frontmatter (especially `name` and `description` fields) enables automatic discovery. You can also explicitly mention a skill by name in your prompt if you know it exists.
Skills are automatically invoked by AI coding tools like Claude Code and OpenCode when the task described in your prompt matches the skill's frontmatter metadata. Well-written frontmatter (especially `name` and `description` fields) enables automatic discovery. You can also explicitly mention a skill by name in your prompt if you know it exists.
### Available Skills
@@ -77,4 +86,4 @@ For a list of skills developed by the Data Team, see the [Available Skills](agen
### Setup
To enable skills in your OpenCode environment, follow the [Skills Setup](agent-setup.md#skills-setup) instructions in the Agent Setup guide.
To enable skills in Claude Code or OpenCode, follow the [Skills Setup](agent-setup.md#skills-setup) instructions in the Agent Setup guide.
Changes for content/handbook/enterprise-data/ai/ai-vision-and-strategy.md: 2 added lines, 2 removed lines.
Original line number
Diff line number
Diff line
@@ -29,8 +29,8 @@ The path forward requires accepting this shift in direction and adopting the men
The Enterprise Data team is not starting from zero—we are already building AI-powered data infrastructure. Key capabilities already in production or active development include:
