Last quarter, your company launched an internal platform with a portal, pipeline builder, and kickoff deck featuring “revolutionize all the things”. Six months later, developers still ask colleagues for databases, share Terraform scripts, and manually paste secrets. Everyone’s busy, but progress is slower than expected.

This guide covers the 20% of platform engineering that drives 80% of the work: build around engineers’ actual needs, keep the platform thin, and let teams choose it. You’ll create a ranked backlog from five interviews and a shadowed deploy, a one-page team charter, a documented golden path, a three-bin governance sort, and a request-to-fulfillment metric. You’ll also assess what AI coding assistants build without guidance.

What You’ll Learn

  • What platform engineering is and how it differs from DevOps and business strategy’s use of “platform.”
  • When to fund a platform team, and when a wiki page is enough.
  • Why the work people do differs from what your process documents describe, and why the platform must serve the work people actually do.
  • How Team Topologies defines platform teams and their role in reducing cognitive load.
  • How to define a minimal viable platform and create a golden path developers choose.
  • How to grow the platform from what product teams already built, and keep adoption voluntary.
  • Where to draw the line between governance and freedom.
  • How to measure a platform and spot a team slipping into the Capability Immaturity Model.
  • InfraCloud’s six reasons developer platforms fail, and a fix for each.
  • What AI coding agents and AI workloads change about the platform’s job.

Before You Start

Required. Authority (or an authorized sponsor) to interview engineers, publish a team charter, and present one metric to leadership. At least three product teams share an infrastructure backlog.

Not required. Kubernetes, Backstage, or any specific tool. Every move in this guide works with a wiki page and a spreadsheet.

The Basics

Platform engineering builds and runs an internal developer platform: curated self-service capabilities that help product teams ship software. It provides shared plumbing (pipelines, environments, databases, observability, and identity) that teams would otherwise rebuild. Microsoft’s guide describes it as a practice “built up from DevOps principles,” aiming to improve “security, compliance, costs, and time-to-business value through improved developer experiences and self-service within a secure, governed framework” (What is platform engineering?).

The difference from DevOps is who does the work. DevOps asks every team to build and run its own software. Platform engineering preserves that ownership while adding a dedicated team to package shared components as a product. The Cloud Native Computing Foundation (CNCF) describes this as “an explicit form” of the cooperation DevOps promised (CNCF Platforms White Paper). The white paper states the motivation plainly: process improvements over the past two decades have shifted increasing infrastructure responsibility to product teams, and platforms aim to give them that time back.

In business strategy, a “platform” can mean a two-sided market that grows through network effects (Strategies for Two-Sided Markets). Internal and business platforms both depend on others choosing to build on them. Steve Yegge’s 2011 Google and Amazon rant offers the same golden rule for both: “eat your own dogfood” (Stevey’s Google Platforms Rant).

Primary Use Cases

  • An organization where each product team manages its own deployment scripts, cloud accounts, and monitoring.
  • A compliance-heavy environment where security, data handling, and cost controls are built in from the outset rather than audited after the fact.
  • A company whose engineers focus more on infrastructure than the product they were hired to build.

Less Suitable Use Cases

  • With twelve people, a shared README on “how we provision things” is the platform; a dedicated team would cost more than it saves.
  • An organization unable to fund a permanent team keeps its platform at the lowest maturity level; volunteer hack-week staffing leaves it to decay between bursts of attention (Platform Engineering Maturity Model).
  • A one-product company with a working deployment path should solve its next bottleneck instead.

When to Use Platform Engineering

Start a platform team when three or more product teams repeatedly face the same undifferentiated work and leadership will fund it as a product, not a cost center. Microsoft cites an undated Gartner forecast, made before 2026, that around 80 percent of engineering organizations would have a dedicated platform team by 2026. It also notes that teams under 20 people can support thousands of developers (What is platform engineering?).

A platform team is worthwhile only if it reduces users’ work; a layer they must learn and work around adds to it.

The 20% That Does 80%

Study Work as Done, Not Work as Imagined

