| name | service-template |
| description | Design a maintainable service or workload template that captures approved defaults without freezing consumers to stale generated code, hidden infrastructure assumptions, or unsafe credentials. |
Service Template
Use when a platform needs repeatable starting artifacts for a common service, worker, application, or integration pattern.
Procedure
- Define the workload class, supported runtimes/stacks, and which concerns the template should solve versus leave to the application team.
- Inventory the minimum approved defaults: project layout, build/test entry points, configuration contract, health behavior, identity, telemetry, deployment metadata, ownership, and documentation.
- Keep generated code minimal and ordinary. Prefer platform-provided reusable capabilities for evolving behavior rather than copying large framework/platform internals into every repository.
- Do not embed credentials, node addresses, environment-specific secrets, mutable resource IDs, or assumptions about one deployment target. Resolve environment/runtime details through accepted configuration and platform contracts.
- Make parameters explicit and validate them before generation. Avoid a combinatorial template with switches for every historical exception.
- Define how dependencies and versions are selected, pinned, upgraded, and audited. Template creation should produce a reproducible starting state.
- Include a small executable example or smoke path that proves the generated project can build/test/run using the supported workflow.
- Define template evolution. Separate fixes that should reach existing services through shared tooling/dependencies from changes that only affect newly generated projects; provide migrations when existing consumers need updates.
- Test generation from a clean environment and validate the result as a consumer would, including CI/deployment integration where practical.
Decision rules
- A template is a starting point, not a control plane.
- Avoid copying logic into every service when a maintained shared capability can enforce or deliver it centrally.
- Do not add options until real consumers demonstrate distinct needs.
- Fleet-compatible workloads should remain portable; placement-specific state belongs to Fleet/node runtime metadata, not the template.
Quality gate
The template is ready when clean generation produces a small understandable project with approved defaults, no machine-specific or secret state is embedded, versions are reproducible, the supported workflow succeeds from scratch, and there is a clear strategy for future platform changes affecting existing consumers.
