Data Architecture Team Skill

IMPORTANT: This skill creates an agent team for multi-perspective analysis of data engineering architectural changes. Enable agent teams first by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in your environment or settings.json.

Purpose

When you need to evaluate data engineering architectural changes (dbt models, data pipelines, schema changes), this skill spawns a team of specialized reviewers who analyze the changes from different angles:

• Performance & Scalability Analyst: Query optimization, incremental strategies, data volume handling, resource efficiency
• Architecture & Design Patterns Reviewer: Star schema/dimensional modeling, OLTP/OLAP separation, layering patterns, tool/technology fit
• Data Quality Engineer: Test coverage, validation frameworks, freshness checks, edge cases
• Pragmatic Engineering Analyst: Effort estimation, simplicity vs extensibility trade-offs, avoiding over-engineering while ensuring future-readiness

Each teammate works independently in read-only plan mode to ensure safe exploration without accidental modifications.

When to Use

Use this skill when you need architectural review for:

• Major dbt model refactoring or new model design
• Data pipeline architecture decisions
• Schema changes affecting multiple models
• Performance optimization opportunities
• Data quality framework improvements
• Materialization strategy changes
• Moving from OLTP to OLAP patterns
• Technology/tool selection decisions

Do NOT use this skill for:

• Simple bug fixes or single-line changes
• Routine model updates that follow established patterns
• When you need implementation (this skill only provides analysis)

Execution Protocol

When this skill is invoked, you MUST:

1. Enable Agent Teams

Verify that agent teams are enabled:

# Check if the environment variable is set
echo $CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS

If not enabled, inform the user and provide instructions to enable it in settings.json.

2. Identify the Review Target

From conversation context, identify what needs architectural review:

• Specific dbt models (file paths or model names)
• Data pipeline components
• Schema change proposals
• Performance issues in existing models
• Data quality concerns
• Technology selection decisions

If the target is unclear, ask the user to specify.

3. Gather Context

Collect all relevant context for the review:

• File contents of affected models (use Read tool)
• Related upstream/downstream models (use dbt lineage if available)
• Current test coverage (dbt test files)
• Performance metrics or issues (if mentioned)
• Database schema (if relevant)
• Project requirements or constraints
• Current data warehouse architecture (staging/core/marts layers)
• Existing tools and technologies in use

4. Create the Agent Team

Spawn the agent team with three specialized teammates. Use natural language to instruct Claude to create the team:

Create an agent team to analyze [describe the change/model/issue] from multiple
data engineering perspectives. Spawn 4 teammates:

1. Performance & Scalability Analyst (use Sonnet, plan mode required)
   - Focus: Query performance, incremental strategies, data volume handling,
     resource efficiency, partition/index optimization, technology fit for the
     use case, avoiding unnecessary complexity
   - Context: [Provide model files, schema, data volume info]
   - Key questions: Is the technology appropriate for the scale? Are we
     over-engineering this solution?

2. Architecture & Design Patterns Reviewer (use Sonnet, plan mode required)
   - Focus:
     * Standard data warehouse patterns (star schema, snowflake schema, fact/dimension tables)
     * OLTP vs OLAP separation (are we mixing operational and analytical workloads?)
     * Slowly Changing Dimensions (SCD Type 1/2/3) where appropriate
     * Relational database best practices
     * dbt layering (staging/intermediate/core/marts)
     * Materialization choices (table/view/incremental)
     * Tool & technology evaluation:
       - Existing tools vs custom implementation (dbt packages, PySpark, Airflow, etc.)
       - Is tool complexity justified for the feature need?
       - Don't reinvent the wheel if good tools exist
       - Don't use heavyweight tools for simple problems
     * Dependencies and maintainability
     * Naming conventions and documentation
     * Effort required vs benefit (how much code rewrite is needed?)
   - Context: [Provide model files, dbt project structure, existing patterns, current tech stack]
   - Key questions: Does this follow standard dimensional modeling? Are we
     separating OLTP and OLAP properly? Is this the simplest solution that
     works? Should we use an existing tool or build custom? Is the tool
     complexity justified? What's the effort/benefit ratio?

3. Data Quality Engineer (use Sonnet, plan mode required)
   - Focus: Test coverage, validation frameworks, freshness checks,
     edge cases, null handling, data integrity, referential integrity
   - Context: [Provide model files, test files, data quality requirements]
   - Key questions: Are we testing the right things? What edge cases are we missing?
     Should we use existing data quality tools (dbt_expectations, Great Expectations, etc.)
     or build custom tests?

4. Pragmatic Engineering Analyst (use Sonnet, plan mode required)
   - Focus:
     * Effort estimation (lines of code, models affected, migration complexity)
     * Simplicity vs extensibility trade-offs (YAGNI vs future-readiness)
     * Avoiding over-engineering (don't build what you don't need NOW)
     * Avoiding under-engineering (don't paint yourself into a corner)
     * Code rewrite scope and risk assessment
     * Implementation phases (can this be done incrementally?)
     * "Good enough for now" vs "built to last" analysis
     * Technical debt evaluation (acceptable vs problematic debt)
   - Context: [Provide current implementation, proposed changes, known future requirements]
   - Key questions:
     * What's the MINIMUM change that solves the current problem?
     * Will this solution hold up when [anticipated requirement] arrives?
     * Are we solving problems we don't have yet?
     * Can we deliver value incrementally instead of all-at-once?
     * What's the 80/20 approach here (80% value with 20% effort)?
     * Where should we be flexible for future changes vs rigid for simplicity?

All teammates must work in plan mode (read-only) and cannot make code changes.

After all teammates complete their analysis, synthesize their findings into a
design document with the following structure:

## Executive Summary
[High-level overview of all findings, key recommendations, effort estimate]

## Performance & Scalability Analysis
- Query performance considerations
- Incremental strategy evaluation
- Resource efficiency
- Technology fit assessment
- Complexity analysis (are we over-engineering?)

## Architecture & Design Patterns Analysis
- Standard patterns evaluation (star schema, dimensional modeling)
- OLTP vs OLAP separation review
- SCD pattern recommendations where applicable
- Relational database best practices
- dbt layering and materialization choices
- Tool & technology recommendations:
  * Existing tools vs custom implementation
  * Tool complexity vs feature needs trade-off
  * Specific package/library recommendations with rationale
- Effort required vs benefit analysis
- Code rewrite scope and impact

## Data Quality Analysis
- Test coverage gaps
- Validation framework recommendations (existing tools vs custom)
- Edge cases and data integrity concerns
- Freshness and SLA monitoring

## Pragmatic Engineering Analysis
- Effort estimation (realistic scope and timeline)
- Simplicity vs extensibility evaluation
- Over-engineering vs under-engineering assessment
- Incremental implementation opportunities
- 80/20 analysis (maximum value with minimum effort)
- Techn