Core Principles of Platform Engineering

📖 Introduction

When I first started building internal tooling for developers, I made a classic mistake: I built what I thought was cool rather than what developers actually needed. The result was a sophisticated system that nobody used—developers found it easier to work around the platform than through it.

That experience taught me the most important lesson in platform engineering: platforms succeed or fail based on principles, not technology. The best platforms I've seen aren't necessarily the most technically advanced—they're the ones that truly understand their users and embody sound principles in every decision.

---

🎯 Core Principles Overview

---

🏪 Principle 1: Product Mindset

Platforms Are Products, Not Projects

The fundamental shift in platform engineering is treating your platform as a product with developers as your customers. This isn't just semantics—it fundamentally changes how you approach building and evolving the platform.

Project Mindset	Product Mindset
Build features, move on	Continuously evolve based on feedback
Success = delivery	Success = adoption and satisfaction
Requirements from stakeholders	Requirements from user research
Fixed scope and timeline	Iterative discovery and delivery
One-time handoff	Ongoing relationship with users

Building for Your Customers

from dataclasses import dataclass
from enum import Enum

class DeveloperPersona(Enum):
    """Different developer personas have different needs."""
    FRONTEND = "frontend"
    BACKEND = "backend"
    FULLSTACK = "fullstack"
    DATA = "data_engineer"
    ML = "ml_engineer"
    PLATFORM = "platform_engineer"


@dataclass
class DeveloperNeed:
    """Capture what developers actually need."""
    persona: DeveloperPersona
    pain_point: str
    frequency: str  # daily, weekly, monthly
    current_workaround: str
    impact_if_solved: str


# Example: Understanding your customers
developer_needs = [
    DeveloperNeed(
        persona=DeveloperPersona.BACKEND,
        pain_point="Creating new microservices takes days of boilerplate",
        frequency="weekly",
        current_workaround="Copy existing service, manually update configs",
        impact_if_solved="Save 2-3 days per new service"
    ),
    DeveloperNeed(
        persona=DeveloperPersona.FRONTEND,
        pain_point="Cannot preview changes in staging-like environment",
        frequency="daily",
        current_workaround="Test locally, hope it works in production",
        impact_if_solved="Catch environment issues before production"
    ),
]

The Feedback Loop

Successful platforms implement continuous feedback mechanisms:

Platform Product Practices

1. Regular user research: Interview developers monthly

2. Usage analytics: Track which features are actually used

3. NPS surveys: Measure developer satisfaction quarterly

4. Office hours: Regular sessions for feedback and support

5. Roadmap transparency: Share plans, gather input

---

💫 Principle 2: Developer Experience (DX)

What is Developer Experience?

Developer Experience encompasses everything a developer encounters when interacting with your platform—from documentation to error messages to the time it takes to complete common tasks.

Developer Experience = 
    Usability 
    + Documentation 
    + Reliability 
    + Speed 
    + Support

The DX Pyramid

                    ┌───────────┐
                    │ Delight   │ ← Exceptional experiences
                    ├───────────┤
                  │   Efficient  │ ← Tasks are quick and easy
                  ├─────────────┤
                │   Reliable      │ ← Platform works consistently
                ├─────────────────┤
              │   Usable           │ ← Developers can accomplish goals
              ├───────────────────┤
            │   Documented          │ ← Information is findable
            └───────────────────────┘

Measuring Developer Experience

Dimension	Metric	Target
Time to First Success	How long until new dev ships first change	< 1 day
Task Completion Time	Time to complete common tasks	Continuously decreasing
Error Rate	% of platform interactions that fail	< 1%
Support Volume	Tickets per developer per month	< 1
Satisfaction Score	Developer NPS	> 50

Practical DX Improvements

# Example: Good DX in a CLI tool

# BAD: Cryptic error message
# Error: ENOENT: no such file or directory

# GOOD: Helpful error with guidance
# Error: Configuration file not found
#
# We looked for the config file at:
#   - ./platform.yaml
#   - ~/.platform/config.yaml
#
# To create a new config file, run:
#   platform init
#
# For more information, see:
#   https://docs.platform.io/configuration

The 10-Second Rule

For common developer tasks, aim for the 10-second rule: developers should be able to start any common task within 10 seconds of deciding to do it.

---

🛤️ Principle 3: Golden Paths

What Are Golden Paths?

Golden paths (also called "paved roads") are opinionated, well-supported workflows that guide developers through common tasks. They make the right thing the easy thing.

