Golden Paths

Patterns for designing standardized, opinionated development workflows that make the right way the easy way.

When to Use This Skill

• Designing standardized developer workflows
• Creating paved roads for common patterns
• Building template-based service creation
• Implementing guardrails with flexibility
• Optimizing developer onboarding
• Reducing cognitive load for developers

Golden Path Fundamentals

What is a Golden Path?

Golden Path Definition:
An opinionated, well-supported workflow that makes best practices
the path of least resistance while not blocking alternatives.

Key Characteristics:
┌─────────────────────────────────────────────────────────────┐
│                    GOLDEN PATH                               │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ✓ Opinionated:  Clear decisions made for you               │
│  ✓ Supported:    First-class documentation and tooling      │
│  ✓ Optimized:    Fastest path to production                 │
│  ✓ Maintained:   Kept up-to-date by platform team           │
│  ✓ Escapable:    Can deviate when needed                    │
│                                                              │
│  "Make the right way the easy way"                          │
│                                                              │
│  Golden Path ≠ The Only Path                                │
│  Golden Path = The Recommended Path                         │
│                                                              │
└─────────────────────────────────────────────────────────────┘

vs Paved Road vs Rails:
├── Golden Path: Recommended workflow with alternatives
├── Paved Road: Same concept, Spotify terminology
├── Rails: More rigid, harder to deviate (often negative)

Golden Path vs Custom

Golden Path Benefits:

Developer Time:
├── New service: 15 min (golden) vs 2 days (custom)
├── Setup CI/CD: Automatic vs 4-8 hours
├── Observability: Built-in vs manual integration
└── Security: Automatic vs checklist review

Platform Support:
├── Golden path: Full support, rapid fixes
├── Custom: Best-effort support, lower priority
├── Hybrid: Support for platform components only

Example Journey:

Golden Path:
┌─────────────────────────────────────────────────────────────┐
│ 1. Choose template     → node-api-template                  │
│ 2. Answer questions    → name, team, database?             │
│ 3. Generate repo       → automatic                         │
│ 4. First deployment    → automatic via CI                  │
│ 5. Start coding        → focus on business logic           │
│                                                              │
│ Time: ~15 minutes                                           │
│ Result: Production-ready service                            │
└─────────────────────────────────────────────────────────────┘

Custom Path:
┌─────────────────────────────────────────────────────────────┐
│ 1. Create repo         → manual setup                       │
│ 2. Choose framework    → research options                   │
│ 3. Setup build         → configure bundler/compiler         │
│ 4. Add observability   → integrate logging, metrics         │
│ 5. Security review     → checklist, manual fixes            │
│ 6. Setup CI/CD         → write pipeline config              │
│ 7. Deploy pipeline     → debug issues                       │
│ 8. Documentation       → write from scratch                 │
│                                                              │
│ Time: 2-5 days                                              │
│ Result: May miss best practices                             │
└─────────────────────────────────────────────────────────────┘

Designing Golden Paths

Identifying Candidates

Golden Path Selection Criteria:

High-Value Candidates:
├── Frequent: Done by many teams regularly
├── Complex: Easy to get wrong
├── Critical: Security/compliance implications
├── Costly: Takes significant time manually
└── Standardizable: Common pattern across teams

Assessment Matrix:
┌────────────────────────────────────────────────────────────┐
│               Frequency                                     │
│            Low          High                                │
│         ┌─────────────┬─────────────┐                      │
│  High   │ Custom      │ GOLDEN PATH │ ← High Impact        │
│         │ Solution    │ PRIORITY    │                      │
│ Impact  ├─────────────┼─────────────┤                      │
│  Low    │ Ignore      │ Document/   │                      │
│         │             │ Automate    │                      │
│         └─────────────┴─────────────┘                      │
└────────────────────────────────────────────────────────────┘

Common Golden Paths:
1. New service creation (by service type)
2. Database provisioning
3. CI/CD pipeline setup
4. Security scanning integration
5. Observability setup
6. Environment creation
7. API development workflow
8. Frontend application setup

Template Design Principles

Template Design:

1. Opinionated Defaults
   ├── Make decisions so developers don't have to
   ├── Choose proven technologies
   ├── Use sensible configurations
   └── Document why choices were made

2. Minimal Required Input
   ├── Service name
   ├── Team/owner
   ├── 1-3 key configuration choices
   └── Everything else has defaults