Every organization runs two systems. One exists in process documents and architecture diagrams: linear, compliant, and tidy. The other is what engineers actually do at 4:37 p.m. on a Tuesday, as the deploy window closes: a curl command saved in a Notion page, a Bash script older than anyone can remember, or a retry loop until the test goes green. Russ Miles calls these “work as imagined” and “work as done,” and applies the distinction to platforms in A Golden Path No One Walks Is a Golden Myth. His short story The Map That Refused to Stay Still brings it to life: a framed, official workflow map and a stained one found in a drawer, annotated “Ask Sarah. If Sarah is on holiday, abandon hope.”

Miles calls the gap “the default mode of human work.” The imagined workflow assumes rational behavior; the real one assumes a deadline. His rule for reading it: “deviation is information, not defiance.” Each workaround marks a spot where going around the platform costs less than using it. Documentation describes imagined work, and only observation shows real work. Miles warns that a platform serving imagined work becomes shelfware.

The move. Shadow one real deploy from commit to production, start to finish, without helping. Then read the last month of the team’s help channel. List every workaround you see: copied scripts, manual steps, “ask this person” handoffs, and retries.

What you get. A list of workarounds with the person or script each one depends on. Each entry is a candidate capability, and the people named are your single points of failure.

Treat the Platform as a Product

Manuel Pais, co-author of Team Topologies, says a platform’s first goal “should be to reduce cognitive load on the stream-aligned teams.” The platform team is also stream-aligned, with internal customers (How Team Topologies Supports Platform Engineering). So, interview users, publish a roadmap, prioritize capabilities most teams need over those demanded by the loudest team, and remove unused features.

Matthew Skelton, Pais’s co-author, makes the same point in his ProductTank Auckland talk: most organizations treat platforms as “blobs of technology” justified by cost cutting, when they could be “curated experiences for engineers who are customers of the platform” (What If Your Internal Platforms Could Drive Business Innovation?).

The CNCF white paper lists attributes of product thinking (CNCF Platforms White Paper):

  • Consistent experience across CLI, API, and portal.
  • Documentation and onboarding.
  • Self-service with no ticket in the loop.
  • Reduced cognitive load.
  • Optional and composable.
  • Secure by default.

Microsoft’s four principles overlap with CNCF’s list and add asset inventories: prioritize each customer, adopt a product mindset, enable self-service, and manage assets through inventories (Platform engineering guide).

The move. Before building, interview five developers from different teams for 30 minutes each. Ask how they last obtained a database, test environment, or production service, and how long each step took. Record the steps and delays, and add the workarounds from your shadowed deploy. Rank your backlog by how many teams faced each obstacle.

What you get. Recurring waits and workarounds, ranked by how many teams reported them. The top one is your first capability.

Lower Cognitive Load With the Right Team Shape

Team Topologies names four team types and three interaction modes (Team Topologies):

  • Stream-aligned teams own a slice of the product end to end.
  • Enabling teams teach a skill and step back.
  • Complicated-subsystem teams own something that needs deep specialists.
  • Platform teams provide internal services others consume with minimal coordination.
graph TB S1[Stream-aligned team: checkout] -->|self-service, X-as-a-Service| P[Platform team: internal developer platform] S2[Stream-aligned team: search] -->|self-service, X-as-a-Service| P E[Enabling team: security] -.->|teaches, then steps back| S1 E -.->|teaches, then steps back| S2 P -->|thin layer over| C[Cloud providers and managed services]

The three interaction modes set how those teams work together:

  • Collaboration. Two teams work closely for a fixed period on a shared problem, such as a new capability neither could build alone.
  • X-as-a-Service. One team consumes another’s service with minimal coordination, treating it as a black box.
  • Facilitating. One team helps another build a skill, aiming to make itself unnecessary.

Skelton sharpens X-as-a-Service with a contrast between a vending machine and a butler. Vending-machine self-service lets teams move at their own speed; butler-style bespoke service creates dependencies and queues at the platform team (What If Your Internal Platforms Could Drive Business Innovation?). A ticket that a platform engineer fulfills by hand is a butler, however good the portal looks.

Pais warns that a platform can become “a bucket for everything, and just becomes a huge mess with lack of ownership, lack of focus and a lot of waste” (How Team Topologies Supports Platform Engineering). In medium or large organizations, platforms comprise teams that each own a cohesive service, such as infrastructure or data services, through consistent interfaces, allowing them to evolve independently.