Golden Path Characteristics

Characteristic	Description
Opinionated	Clear recommendations, not endless options
Supported	Platform team maintains and improves them
Documented	Step-by-step guidance available
Automated	As much automation as possible
Optional	Developers can deviate if they have good reasons

Designing Golden Paths

from dataclasses import dataclass
from typing import Optional


@dataclass
class GoldenPath:
    """Define a golden path for a common developer workflow."""
    
    name: str
    description: str
    target_persona: str
    steps: list[str]
    automation_level: str  # "fully", "partially", "guided"
    escape_hatches: list[str]  # Ways to deviate if needed
    
    def is_well_designed(self) -> bool:
        """Check if golden path follows best practices."""
        checks = [
            len(self.steps) <= 5,  # Not too complex
            self.automation_level in ["fully", "partially"],  # Some automation
            len(self.escape_hatches) > 0,  # Flexibility exists
        ]
        return all(checks)


# Example golden path
create_service_path = GoldenPath(
    name="Create New Microservice",
    description="Scaffold a production-ready microservice with all infrastructure",
    target_persona="Backend Developer",
    steps=[
        "1. Run 'platform create service --name my-service'",
        "2. Answer prompts for database, messaging, etc.",
        "3. Push generated code to trigger CI/CD",
        "4. Access running service in dev environment",
    ],
    automation_level="fully",
    escape_hatches=[
        "Use custom template: --template=custom-path",
        "Skip infrastructure: --no-infra",
        "Manual Kubernetes: export manifests with --export-k8s",
    ]
)

Golden Path vs. Guardrails

Golden Path: "Here's the recommended way to do X"
             ↓
             Easy, supported, best practices baked in
             
Guardrail:   "You cannot do Y regardless of which path you take"
             ↓
             Security requirements, compliance rules, cost controls

Both work together:

• Golden paths make the right thing easy

• Guardrails make the wrong thing impossible

---

👥 Principle 4: Team Topologies Integration

The Four Team Types

Team Topologies provides a framework for organizing teams for fast flow. Platform engineering fits naturally within this model.

Team Type	Purpose	Platform Engineering Role
Stream-aligned	Deliver business value	Primary customers of the platform
Platform	Provide self-service capabilities	Builds and maintains the IDP
Enabling	Help teams overcome obstacles	May help teams adopt platform
Complicated Subsystem	Handle complex domains	May provide specialized platform components

Interaction Modes

Platform teams use specific interaction modes with other teams:

Mode	When Used	Duration
X-as-a-Service	Platform capabilities consumed via API/self-service	Ongoing
Collaboration	Building new platform capability with a stream team	Temporary
Facilitating	Helping teams adopt platform features	Time-boxed

Reducing Cognitive Load

Team Topologies emphasizes reducing cognitive load. Platform engineering directly addresses this:

Before Platform Engineering:
┌─────────────────────────────────────────────────────────┐
│ Stream-Aligned Team Cognitive Load                      │
├─────────────────┬───────────────────────────────────────┤
│ Business Logic  │ ████████████████████████████████████ │ 30%
│ Infrastructure  │ ████████████████████████████████████ │ 35%
│ CI/CD           │ ██████████████████                   │ 15%
│ Security        │ ██████████████████                   │ 15%
│ Observability   │ ██████                               │ 5%
└─────────────────┴───────────────────────────────────────┘

After Platform Engineering:
┌─────────────────────────────────────────────────────────┐
│ Stream-Aligned Team Cognitive Load                      │
├─────────────────┬───────────────────────────────────────┤
│ Business Logic  │ ████████████████████████████████████ │ 80%
│ Platform Usage  │ ██████████                           │ 15%
│ Custom Needs    │ ███                                  │ 5%
└─────────────────┴───────────────────────────────────────┘

Infrastructure, CI/CD, Security, Observability → Platform Team

---

🔧 Principle 5: Don't Reinvent the Wheel

Build vs. Buy vs. Integrate

Platform teams should focus on what makes their organization unique, not rebuilding commodity solutions.

What to Build vs. Buy

Category	Recommendation	Examples
Always Buy/Use	Commodity infrastructure	CI runners, container registries, cloud services
Usually Open Source	Standard platform components	Kubernetes, Backstage, Argo CD
Consider Building	Glue and integrations	Custom plugins, workflow automation
Build Custom	Unique organizational needs	Domain-specific abstractions

