The Architect

Once repository policy is stable, other maintainers begin depending on the Starlark surfaces behind it. Level 4 is about designing contracts they can load, call, extend, test, and publish.

Macros, rules, providers, toolchains, and module extensions may all look like “some Starlark,” but they serve different consumers and phases. Choose the smallest surface that expresses the required boundary before callers depend on an accidental one.

Match The Mechanism To Its Consumer

Start with the smallest contract. 4.1 Macro Design & Rule-Authoring Starlark asks whether the abstraction belongs to loading or analysis: is it only shaping BUILD declarations, or is it defining target meaning? 4.2 Custom Rules, Providers & Actions is where that decision becomes a target kind: attributes in, providers and declared actions out. Together they form the rule-authoring core.

Then make the contract usable. 4.3 Starlark Development Tools is the feedback loop: formatting, macro expansion inspection, print probes, editor integration, debugging, and scratchpads each answer a different layer of question. 4.4 Production Rule Surface turns a working rule into a surface other teams can rely on: public attrs, provider fields, runfiles, launched environments, action requirements, and worker mode. 4.5 Rule Testing & Documentation proves those promises with analysis tests, integration fixtures, executable examples, and generated API docs.

After one target kind works, the architecture expands into configured graphs. 4.6 Toolchains & Platform Resolution reframes Level 3 platforms as rule-author inputs: what the artifact targets, where tools run, which toolchain type is required, and when one rule needs several execution sides. 4.7 Build Settings & Transitions handles the values that flow across dependency edges. Read both with restraint. Every unnecessary configuration fork becomes analysis cost and another shape future maintainers must explain.

The next step is crossing boundaries without making every rule carry every concern. 4.8 Aspects gives cross-cutting analysis a shadow graph for IDE metadata, linting, SBOMs, refactoring, and similar overlays. 4.9 Repository Rules moves outside ordinary action execution into external repository materialization: downloads, generated BUILD files, host tools, credential helpers, and reproducibility tracking. 4.10 Authoring Module Extensions sits above that in the Bzlmod graph, collecting tags across modules and deciding which repositories should exist.

4.11 Ruleset Packaging & Publishing handles the handoff to ruleset consumers through public entry points, module metadata, releases, CI gates, and compatibility policy. 4.12 Experimental Rule Patterns is an optional look at dynamic actions, rule extension APIs, subrules, and materializer rules; those mechanisms are design vocabulary, not defaults for ordinary rules. 4.13 Build a Ruleset End-to-End then assembles the stable mechanisms into one tested ruleset.

Read By The Pressure You Have

If you are new to rule authoring, read the level in three passes. First read 4.1 Macro Design & Rule-Authoring Starlark and 4.2 Custom Rules, Providers & Actions for the phase model and target contract. Then keep 4.3 Starlark Development Tools open while you write the first macro or rule, because the fastest feedback loop is part of the authoring skill. Before sharing that rule, move through 4.4 Production Rule Surface and 4.5 Rule Testing & Documentation so "it builds" does not become the only success criterion.

If the pressure is platform or tool selection, go to 4.6 Toolchains & Platform Resolution and then 4.10 Authoring Module Extensions or 4.11 Ruleset Packaging & Publishing if the setup must be reusable. If the pressure is multi-configuration output, go to 4.7 Build Settings & Transitions. If the pressure is metadata, linting, IDEs, or whole-repo traversal, go to 4.8 Aspects. If the pressure is external dependency materialization, private downloads, host discovery, or slow fetches, go to 4.9 Repository Rules.

Use 4.13 Build a Ruleset End-to-End as the consolidation step after the relevant concept articles. Its runnable project shows the order in which contracts must stabilize before another layer can depend on them.

When the contract is correct but the build is still slow, surprising, or hard to explain, continue into 5.2 Query and the rest of Level 5. Level 4 teaches how to design Bazel abstractions. Level 5 teaches how to gather evidence when those abstractions meet a large real graph.

Next: diagnose the configured graphs and actions produced by those abstractions with 5.2 Query.