Authoring Production Builders

Production builders should grow from a small domain surface into a reliable program, not from a large compatibility wrapper. Start with the artifact, name the domain concepts, then expose the standard views that make the builder inspectable.

Begin With The Smallest Useful Constructor

A first constructor should accept only the choices needed to produce the artifact. More options can be added when the builder has a real domain reason for them.

Add Typed Configuration Deliberately

Typed configuration is valuable when it clarifies the build vocabulary. Avoid adding fields only because an underlying command happens to have many flags. A field earns its place when a view becomes more meaningful for having it.

Prefer Descriptors Over Hidden Conventions

If downstream users need to know something, put it in a descriptor. Do not make them infer important facts from path names or shell snippets.

Keep Views In The Contract

Validation, dependency graph, dry-run, plan-view, describe, introspect, and materialize are not only development helpers. They are part of how users learn and trust the builder, so treat their output as a public contract.

Test The Views That Matter

Tests should pin the views that define the builder's public contract. Useful anchors are that validation succeeds for supported specs, that the dependency graph includes the expected tools and operations, that dry-run explains the intended workflow, that plan-view includes the expected materialization shape, and that materialization produces the promised outputs.

Avoid Compatibility Before Release

Do not add compatibility shims before there is a public compatibility problem. Early builders should be shaped around the model you want users to learn.