Build Engineer Pro

A senior build engineering agent that optimizes build systems, reduces compilation times, and maximizes developer productivity through build tool configuration, caching strategies, and scalable build pipelines.

When to Use This Agent

Choose Build Engineer Pro when:

• Build times have grown beyond acceptable thresholds (>2 min local, >10 min CI)
• Setting up or migrating build systems (webpack to Vite, Make to Bazel)
• Implementing build caching strategies (local, remote, distributed)
• Debugging flaky or non-deterministic builds
• Optimizing CI/CD pipeline performance and resource usage

Consider alternatives when:

• Writing application code or business logic (use a general development agent)
• Setting up deployment pipelines (use a DevOps agent)
• Optimizing runtime application performance (use a performance engineer agent)

Quick Start

Copy
# .claude/agents/build-engineer-pro.yml
name: Build Engineer Pro
description: Optimize build systems for speed and reliability
model: claude-sonnet
tools:
  - Read
  - Edit
  - Write
  - Bash
  - Glob
  - Grep

Example invocation:

claude "Analyze our webpack build times, identify the slowest modules, and implement caching and parallelization to reduce build time by at least 50%"

Core Concepts

Build System Comparison

System	Language	Strengths	Best For
Vite	JS/TS	Fast dev server, ESM-native	Frontend apps, libraries
esbuild	JS/TS	Extremely fast bundling	Build step, simple bundles
Turbopack	JS/TS	Incremental, Rust-based	Next.js projects
Bazel	Polyglot	Hermetic, remote cache	Large monorepos
Nx	JS/TS	Task orchestration, graph	JS/TS monorepos
Turborepo	JS/TS	Simple caching, pipelines	Multi-package repos

Build Performance Analysis

Copy
# Measure webpack build timing
WEBPACK_PROFILE=true npx webpack --profile --json > stats.json
npx webpack-bundle-analyzer stats.json

# Measure Vite build timing
npx vite build --debug 2>&1 | tee build-log.txt

# Analyze TypeScript compilation
npx tsc --diagnostics --extendedDiagnostics

# Find slow modules in Node.js startup
node --cpu-prof --cpu-prof-interval=100 app.js

Caching Strategy Layers

Copy
// turbo.json — Turborepo remote caching
{
  "pipeline": {
    "build": {
      "dependsOn": ["^build"],
      "outputs": ["dist/**", ".next/**"],
      "cache": true
    },
    "test": {
      "dependsOn": ["build"],
      "outputs": ["coverage/**"],
      "cache": true
    },
    "lint": {
      "outputs": [],
      "cache": true
    }
  },
  "remoteCache": {
    "signature": true
  }
}

// Cache hit rates to target:
// Local cache:  60-80% hit rate (same developer, iterative work)
// Remote cache: 40-60% hit rate (shared across team/CI)
// CI cache:     70-90% hit rate (dependency install, build artifacts)

Configuration

Parameter	Description	Default
build_system	Primary build tool (vite, webpack, esbuild, bazel)	Auto-detect
monorepo_tool	Monorepo orchestrator (turborepo, nx, lerna)	Auto-detect
cache_backend	Cache storage (local, s3, gcs, custom)	local
parallelism	Max parallel build tasks	os.cpus().length
target_time	Target build time in seconds	60
profile_output	Where to save profiling data	./build-profile

Best Practices

1. Profile before optimizing — measure the actual bottleneck. Run a build with profiling enabled and analyze where time is actually spent. Common assumptions like "TypeScript is slow" often hide the real bottleneck: a single large SVG loader, an unoptimized regex in PostCSS, or redundant file system scans. Address the measured bottleneck first, not the assumed one. Profiling data prevents wasted optimization effort.

2. Layer caching from fastest to slowest: memory, disk, remote. In-memory caches (esbuild module cache) are fastest but lost on restart. Disk caches (Turborepo local cache) persist across builds. Remote caches (S3, Vercel) share across team and CI. Each layer should fall through to the next. Configure cache keys based on file content hashes, not timestamps, to maximize hit rates and prevent stale cache bugs.

3. Make builds hermetic and deterministic. A build should produce identical output given identical input, regardless of which machine runs it or what else is installed. Pin all tool versions, avoid host-system dependencies, use lockfiles for all dependency managers, and never rely on filesystem ordering. Deterministic builds make caching reliable and debugging reproducible.

4. Parallelize independent build tasks at the task graph level. Modern build orchestrators (Turborepo, Nx, Bazel) model builds as directed acyclic graphs. Tasks without dependencies run in parallel automatically. Structure your build graph so the critical path (longest chain of dependent tasks) is as short as possible. Move slow tasks (type checking, linting) out of the critical path by running them in parallel with the build.

5. Monitor build metrics as first-class infrastructure. Track build time percentiles (P50, P95), cache hit rates, and CI resource utilization over time. Set alerts when build times regress beyond thresholds. Build time is developer productivity — a 1-minute regression across 50 developers running 10 builds/day wastes 8+ hours daily. Treat build performance regressions like production performance regressions.

Common Issues

Build cache hit rates are unexpectedly low. The most common cause is cache keys that include volatile data: timestamps, random values, absolute file paths, or environment variables that differ between machines. Audit your cache key computation to ensure it includes only content hashes of source files and dependency versions. Remove any non-deterministic inputs. Log cache key computations to debug mismatches between local and CI environments.

Incremental builds are slower than clean builds. This paradox occurs when the incremental build system spends more time determining what changed than it saves by not rebuilding everything. Common causes include file watchers scanning too many directories (add node_modules to ignore lists), over-broad invalidation rules that rebuild entire modules for single-file changes, and fragmented caching that incurs excessive I/O. Profile the change detection phase separately from the build phase.

CI builds are significantly slower than local builds. CI environments often have slower I/O, less memory, and cold caches. Optimize CI builds specifically: use RAM disks for temporary build artifacts, configure dependency caching (actions/cache for GitHub Actions), run builds on machines with SSDs, and warm the remote cache from a scheduled nightly build. Additionally, ensure CI builds are not running unnecessary steps like full linting when only specific packages changed.