Building a Golden Path: The Platform Engineering Playbook

The Platform Paradox

We've seen it a dozen times: a company invests months building an Internal Developer Platform (IDP). Beautiful documentation, comprehensive tooling, exec sponsorship. Launch day arrives and... developers keep doing things the old way.

Why? Because most IDPs fall into one of two traps:

• Too restrictive – "You can only deploy Node.js services using our approved template." Developers route around it.
• Too permissive – "Here are 50 tools, figure it out." Nobody knows what to use.

The solution: golden paths.

What is a Golden Path?

A golden path is the easiest way to do the right thing. It's a pre-configured, well-documented, production-ready path from code to deployment—but not the only path.

Think of it like a highway system: there's a fast, safe route (the golden path), but you can take side roads if you need to. Most developers stay on the highway because it's faster.

The Golden Path Framework

1. Start with Real Pain Points

Don't build a platform in a vacuum. Interview 10+ developers and ask:

• What takes longest in your workflow?
• What do you dread doing?
• What do you have to ask DevOps for?

Common answers: "Spinning up a new service takes 2 weeks," "I don't know how to add monitoring," "Getting database access requires 5 approvals."

Build for those pain points first. Not what you think they need—what they actually struggle with.

2. Design Service Templates

Create scaffolding templates that include:

• Infrastructure – Kubernetes manifests, Terraform configs, load balancers pre-configured
• Observability – Prometheus metrics, structured logging, tracing built-in
• CI/CD – GitHub Actions workflows with testing, security scanning, deployment
• Security – Secret management, mTLS, RBAC policies configured

Example: npx create-service my-api --template=node-express generates a production-ready API with all of the above.

3. Make Documentation Executable

Nobody reads docs. Make them interactive:

• Runbooks as code – Use tools like Runme or executable Markdown
• CLI wizards – Guide developers through complex tasks step-by-step
• Video walkthroughs – 3-minute Loom videos showing common tasks

Documentation should answer: "How do I deploy this?" not "What is our platform philosophy?"

4. Build a Service Catalog

Use Backstage, Port, or a custom portal to show:

• All services and who owns them
• Dependencies and API docs
• Health metrics and on-call rotations
• Cost per service

Developers need to discover what already exists before building something new.

5. Provide Escape Hatches

The golden path won't work for every use case. Provide clear exit ramps:

• Custom overrides – Let teams customize templates when needed
• Migration guides – "If you need X, here's how to move off the golden path"
• Exception process – Clear criteria for when deviations are okay

Teams that feel trapped by the platform will rebel. Give them controlled freedom.

Measuring Success

Track these metrics to know if your golden path is working:

• Adoption rate – % of services using platform templates
• Time to first deployment – How long from "create service" to production?
• Developer satisfaction – Quarterly surveys (NPS for the platform)
• Support tickets – Decreasing tickets = better self-service

Our target: 80%+ adoption within 6 months, <20 minute time to first deploy.

Common Mistakes to Avoid

• Building in isolation – Platform teams that don't talk to developers build the wrong thing
• Big bang launches – Start with 1-2 teams as early adopters, iterate, then expand
• Ignoring feedback – If developers complain about something, fix it or explain why you can't
• Over-engineering – Start simple. You can always add complexity later.

Real Example: Node.js Golden Path

For a 60-person engineering team, we built a Node.js golden path:

• Template: Express API with TypeScript, Prisma ORM, Jest tests, Docker multi-stage build
• Infrastructure: Kubernetes deployment, Postgres database, Redis cache—provisioned automatically
• CI/CD: GitHub Actions with parallel tests, Docker build caching, automated deployments to staging/prod
• Observability: Prometheus metrics endpoint, structured JSON logging, distributed tracing with Jaeger
• Time to production: 18 minutes from npx create-service to live in staging

Adoption: 90% of new services used the template within 3 months. Why? Because it was faster than doing it manually.

Conclusion

Golden paths aren't about control—they're about velocity. When the right way is the easiest way, developers naturally adopt it.

Start small: pick one pain point (e.g., "new service setup"), build a golden path for it, and measure adoption. Once you prove value, expand to other workflows.

The goal isn't to force everyone onto the highway. It's to make the highway so good that nobody wants to take the back roads.

---

Need help building an Internal Developer Platform? Let's talk. We've designed golden paths for teams ranging from 20 to 200 engineers.