majiayu000 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 overviewself-service-infrastructure- Infrastructure provisioning patternsdesign-interview-methodology- Interview preparationquality-attributes-taxonomy- Understanding quality requirements