The move. Write a one-page platform team charter naming its customers, three owned capabilities, and what it refuses to own. Review quarterly. An empty “refuses” list signals the bucket problem has begun.

What you get. A charter short enough to read in two minutes, with a “refuses to own” list that has at least one entry.

Start With the Thinnest Viable Platform

Microsoft’s guide promotes the thinnest viable platform as the starting point: a minimum viable product for your platform that you build on feedback (What is platform engineering?). Pais is blunter: at a startup, “the platform might just be some sort of Wiki page” that explains how to create a database the recommended way (How Team Topologies Supports Platform Engineering). The CNCF adds that platform teams should rely on managed providers and internal infrastructure teams for implementation and own the interfaces: the portal, the API, the template, and the docs (CNCF Platforms White Paper).

The move. Pick the top-ranked obstacle from your interviews, usually getting a new service into production. Document the recommended path from start to finish, including every click and command. Automate only the slowest step. Ship it, then time an engineer from another team who has never used the path. A new hire is ideal, but a volunteer from the interviews works too.

What you get. One new engineer’s time to production, from the timestamp of their request to the moment the service goes live. These timestamps provide the first data point for the Measure section’s metric.

Pave Golden Paths, and Keep Them Optional

Spotify coined “Golden Path” for the “opinionated and supported” path to “build something,” with tutorials for each engineering discipline that new hires are encouraged to complete within two weeks (How We Use Golden Paths). Microsoft’s “paved path” metaphor describes trails paved as more people use them, maintaining velocity while guiding developers through security and compliance (What is platform engineering?).

Three lessons from Spotify matter more than the metaphor. Tutorials should mirror the actual path, and if it’s too long, shorten the path rather than the tutorial. Engineers can leave the path, “but then you will not have the same support.” Every new hire tests the tutorials, driving ongoing platform fixes (How We Use Golden Paths).

Yegge’s rule applies: if the platform team bypasses its own golden path, others will too (Stevey’s Google Platforms Rant).

Miles treats golden paths as living contracts that you revise and validate continuously. In his words, “a golden path no one walks is a golden myth.” His test for when a workaround deserves a place on the path: “A workaround used by three people is a smell. Used by thirty, it’s a requirement” (A Golden Path No One Walks Is a Golden Myth).

Skelton describes the same growth as gardening (What If Your Internal Platforms Could Drive Business Innovation?):

graph TB F[Forage: find what product teams built for themselves] --> H[Harvest: pick the ones that fit the platform strategy] H --> R[Re-common: offer them to every team as a service] R -->|more capabilities let teams build more| F

The cycle accepts that large organizations duplicate work and turns the duplicates into a supply of tested ideas. Harvesting is selective: the platform declines contributions that don’t fit its strategy, even good ones. The CONTRIBUTING.md in the next move is the harvest step: it says how a product team proposes a tool for the path, and what the platform declines.

The move. Create a golden path repository and fill in one path first:

golden-paths/
  backend-service/
    README.md          # the opinionated path, every step, in order
    template/          # scaffold a new service from here
    checks.yml         # what "on the path" means, machine-checkable
  CONTRIBUTING.md      # how a product team proposes a change to the path

Keep checks.yml small and literal. Each entry names one testable requirement for a service on the path:

# checks.yml: one entry per thing a service on the path must have
template-version-file: .golden-path-version
deploy-pipeline: shared/deploy.yml
health-endpoint: /healthz

Choose any script-readable format. Make “on the path” objective. Run the checks against the platform team’s own services first, and fix every failure before you ask a product team to adopt the path.

What you get. A written path a new engineer can follow alone, with a scaffold for a deployable service. Checks evolve into Spotify’s “Golden State” idea, showing which systems follow the path and which have drifted (How We Use Golden Paths).

Draw the Line Between Governance and Freedom

Matt Cobby’s “gravity well” model guides what a platform standardizes: capabilities an organization depends on more are standardized and slower to change.

Cobby divides capabilities at a “value line.” Capabilities above it drive revenue and need room to move quickly. Those below it, such as Kubernetes, pipelines, and cloud accounts, must be delivered well at the lowest unit cost; no one benefits from every team implementing them differently. Exceptions include high-risk areas like data and security, where “solid, tested and certified” components should be available on demand (Can You Have Both Governance and Freedom in Developer Experience?).