3. Complete Package
   ┌─────────────────────────────────────────────────────────┐
   │ Template Contents:                                       │
   │                                                          │
   │ Application Layer:                                       │
   │ ├── Application code skeleton                            │
   │ ├── Configuration management                             │
   │ ├── Health check endpoints                               │
   │ └── API documentation setup                              │
   │                                                          │
   │ Quality Layer:                                           │
   │ ├── Unit test framework                                  │
   │ ├── Integration test setup                               │
   │ ├── Linting and formatting                               │
   │ └── Pre-commit hooks                                     │
   │                                                          │
   │ Operations Layer:                                        │
   │ ├── Dockerfile                                           │
   │ ├── Kubernetes manifests                                 │
   │ ├── CI/CD pipeline                                       │
   │ └── Infrastructure as Code                               │
   │                                                          │
   │ Observability Layer:                                     │
   │ ├── Structured logging                                   │
   │ ├── Metrics instrumentation                              │
   │ ├── Distributed tracing                                  │
   │ └── Dashboard templates                                  │
   │                                                          │
   │ Documentation Layer:                                     │
   │ ├── README template                                      │
   │ ├── ADR templates                                        │
   │ ├── Runbook templates                                    │
   │ └── API specification                                    │
   └─────────────────────────────────────────────────────────┘

4. Clear Extension Points
   ├── Where to add business logic
   ├── How to add new endpoints
   ├── How to integrate dependencies
   └── How to customize behavior

Template Architecture

Template Implementation Patterns:

1. Scaffolding/Generation (Backstage, Yeoman)
   Input → Template + Variables → Generated Repo

   Pros: Simple, full control
   Cons: Generated code diverges over time

2. Cookiecutter/Copier
   Template repo → Variable substitution → New repo

   Pros: Easy to maintain templates
   Cons: Post-generation updates hard

3. Base Image/Library Pattern
   ┌─────────────────────────────────────────────────────────┐
   │                Application Code                          │
   │                      │                                   │
   │                      ▼                                   │
   │  ┌─────────────────────────────────────────────────┐    │
   │  │           Company Base Library                   │    │
   │  │  ├── Logging (preconfigured)                    │    │
   │  │  ├── Metrics (preconfigured)                    │    │
   │  │  ├── Tracing (preconfigured)                    │    │
   │  │  ├── HTTP client (with retry)                   │    │
   │  │  └── Health checks (standard)                   │    │
   │  └─────────────────────────────────────────────────┘    │
   │                      │                                   │
   │                      ▼                                   │
   │  ┌─────────────────────────────────────────────────┐    │
   │  │           Company Base Image                     │    │
   │  │  ├── Runtime (Node, Go, .NET)                   │    │
   │  │  ├── Security patches                           │    │
   │  │  └── Standard tooling                           │    │
   │  └─────────────────────────────────────────────────┘    │
   └─────────────────────────────────────────────────────────┘

   Pros: Updates propagate automatically
   Cons: Requires versioning strategy

4. Mono-Repo with Generators
   Centralized templates → Generated into mono-repo

   Pros: Consistency, shared tooling
   Cons: Mono-repo complexity

Guardrails and Flexibility

Guardrail Design

Guardrails: Automatic enforcement of standards without blocking.

Types of Guardrails:

1. Preventive (Block before it happens)
   ├── Pre-commit hooks
   ├── PR checks
   ├── Template validation
   └── Infrastructure policies

2. Detective (Alert after it happens)
   ├── Compliance scans
   ├── Drift detection
   ├── Audit logs
   └── Security scanning

3. Corrective (Auto-fix issues)
   ├── Auto-formatting
   ├── Auto-remediation
   ├── Self-healing infrastructure
   └── Automated rollbacks

Guardrail Implementation:
┌─────────────────────────────────────────────────────────────┐
│                 DEVELOPMENT LIFECYCLE                        │
│                                                              │
│  Code ──► Commit ──► PR ──► Merge ──► Deploy ──► Production │
│    │        │        │        │         │           │       │
│    ▼        ▼        ▼        ▼         ▼           ▼       │
│ [Lint]  [Pre-    [PR      [Build   [Deploy    [Runtime     │
│ [Format] commit]  checks]  gates]   policies]  monitoring] │
│                                                              │
│  Guardrails at each stage:                                  │
│  ├── IDE: Real-time feedback, auto-fix                      │
│  ├── Commit: Secrets scan, lint                             │
│  ├── PR: Tests, security scan, approval                     │
│  ├── Build: Vulnerability scan, compliance                  │
│  ├── Deploy: Canary, health checks                          │
│  └── Runtime: Anomaly detection, auto-scale                 │
└─────────────────────────────────────────────────────────────┘

