Stats
Actions
Tags
Help us improve
Share bugs, ideas, or general feedback.
From systems-design
Designs standardized development workflows using golden path patterns, paved roads, opinionated defaults, templates, and guardrails to optimize onboarding and productivity.
npx claudepluginhub melodic-software/claude-code-plugins --plugin systems-designHow this skill is triggered — by the user, by Claude, or both
Slash command
/systems-design:golden-pathsThis skill is limited to the following tools:
The summary Claude sees in its skill listing — used to decide when to auto-load this skill
Patterns for designing standardized, opinionated development workflows that make the right way the easy way.
Defines opinionated golden paths for common dev tasks like service creation, environment setup, or feature deployment. Produces concrete steps, templates, Makefiles, and commands.
Define a golden path — the opinionated, supported way to do a common developer task (create a new service, set up an environment, deploy a feature). Produces concrete steps, templates, and tooling. Use when asked to "golden path", "create project template", "scaffold a new service", "how should we create services", or "standardize our setup".
Designs Internal Developer Platforms with self-service portals, templates, provisioning, and golden paths. Useful for platform teams assessing maturity and creating roadmaps.
Share bugs, ideas, or general feedback.
Patterns for designing standardized, opinionated development workflows that make the right way the easy way.
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 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 │
└─────────────────────────────────────────────────────────────┘
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:
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 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: 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: 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"
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 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 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)
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
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
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
internal-developer-platform - Platform engineering overviewself-service-infrastructure - Infrastructure provisioning patternsdesign-interview-methodology - Interview preparationquality-attributes-taxonomy - Understanding quality requirements