The Platform Glue

The real value of platform engineering is often in the glue—the integrations that tie everything together:

# Example: Platform glue connecting systems

# New service creation workflow (the glue)
on_service_created:
  - scaffold_code_repository  # GitHub/GitLab API
  - create_kubernetes_namespace  # Kubernetes API
  - provision_database  # Crossplane/Terraform
  - setup_monitoring  # Prometheus/Grafana API
  - configure_cicd  # Argo CD/Flux
  - register_in_catalog  # Backstage API
  - notify_team  # Slack/Teams API
  - create_documentation  # Confluence/Notion API

---

✅ Principle 6: Focus on Common Problems

The 80/20 Rule

Focus on the 20% of use cases that cover 80% of developer needs. Don't try to solve every edge case immediately.

Identifying Common Problems

from collections import Counter
from dataclasses import dataclass


@dataclass
class DeveloperRequest:
    """Track requests to identify patterns."""
    request_type: str
    time_to_resolve: float  # hours
    could_be_self_service: bool


def analyze_platform_opportunities(requests: list[DeveloperRequest]) -> dict:
    """Identify highest-impact automation opportunities."""
    
    # Count request types
    type_counts = Counter(r.request_type for r in requests)
    
    # Calculate time spent per type
    time_by_type = {}
    for request_type in type_counts:
        matching = [r for r in requests if r.request_type == request_type]
        time_by_type[request_type] = sum(r.time_to_resolve for r in matching)
    
    # Find self-service candidates
    self_service_candidates = [
        r.request_type for r in requests 
        if r.could_be_self_service
    ]
    candidate_counts = Counter(self_service_candidates)
    
    # Prioritize by frequency × time × automation potential
    priorities = {}
    for req_type in type_counts:
        frequency = type_counts[req_type]
        total_time = time_by_type[req_type]
        automatable = candidate_counts.get(req_type, 0) / frequency
        priorities[req_type] = frequency * total_time * automatable
    
    return dict(sorted(priorities.items(), key=lambda x: -x[1]))

Start Small, Iterate

1. Identify top 3 pain points through developer surveys

2. Build minimal solution for #1 pain point

3. Measure adoption and feedback

4. Iterate and expand based on learnings

5. Move to next pain point

---

📏 Applying Principles in Practice

Decision Framework

When making platform decisions, ask:

┌─────────────────────────────────────────────────────────────┐
│                   PLATFORM DECISION CHECKLIST               │
├─────────────────────────────────────────────────────────────┤
│ □ Does this reduce cognitive load for developers?           │
│ □ Is this solving a common problem (not edge case)?         │
│ □ Are we treating developers as customers?                  │
│ □ Does this enable self-service?                            │
│ □ Can we measure the impact?                                │
│ □ Are we building on existing tools vs. reinventing?        │
│ □ Is there a clear golden path?                             │
│ □ Do escape hatches exist for advanced users?               │
└─────────────────────────────────────────────────────────────┘

Antipatterns to Avoid

Antipattern	Why It's Bad	Better Approach
The Perfect Platform	Never ships, scope creep	Thinnest viable platform first
Build Everything	Waste resources, maintenance burden	Leverage OSS and commercial tools
Force Everyone	Breeds resentment, workarounds	Make platform attractive, not mandatory
Ignore Feedback	Platform diverges from needs	Regular user research and iteration
No Escape Hatches	Blocks advanced use cases	Allow deviation with guardrails

---

📝 Summary

Platform engineering success depends on adhering to core principles that put developers first and focus on sustainable, iterative improvement.

Key Principles Recap

Principle	Key Takeaway
Product Mindset	Treat platform as product, developers as customers
Developer Experience	Every interaction should be smooth and helpful
Golden Paths	Make the right thing easy, not just possible
Team Topologies	Reduce cognitive load through clear boundaries
Don't Reinvent	Build glue, not commodity tools
Focus on Common	Solve the 80% before the edge cases

---

🔗 References

• Team Topologies - Matthew Skelton & Manuel Pais

• The DevOps Handbook - Kim, Humble, Debois, Willis

• Evan Bottcher on Platforms - Martin Fowler's Blog

• Platform Engineering Principles - Microsoft

• Developer Experience at Stripe

---

➡️ Next Steps

Continue to Article 3: Platform Engineering vs DevOps vs SRE to understand how platform engineering relates to and differs from DevOps and Site Reliability Engineering.