Incremental builds: only changed targets

Incremental builds with only changed targets rebuild exactly and only the build targets that depend on files that have changed since the last build. This is fundamentally different from module-level incremental compilation in Maven or Gradle, which recompiles an entire module when any file within it changes. True target-level incrementality requires a precise, complete dependency graph - exactly what Bazel BUILD files and Buck2 BUCK files provide.

The mechanism is straightforward in concept: the build system maintains a hash of every input to every build action. When a source file changes, its hash changes. Every target that directly or transitively depends on that file has an input hash change, and must be rebuilt. Every target that doesn't depend on the changed file has an identical input hash to the previous build, and can be retrieved from cache. With Bazel, this computation happens before any compilation starts - the build system knows exactly which targets will be cache hits and which need to be rebuilt.

For a monorepo with 10,000 build targets, a change to a leaf utility function might affect 50 targets directly. A change to a widely-used base library might affect 5,000 targets. The build system computes the affected set precisely and rebuilds only that set - without redundant work and without missing anything. This precision is what makes large-codebase builds practical for agents doing iterative work.

The practical impact is dramatic. In a well-structured codebase with fine-grained targets, a one-line change in a leaf module rebuilds in under 5 seconds regardless of how large the overall codebase is. The build system doesn't care that there are 500,000 lines of code it doesn't need to touch - it skips them all. This property is what makes AI agent iteration loops viable at large codebase scale: the agent's build time is proportional to what changed, not to the total codebase size.

• Build time is proportional to change scope, not codebase size - a one-line change always takes the same time to build regardless of whether the codebase has 10,000 or 10,000,000 lines
• Agent iteration loops hit only the relevant build work - an agent fixing a bug in one module doesn't wait for unrelated modules to compile; the build system proves they're unaffected and skips them
• Developers can work confidently without full rebuilds - when the build system guarantees correct incrementality, there's no reason to run clean; developers and agents trust incremental build results
• Large monorepos become viable for agent workflows - without target-level incrementality, monorepos are impractical for agent iteration; with it, a 10-million-line monorepo has the same iteration speed as a 100,000-line service
• Cache hit rates are objectively measurable and improvable - Bazel reports exact cache hit and miss statistics; teams can track and optimize their cache effectiveness systematically

1. Understand your current dependency graph shape - Use bazel query 'deps(//..., 1)' to see the immediate dependencies of all targets, and bazel query 'rdeps(//..., //path/to:target)' to see what depends on a specific target. Identify "heavy" targets that have many dependents - changes to these will trigger large rebuilds.
2. Split large targets into smaller, more focused targets - A single BUILD target with 50 source files means a change to any of those 50 files triggers rebuilding everything that depends on the target. Split it into smaller targets with clear interfaces. More targets means finer-grained incrementality.
3. Measure your actual affected-target set for common change types - Run bazel query 'rdeps(//..., //path/to:changed_file)' for your most common change types: fixing a bug in a specific service, updating a shared utility, modifying a proto definition. The output tells you exactly how many targets will rebuild for each change type.
4. Identify and isolate wide-impact targets - Proto files, shared configuration, and base utility libraries often affect hundreds or thousands of downstream targets. Small changes to these files trigger large rebuilds. Isolate these targets by minimizing their interfaces and splitting stable from volatile parts.
5. Enforce target granularity standards - Add a BUILD file linting rule that flags targets with more than N source files (N=10 is a reasonable starting point). Large targets are an incrementality anti-pattern. Make fine-grained targets the norm in your BUILD file review process.
6. Configure affected-target-only test runs in CI - Use bazel test $(bazel query 'rdeps(//..., set(//path/to:changed_targets))') to run only tests for targets that depend on what changed. This is the CI equivalent of incremental builds: test only what could have been broken by the current change.

Undeclared file dependencies that force cache misses. If a BUILD target reads a file at build time without declaring it as a dependency, Bazel doesn't know to invalidate the cache when that file changes. The result is either a stale cache hit (incorrect build) or constant cache misses (Bazel detects the undeclared input via sandboxing). Fix undeclared dependencies by declaring them explicitly in BUILD files.

Proto file changes cascading across the entire codebase. Proto files often have hundreds of downstream dependents. A proto change can trigger rebuilds of thousands of targets. Mitigate this by stabilizing proto interfaces, using proto extension fields for evolution, and structuring proto dependencies to minimize the fan-out from any single proto file change.

Overly coarse BUILD target granularity. Teams migrating from Maven/Gradle often create one BUILD target per Maven module - which can have hundreds of source files. This replicates Maven's module-level incrementality rather than achieving target-level incrementality. Break down BUILD targets to be as fine-grained as practical: one target per logical component, typically 5-20 source files.

Not using the incremental test runner. Getting incremental builds without incremental test runs leaves productivity on the table. Bazel supports test caching: if a test and all its dependencies haven't changed, the previous test result is used. Enable test caching with --cache_test_results=yes and verify tests are being cached with --test_summary=detailed.

Modifying widely-used headers or interfaces unnecessarily. In C++ and Rust, changes to header files or trait definitions cascade to all dependents. Developers and agents working on a widely-used interface need to be aware that their change scope is much larger than what they directly modified. Make this visible with bazel query output in code review.