Platform Engineering 04 - Designing Golden Paths

The Road People Choose

Post 01 introduced the concept of golden paths — the recommended, well-supported way to perform a given task. This post moves into the practical side of things. How do you actually design a golden path, and how do you respond when teams decide to go off-road?

What Makes a Good One

Not all golden paths carry the same value. A poorly designed golden path feels like bureaucracy, while a well-designed one feels like a shortcut. Three principles separate the two.

First, a golden path must be optional, not mandatory. The moment it is forced, it stops being a path and becomes a fence. Developers should follow it because it is genuinely the better choice, not because they were told to.

Second, adoption must be easy. If getting on the path requires a week of migration work, most teams will not bother trying. The on-ramp matters just as much as the road itself.

Third, it must be well-documented. A golden path without documentation is just a route that someone on the platform team happens to know about. It needs to be written down, and the documentation should explain not just the "how" but also the "why."

Step by Step

Start by picking a workflow. Something that is both common and painful tends to be the most effective first target, and "deploy a web service" is a classic choice.

Next, map the current state. Talk to three to five teams and listen to how they do things today and where they experience friction.

Then design the ideal path. The key is distinguishing between what the developer should do directly and what the platform should handle automatically.

Once the path is defined, build the template. This should include the repository structure, CI configuration, Dockerfile, deployment manifests, and observability setup — everything a team needs to get started.

Don't launch broadly right away. Find one team willing to try it first and observe where they get stuck.

Finally, smooth out the rough edges, write the documentation, and open it up to the rest of the organization.

Project Templates

The entry point for most golden paths is a project template.

my-service-template/
├── src/                    # starter code with health check endpoint
├── Dockerfile              # production-ready, multi-stage build
├── .github/workflows/      # CI pipeline pre-configured
├── k8s/                    # deployment manifests with sane defaults
├── observability/           # logging and metrics config
├── README.md               # "run this to get started"
└── Makefile                # common commands: build, test, deploy

This template should work out of the box. The goal is that running git clone followed by make run brings up a service with CI, deployment, and monitoring already wired together.

Examples

For a web service golden path, the platform provides a template repository that includes framework scaffolding, a CI pipeline, Kubernetes manifests, Prometheus metrics, and structured logging. A developer clones it, changes the service name, pushes, and within minutes the service is deployed to staging.

For a data pipeline golden path, the template includes an Airflow DAG structure, data quality checks, warehouse connections, and failure alerting. The data engineer fills in the transformation logic, and the platform handles everything else.

When Teams Go Off-Road

Teams leaving the golden path is inevitable. Since the path is optional by design, this is a natural occurrence. What matters is understanding why they are leaving.

Reason	Response
Golden path doesn't support their use case	Extend the path or document the exception
Team didn't know it existed	Improve discovery and onboarding
Team prefers their own way out of habit	Show the benefits, don't force
Golden path has a real limitation	Fix it -- valuable feedback

The worst response is to mandate adoption. The most effective response is to make the golden path good enough that going off-road feels like unnecessary effort.

Where It Gets Real

Golden paths are where platform engineering transitions from an abstract concept to something tangible. They are not architecture diagrams or strategy decks — they are the actual artifacts that developers interact with every day.

A well-designed golden path multiplies productivity across every team that adopts it. A poorly designed one becomes shelfware that surfaces as a recurring complaint in retrospectives.

Next time: infrastructure as code — the foundation that golden paths are built on.