Cobby’s tool for distributed decisions is a brief set of engineering principles, not a standards document. A good principle’s opposite must be nonsense. Examples include “build differentiators, buy commodity” and “end-to-end ownership,” each paired with an intent statement to help engineers make trade-offs without consulting an architect (Can You Have Both Governance and Freedom in Developer Experience?).

The move. Sort platform capabilities into three bins: deep in the well (standardize, one way), above the value line (recommend, allow alternatives), and high-risk (certified components required). Publish the classifications and debate them openly before a release gate does it for you. Keep the high-risk bin small: Miles warns that “a compliant workflow that destroys flow is still failure” (A Golden Path No One Walks Is a Golden Myth).

What you get. A published list showing which capabilities have a defined or recommended approach, and which require certified components.

Measure the Platform, and Watch for Immaturity

The CNCF white paper groups platform metrics into three buckets (CNCF Platforms White Paper):

  • User satisfaction and productivity: active users, retention, and survey scores.
  • Organizational efficiency: request-to-fulfillment latency, time to deploy a service, and time for new users to ship their first change.
  • Product delivery: the four DORA metrics from Google’s DevOps Research and Assessment program.

Start with request-to-fulfillment latency: it’s cheap to measure, and developers feel it. Miles adds two cautions (A Golden Path No One Walks Is a Golden Myth). Measure cognitive load alongside lead time. In Miles’s words, “if your platform makes people feel stupid, they will route around it.” And publish observability for the platform itself: when teams can’t see what the platform is doing, they assume it’s untrustworthy.

The CNCF’s maturity model then describes five aspects (investment, adoption, interfaces, operations, measurement) across four levels. Adoption is the aspect to watch:

Provisional: erratic Teams find tools through rumors and chance conversations; each team maintains its own deployment scripts.
Operational: extrinsic push Mandates and incentives drive use. Teams with unmet needs can’t extend the platform, so they work around it.
Scalable: intrinsic pull Teams choose the easiest platform, then check it first after a good experience.
Optimizing: participatory Product teams contribute fixes and capabilities; platform engineers join product planning.

The authors caution that higher maturity levels require more funding and staff time, so reaching the top “should not be a goal in itself” (Platform Engineering Maturity Model).

Maturity models have a built-in trap. Capability Maturity Model Integration (CMMI), which originated at Carnegie Mellon’s Software Engineering Institute, rates organizations from level 1 to 5 (Capability Maturity Model Integration). The parody beside it, the Capability Immaturity Model, is more useful for platform teams. It ranges from level zero to minus three (Capability Immaturity Model):

  • Negligent (level 0): lip service and fanfare with no follow-through.
  • Obstructive (minus one): process followed with rigor while the product is incidental.
  • Contemptuous (minus two): fudged metrics and activity counted instead of outcomes.
  • Undermining (minus three): sabotaging the teams that are improving.

A platform team that counts “pipelines created” while developers copy YAML around it is at level minus two. A platform team that mandates adoption and blocks releases to meet a usage target is at level minus one. The CNCF model treats “extrinsic push” as a stage to pass through; a team that stays there by blocking releases has stopped earning its users.

Skelton’s answer is voluntary adoption: teams choose whether to use the platform, so the platform has to earn its users. Low adoption is a signal to improve the platform (What If Your Internal Platforms Could Drive Business Innovation?). Miles gives the reason: “Behaviour follows friction, not policy” (A Golden Path No One Walks Is a Golden Myth).

The move. Track one metric: median time from “I need X” to “I have X” for your top capability. Take the first from the original ticket, chat, or form; take the second from the engineer’s confirmation that it works. Publish monthly. If the time rises, the platform is adding load, not removing it.

What you get. One published number, tracked monthly. Your first data point is the new engineer’s time from the thinnest viable platform move; switch to the median as more teams use the path. Any later rise signals a need to interview again.

Plan for AI Coding Agents and AI Workloads

AI changes the platform’s job in two directions.

The first is who writes the code. Will Strye asks what a foundational platform is for once coding agents can deliver security, resilience, and the other nonfunctional requirements themselves (It’s Time to Rethink Your Platform Strategy). Many agents reach tools through the Model Context Protocol (MCP), “an open-source standard for connecting AI applications to external systems” (What is the Model Context Protocol?). An engineer can prompt their way to a deployable service that never touched your golden path. Strye’s questions for platform teams: does your development model still enforce your standards when an agent writes the code, and should you run internal MCP servers that teach agents your paths?