Escape Hatches

Escape Hatches: How to deviate from golden path when needed.

Principles:
├── Make deviation possible but intentional
├── Require justification, not approval
├── Don't punish teams for legitimate needs
└── Learn from deviations to improve paths

Escape Hatch Patterns:

1. Documented Exception
   # .platform/exceptions.yaml
   exceptions:
     - rule: must-use-company-base-image
       reason: "ML workload requires specific CUDA version"
       approved-by: platform-team
       expires: 2024-12-31
       review-issue: PLAT-1234

2. Tiered Support
   ┌─────────────────────────────────────────────────────────┐
   │ Tier 1: Golden Path                                      │
   │ - Full support                                           │
   │ - Automatic updates                                      │
   │ - Priority bug fixes                                     │
   │                                                          │
   │ Tier 2: Supported Deviation                              │
   │ - Documented exception                                   │
   │ - Best-effort support                                    │
   │ - Manual updates may be needed                           │
   │                                                          │
   │ Tier 3: Custom                                           │
   │ - Self-supported                                         │
   │ - No guarantees                                          │
   │ - Must meet minimum security standards                   │
   └─────────────────────────────────────────────────────────┘

3. Override Mechanism
   # pipeline.yaml
   lint:
     enabled: true
     override: true  # Skip for this repo
     override-reason: "Legacy code, lint fix scheduled for Q2"

Common Golden Paths

Service Creation Path

Service Creation Golden Path:

┌─────────────────────────────────────────────────────────────┐
│ Step 1: Select Template                                      │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Available Templates:                                        │
│  ○ REST API (Node.js)     - Standard HTTP API               │
│  ○ REST API (Go)          - High-performance API            │
│  ○ REST API (.NET)        - Enterprise API                  │
│  ● GraphQL Service        - Flexible API layer              │
│  ○ Event Consumer         - Kafka/message processing        │
│  ○ Scheduled Job          - Batch/cron workloads            │
│                                                              │
│  [Continue with GraphQL Service]                            │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ Step 2: Configure Service                                    │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  Service Name: _________ (kebab-case, e.g., user-service)   │
│  Owner Team:   [▼ Select team ]                             │
│  Description:  _________________________________________     │
│                                                              │
│  Optional Features:                                          │
│  ☑ Database (PostgreSQL)                                    │
│  ☐ Cache (Redis)                                            │
│  ☑ Message Queue (Kafka consumer)                           │
│  ☐ External API Client                                      │
│                                                              │
│  [Create Service]                                           │
└─────────────────────────────────────────────────────────────┘

┌─────────────────────────────────────────────────────────────┐
│ Step 3: Automatic Setup (60 seconds)                         │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ✓ Repository created         github.com/org/user-service   │
│  ✓ CI/CD pipeline configured  Actions workflow created      │
│  ✓ Dev environment ready      user-service.dev.internal     │
│  ✓ Database provisioned       PostgreSQL on RDS             │
│  ✓ Secrets configured         Vault paths created           │
│  ✓ Monitoring setup           Datadog dashboards created    │
│  ✓ Registered in catalog      Backstage entry created       │
│                                                              │
│  [Open Repository] [View in Catalog] [Start Coding]         │
└─────────────────────────────────────────────────────────────┘

Deployment Path

Deployment Golden Path:

Developer Workflow:
┌─────────────────────────────────────────────────────────────┐
│                                                              │
│  1. Developer pushes to feature branch                      │
│     └── Automatic: lint, test, build, security scan         │
│                                                              │
│  2. Developer opens PR                                      │
│     └── Automatic: preview environment, E2E tests           │
│                                                              │
│  3. PR approved and merged                                  │
│     └── Automatic: deploy to staging                        │
│                                                              │
│  4. Staging validation (automated + manual)                 │
│     └── Automatic: smoke tests, synthetic monitoring        │
│                                                              │
│  5. Production deployment                                   │
│     └── Automatic: canary → gradual rollout                 │
│                                                              │
│  No manual steps required for standard deployments          │
└─────────────────────────────────────────────────────────────┘

