Skip to content

PATTERN Cited by 1 source

Template project nudges consistency

Context

A platform / infrastructure team wants every new service at the company to ship with the "right" defaults: observability wired up, AuthN/AuthZ configured, CI pipelines, linters, test scaffolding, deployment manifests, baseline dependencies at supported versions. Two extremes fail:

  • Pure mandates / policy enforcement (you MUST use library X, framework Y) breeds resentment, doesn't scale to the long tail of "reasonable exceptions", and requires ongoing enforcement infrastructure.
  • Pure laissez-faire leaves each team to assemble the stack from scratch — duplicated work, divergent choices, fleet-wide operability erosion.

Pattern

Ship a template project — a bootstrap-able service scaffold carrying out-of-the-box configuration and platform integrations — through the internal developer tooling, so that creating a new service produces a working baseline with all the platform defaults already wired. Teams adapt the template to their needs rather than assembling from scratch, but the defaults become the path of least resistance.

This is a nudge, not a gate. Teams can deviate; most won't, because the template is cheaper than rolling their own.

The Zalando instantiation

From the [[sources/2021-06-30-zalando-how-we-use-kotlin-for-backend-services|2021 Kotlin adoption post]]:

Our internal developer tooling allows to initialize a repository from a template project. Those come with out-of-the box configuration and integrations which teams can then adapt to their needs. As an added benefit, they nudge teams towards higher consistency across different services and departments.

Critically, a template project is what the Kotlin Tech Radar ADOPT promotion required — the Kotlin Guild had to produce the template before Kotlin could graduate from TRIAL to ADOPT. The template is the observable artefact of the platform team's commitment to support the technology.

Mechanics

  • Repository-init CLI (scaffold generator) — teams run <internal-tool> new my-service and get a fresh repo.
  • Pre-wired platform integrations — OpenAPI stub, Zally CI job, Skipper ingress manifest, opentracing-toolbox dependency, Dockerfile, K8s manifests, observability config (metrics + logs + traces).
  • Baseline tests — smoke + integration tests that pass out-of-the-box so CI is green from commit 0.
  • Light opinionation on business logic layout — the template shouldn't dictate domain structure, only infra/cross-cutting wiring.

Why nudges beat mandates at scale

  • Attrition of exceptions: every mandate generates legitimate exceptions; enforcement cost scales with exception surface.
  • Platform team bandwidth: the same team that would enforce compliance also has to maintain the platform; template investment is work once, compliance policing is work forever.
  • Team autonomy preserved: teams that genuinely need to deviate (latency-critical hot-path, unusual domain constraints) can still do so, at the cost of losing the default integrations. This is the right cost structure.
  • Template evolves with the platform: when the platform team ships a new observability default, they update the template; new services get it automatically; existing services adopt it on their own cadence.

Trade-offs / failure modes

  • Template staleness — once shipped, the template must be actively maintained. A stale template is a vector for spreading outdated defaults across the fleet.
  • Template complexity creep — "just add one more feature" pressure over time can turn a 10-minute-to-grok scaffold into a 2-day onboarding exercise.
  • Invisibility of the "why" — teams bootstrap from the template without understanding why the defaults are the defaults; when they deviate, they deviate without awareness of what they're giving up.
  • Doesn't solve drift — new services get the defaults, but existing services diverge over time. A template alone won't reconverge the fleet; you still need migration tooling / lint-gate enforcement for cross-fleet consistency.

Seen in

Last updated · 476 distilled / 1,218 read