The second is what teams build. Divya Arunachalam argues that AI development breaks platforms designed for deterministic microservices (Rethinking Platform Engineering). Teams need graphics processing unit (GPU) environments within hours and versioned datasets, model weights, and prompt templates alongside code. They also live with frameworks whose APIs shift every few months. Her four pillars for an AI-ready platform are composable infrastructure, machine learning developer experience, versioned assets with lineage, and governance with full-stack observability.

Her org-design advice matches the rest of this guide: guardrails instead of gates, platform engineers paired with machine learning practitioners, and a stack you assume needs a refresh every 6 to 12 months.

The move. Ask three teams which AI coding assistants they use, and pick the most common one. Have it generate a new service from a plain prompt, with no mention of your golden path, then check the result against each entry in checks.yml: does .golden-path-version exist, does the pipeline call shared/deploy.yml, and does /healthz respond?

What you get. A list of the checks that agent-generated code fails. Each failure is a standard that lives in your docs but not in anything an agent reads; those are the first candidates for an internal MCP server or a template the agent can call.

If a Move Stalls

  • No obstacle shared across the interviews. Stop. The platform team’s leverage isn’t there yet; a wiki page is the right platform for now.
  • No funding for a durable team. Ship the wiki-page platform from the thinnest viable platform section, and bring the request-to-fulfillment number to the next budget review.
  • A team wants a refused capability. Refer to the charter’s “refuses to own” list and next quarterly review. Add the capability only if at least three teams report the same wait.
  • The governance sort deadlocks. Put the disputed capability in the “recommend, allow alternatives” bin; revisit after one month of metrics.
  • Nobody walks the golden path. Check whether the platform team uses it for its services, then retest with a new engineer.
  • No timestamps for requests. Start logging the request time in the ticket, chat thread, or form today; report the metric after the first full month.
  • The AI assistant passes every check. Repeat the move with the second most common assistant, then with a prompt that names a language or framework your path omits.
  • Teams keep routing around the platform. Shadow another deploy instead of writing a policy. The workaround they chose shows what the platform is missing.

Beware of These Potential Failures

InfraCloud’s six platform engineering failure causes each map to a fix above (How to Fail at Platform Engineering):

  • Product misfit. Developers weren’t involved, so the platform solves problems they don’t have. Fix: interview them.
  • Overly complex design. Too many options, nonstandard configuration languages, and a steep learning curve. Fix: the thinnest viable platform.
  • Swiss knife syndrome. A platform that integrates with everything but does none well. Fix: the charter’s “refuses to own” list.
  • Insufficient documentation. Developers ask colleagues instead of reading docs, piling up support tickets. Fix: a golden-path tutorial that stays on track.
  • Siloed development. Platform and product teams rarely share work. Fix: shared channels, a published roadmap, and product team contributions.
  • Stagnant platform. Teams drift away when tool versions lag and features stall. Fix: set a roadmap and track a monthly metric.

InfraCloud cites the 2023 State of Platform Engineering report, where 32 percent said poor team communication causes platform failure (How to Fail at Platform Engineering). Four of the six are communication problems: misfit, missing docs, silos, and an unshared roadmap. The 32 percent figure is from 2023 and may have shifted.

Learn Platform Engineering - Beyond the Basics

You have the essentials: work as done, product mindset, team structure, a minimal viable platform, golden paths, governance, one honest metric, a plan for AI, and the failures to watch for. Read Russ Miles’s short story and essay, watch the Team Topologies video, read the CNCF white paper, then choose one book on leadership and one on strategy.

Video

Audio and Podcasts

  • Platform Engineering Podcast, interviews with the people running internal platforms at large companies.
  • Ship It! on Changelog, a podcast about shipping software and the platforms that make it possible. The show ended in December 2024 after 135 episodes; the archive is still online.
  • Team topologies: Organizing teams for fast flow on the Scandinavian Product Podcast, an interview with Manuel Pais on team shapes, cognitive load, and platform teams.

Books

Online

References

Related Content