Pipeline Configuration:
# Comes pre-configured in template
# Developers only modify if needed

deploy:
  staging:
    trigger: merge-to-main
    strategy: rolling
    tests: [smoke, integration]

  production:
    trigger: staging-success
    strategy: canary
    canary-percentage: 5
    canary-duration: 15m
    rollback: automatic

Adoption Strategy

Rolling Out Golden Paths

Adoption Phases:

Phase 1: Pilot (1-2 teams, 1-2 months)
├── Partner with friendly teams
├── Gather intensive feedback
├── Iterate rapidly
├── Build success stories
└── Document learnings

Phase 2: Early Adopters (5-10 teams, 2-3 months)
├── Expand to interested teams
├── Refine based on feedback
├── Build champions network
├── Create training materials
└── Measure adoption metrics

Phase 3: Early Majority (30-50% teams, 3-6 months)
├── Marketing and communication
├── Training sessions
├── Self-service documentation
├── Deprecate old paths
└── Track DORA metrics

Phase 4: Late Majority (70-90% teams, 6-12 months)
├── Mandate for new services
├── Migration support for existing
├── Advanced features
├── Refinement and optimization
└── Continuous improvement

Adoption Tactics:
├── Make golden path faster than alternatives
├── Provide migration tooling
├── Celebrate early adopters
├── Address blockers quickly
├── Don't force premature adoption
└── Listen to resistors (they find real issues)

Measuring Success

Golden Path Metrics:

Adoption Metrics:
├── % new services using templates
├── % teams with at least one golden path service
├── Template usage by type
├── Deviation rate (why teams don't use)
└── Migration rate (legacy to golden path)

Efficiency Metrics:
├── Time to first deployment (new service)
├── Time to production change
├── PR cycle time
├── Incident resolution time
└── Developer time saved

Quality Metrics:
├── Deployment success rate
├── Security scan pass rate
├── Change failure rate
├── Incident rate (golden vs custom)
└── Compliance audit findings

Satisfaction Metrics:
├── Developer NPS for platform
├── Template satisfaction surveys
├── Support ticket volume
├── Documentation effectiveness
└── Onboarding experience rating

Anti-Patterns

Golden Path Anti-Patterns:

1. "One Golden Path for All"
   ❌ Same template for microservices and ML workloads
   ✓ Multiple paths for different use cases

2. "Rails, Not Paths"
   ❌ Making deviation impossible or punished
   ✓ Deviation possible with justification

3. "Technical Purity Over Practicality"
   ❌ Choosing trendy tech that teams struggle with
   ✓ Use tech teams can actually use

4. "Set and Forget"
   ❌ Creating path once and never updating
   ✓ Continuous improvement based on feedback

5. "Mandate Without Value"
   ❌ Forcing adoption before path is good
   ✓ Make path so good teams want to use it

6. "Complexity Hiding"
   ❌ Hiding all complexity, no learning opportunity
   ✓ Progressive disclosure of complexity

7. "No Escape Hatch"
   ❌ Blocking legitimate deviations
   ✓ Clear process for exceptions

Best Practices

Golden Path Best Practices:

1. Start with Pain Points
   ├── Interview developers about friction
   ├── Measure current time-to-production
   ├── Identify most common tasks
   └── Focus on highest-impact paths first

2. Make Right Way Easy
   ├── Golden path should be faster than alternatives
   ├── Defaults should be secure and compliant
   ├── Documentation integrated into workflow
   └── Errors should guide to solutions

3. Iterate Based on Feedback
   ├── Regular user research
   ├── Fast iteration cycles
   ├── A/B test improvements
   └── Deprecate gracefully

4. Balance Opinionation and Flexibility
   ├── Strong defaults with clear rationale
   ├── Document why choices were made
   ├── Allow overrides with justification
   └── Learn from deviations

5. Invest in Documentation
   ├── Getting started guides
   ├── Decision explanations
   ├── Troubleshooting guides
   └── Migration guides

6. Build Community
   ├── Champions in each team
   ├── Regular office hours
   ├── Contribution guidelines
   └── Celebrate successes

Related Skills

• internal-developer-platform – Platform engineering overview
• self-service-infrastructure – Infrastructure provisioning patterns
• design-interview-methodology – Interview preparation
• quality-attributes-taxonomy – Understanding quality requirements