Claude Code

npm install -g @anthropic-ai/claude-code

# Buster Agent Development

## Working relationship
- Push back on ideas with reasoning—this leads to better agent configurations
- ALWAYS ask for clarification rather than making assumptions about agent behavior
- NEVER lie, guess, or make up agent capabilities that don't exist

## Project context
- Format: YAML agent configuration files
- Location: .github/buster/agents/
- dbt project: [Describe your dbt project structure]
- Warehouse: [Snowflake/BigQuery/Redshift/etc.]
- Common patterns: [List your team's naming conventions or model layers]

## Buster fundamentals

### Agent structure
Every agent requires:
- name: Kebab-case identifier
- triggers: When the agent runs (pull_request, scheduled, event, manual)
- prompt: Natural language instructions describing what to accomplish
- tools: (optional) Preset or specific tools allowed

Optional fields:
- description: What the agent does
- restrictions: File paths, SQL permissions, git operations
- notifications: Slack, email alerts
- context: Additional files or variables for the agent

### Available triggers
- pull_request: Responds to PR events (opened, synchronize, closed)
  - Can filter by paths, branches, labels, PR size, author
- scheduled: Runs on cron schedules with timezone support
- event: Reacts to data stack events (schema changes, test failures)
- manual: Executes on demand with optional parameters

### Tool presets
- safe: Read-only (code review, audits, analysis)
- standard: Read/write files and git, read-only SQL (default, covers 80% of use cases)
- unrestricted: Full access including destructive operations (use sparingly)

### Common restrictions patterns
```yaml
restrictions:
  files:
    allow: ["models/**"]
    deny: ["**/*.env"]
  sql:
    read_only: true
    allowed_schemas: [raw, staging, marts]
  git_operations:
    branch_prefix: "agent/"

triggers:
  - type: scheduled
    cron: "0 2 * * *"
prompt: |
  Find PRs merged in last 24 hours with model changes.
  Profile changed models, update YAML documentation.
  Create single PR with all updates.

triggers:
  - type: pull_request
    paths: ["models/**/*.sql"]
tools:
  preset: safe
prompt: |
  Review SQL for best practices.
  Comment on issues found.
  Don't modify files.

triggers:
  - type: event
    event_name: schema_change_detected
    source: fivetran
prompt: |
  Analyze schema change impact.
  Update staging models if needed.
  Create PR with changes and impact summary.

## Sample Prompts

Once you have Claude Code set up, try these prompts to see how it can help with Buster agent development. You can copy and paste these examples directly, or adapt them for your specific needs.

### Create a new agent from requirements

Turn your workflow description into a complete Buster agent configuration.

**Example prompt:**

```text
Create a Buster agent that:
- Triggers on PRs that change staging models
- Checks if column names follow our snake_case convention
- Comments on the PR if violations are found
- Uses safe preset (read-only)

Save it to .github/buster/agents/staging-naming-check.yaml

Review all agents in .github/buster/agents/ and check for:
- Missing required fields
- Tools that don't match the task (like using 'safe' preset but trying to commit)
- Prompts that are too vague or missing error handling
- Inefficient trigger patterns

Suggest improvements for each issue found.

I have an agent at .github/buster/agents/docs-updater.yaml that's supposed to update
documentation but it's generating descriptions that are too generic.

Can you:
1. Read the current prompt
2. Make it more specific about what to include in descriptions
3. Add examples of good documentation
4. Update the file with the improved prompt

For my PR reviewer agent at .github/buster/agents/pr-review.yaml, generate test 
scenarios I should validate with `buster test`:
- Small PR (1-2 files)
- Large PR (20+ files)
- PR with syntax errors
- PR with only documentation changes
- PR modifying critical marts models

Show the buster test commands with mock flags for each scenario.

We manually check every Monday if any models in models/marts/ are missing tests.
When we find models without tests, we create a GitHub issue listing them.

Can you create a Buster agent that automates this workflow? It should:
- Run every Monday at 9 AM EST
- Check for missing tests on mart models
- Create an issue if any are found (include which models and what tests are missing)
- Send a Slack message to #data-quality with the results

My schema-change-handler agent at .github/buster/agents/schema-change.yaml isn't 
triggering when I expect it to. Can you:
1. Review the trigger configuration
2. Check if the filters might be too restrictive
3. Suggest what might be preventing it from running
4. Show me how to test it manually with mock events

# new-agent

Create a new Buster agent configuration.

## Usage
/new-agent <name> <trigger-type> <description>

## What it does
1. Creates a new YAML file at .github/buster/agents/<name>.yaml
2. Includes proper structure with name, trigger, tools, and prompt
3. Adds our team's standard restrictions and notifications
4. Validates the configuration with buster validate

# test-agent

Test a Buster agent locally with various scenarios.

## Usage
/test-agent <agent-name>

## What it does
1. Runs buster validate on the agent
2. Tests with mock PR (small change)
3. Tests with mock PR (large change)
4. Shows execution logs and any issues found
5. Suggests prompt improvements if behavior is unexpected

Create an agent similar to .github/buster/agents/docs-updater.yaml but for
generating tests instead of documentation. Keep the same scheduling pattern
and notification setup.

Let's improve the prompt for my docs-updater agent step by step:

Step 1: Current prompt just says "update docs". Make it specify what fields 
to include (model description, column descriptions).

Then test it.

Step 2: Add formatting standards (sentence case, include row counts).

Then test again.

Step 3: Add error handling for dbt parse failures.

I've created a new agent at .github/buster/agents/test-generator.yaml.
Before I commit it:
1. Validate the YAML structure
2. Show me the buster test command to test it locally
3. Walk me through what to look for in the execution logs

This agent has complex conditional logic. Can you add YAML comments explaining:
- When it creates a PR vs just commenting
- How it classifies severity (critical/high/medium)
- What the different Slack channels are for

I'm updating my pr-review agent to also check for missing tests.
Can you:
1. Add a comment at the top noting this change
2. Update the description field to reflect the new capability
3. Show me a good commit message for this change

We just added a Stripe connector to Fivetran. Create an agent that:
- Triggers on schema changes from the Stripe connector
- Detects new tables or columns in raw.stripe schema
- Creates staging models following our naming conventions (stg_stripe__*)
- Includes source YAML with freshness checks
- Opens a PR with the new staging models

Create a daily health check agent that:
- Runs every morning at 8 AM EST on weekdays
- Checks for models in marts/ with >5% null rates in key columns
- Queries for models that haven't been updated in 7+ days
- Sends a summary report to #data-quality Slack
- Only alerts if issues are found (silent on success)

I need to update all my existing PR review agents to use a new Slack channel.
Can you:
1. Find all agents with pull_request triggers
2. Update their notification.slack.channel to "#data-reviews"
3. Validate each one after updating
4. Show me a summary of what changed

My agent at .github/buster/agents/docs-updater.yaml completed successfully but
didn't update the YAML files. Looking at the run logs, it seems to profile the
models correctly. Can you:
1. Read the agent prompt
2. Identify what might be missing
3. Suggest specific improvements to make it actually update the files

My schema-change agent failed with "Error: Cannot modify file 'models/staging/salesforce/stg_salesforce__accounts.sql' - in critical_files list"

Can you:
1. Review the restrictions in the agent config
2. Explain why this is failing
3. Suggest how to fix it (either update restrictions or change the approach)

My PR review agent is triggering on every single commit, even for non-SQL changes.
Can you add path filters so it only runs when .sql or .yml files in models/ change?