Compilation bottleneck eliminated via crate/module architecture

Compilation bottleneck elimination through crate/module architecture means restructuring a codebase so that the unit of compilation is small, focused, and independently compilable. In Rust, this means splitting a large crate into many small, well-defined crates. In Java or Kotlin, it means splitting large modules into fine-grained Gradle subprojects or Bazel targets. In TypeScript, it means separating packages in a monorepo so that tsc compiles each package independently. The structural goal in every language is the same: no single compilation unit is so large that it becomes a serialization bottleneck, and independent units can compile in parallel.

Cursor's engineering team discovered this problem empirically when scaling to hundreds of simultaneous agents. Their Rust codebase had large crates that took several minutes to compile. When 10 agents were all modifying files in those large crates simultaneously, they each triggered full recompilation of the crate, and the compilation jobs serialized on shared resources. The solution was structural: split the large crates into smaller, more focused crates with explicit dependency declarations. Smaller crates compile faster individually and, more importantly, can compile in parallel - an agent modifying crate A doesn't block another agent modifying crate B if A and B don't depend on each other.

The compilation unit structure also affects the remote execution model. A Bazel build for a well-structured codebase with 500 fine-grained targets can distribute those 500 compilation jobs across 500 remote workers simultaneously. A poorly structured codebase with 5 large targets can only use 5 workers - the parallelism ceiling is the number of independent build targets. Architecture directly determines how much remote execution parallelism is available.

This is fundamentally an architectural concern, not just a build system configuration concern. BUILD file ownership conventions, crate design philosophy, package structure in package.json workspaces, and module decomposition decisions all need to be made with compilation parallelism in mind. The principle: prefer many small, focused units over few large ones - not just for software engineering reasons, but because small units enable the parallel agent compilation that makes commodity build speeds achievable.

• Compilation parallelism ceiling is set by architecture - a codebase with 10 large modules can use at most 10 parallel compilers; a codebase with 500 fine-grained targets can use 500; the difference is 50x potential parallelism
• Concurrent agents amplify the cost of large compilation units - when 20 agents are each modifying files in the same large module, all 20 trigger the same expensive full-module recompilation; with fine-grained targets, each agent typically touches an independent target
• Agent isolation improves with smaller compilation units - agents working on separate small crates/modules truly don't affect each other's build times; agents working in different parts of a large monolithic module still share compilation overhead
• Incremental compilation effectiveness increases with smaller units - smaller compilation units have fewer files, so a change to one file invalidates a smaller fraction of the unit's compiled output; fine-grained targets approach "one file change = one file compiled"
• Code review and ownership become cleaner - small, focused compilation units align naturally with team ownership and code review boundaries; BUILD files make ownership explicit

1. Profile your compilation bottlenecks - Identify which compilation units (crates, modules, targets) take the longest to compile from scratch and have the highest fan-out (most other targets depend on them). These are your primary optimization targets. In Rust: cargo build --timings. In Bazel: build scan profiles. Focus on the top 5 by compile time.
2. Set maximum compilation unit size guidelines - Establish a convention: no Rust crate over 20,000 lines of code, no Java module over 10,000 lines, no Bazel target over 15 source files. These thresholds are starting points, not absolute rules - calibrate based on your measured compilation times.
3. Split the largest compilation units first - Choose the largest, slowest-compiling unit and split it along natural domain boundaries. Identify which code within the unit is stable (rarely changes) vs. volatile (changes frequently). Move stable code to a foundation crate/module; keep volatile code in a thinner layer on top. This split immediately speeds up incremental builds for changes to the volatile layer.
4. Declare explicit dependency interfaces - When splitting a large unit into smaller ones, make the inter-unit dependencies explicit: trait bounds in Rust, interfaces in Java, index.ts re-exports in TypeScript. Explicit interfaces enforce the modular structure and prevent re-entanglement of the split units.
5. Validate parallelism improvement - After splitting a large unit, measure the time to compile both resulting units sequentially vs. in parallel. If the parallel time is significantly lower than the sequential time and the individual unit times are each faster than the original, the split is working correctly.
6. Establish BUILD file review as an architectural gate - Require senior engineer review for any BUILD file change that creates a target with more than 15 source files or that adds a dependency from a widely-used library to a new dependee. These are the changes that can inadvertently create compilation bottlenecks.

Splitting without defining stable interfaces. Splitting a large crate into 5 smaller crates with circular dependencies or too-tight interfaces doesn't deliver the expected parallel compilation benefit. The split must expose clean interfaces. If you find yourself splitting and then immediately pulling split units back together to share implementation, the split boundary was wrong.

Over-splitting to the point of excessive dependency management overhead. 500 crates with 5 files each is not better than 50 crates with 50 files each - the overhead of managing 500 dependency declarations, 500 BUILD files, and 500 versioned APIs creates maintenance work that exceeds the build time savings. Find the granularity sweet spot: small enough for fast incremental compilation, large enough to represent a coherent unit of functionality.

Not aligning compilation units with team boundaries. A compilation unit that multiple teams co-own becomes a coordination bottleneck - two teams simultaneously changing different parts of the unit merge their build costs. Align compilation unit ownership with team ownership. If team A owns crate A and team B owns crate B, they can work in parallel with no build interference.

Ignoring the cost of interface evolution. Fine-grained crates with explicit interfaces create more interface evolution work. Adding a method to an interface in a widely-used crate requires updating all dependents. Teams that split aggressively but then frequently evolve shared interfaces may find that the merge and API evolution cost exceeds the build time savings. Stabilize interfaces before splitting aggressively.

Treating this as a one-time refactoring. Compilation unit structure degrades over time as code is added, shortcuts are taken, and BUILD files get large targets appended rather than split. Schedule quarterly BUILD file audits to identify target granularity violations. Make "target too large" a CI lint rule that fails the build when any target exceeds the maximum size guideline.