Platform Engineering’s patterns and anti-patterns

Source: Dev.to

Platform Engineering Overview

Platform Engineering has been around for a while. Interest recently accelerated, however, thanks to its relevance to DevOps.

For some, Platform Engineering solves a common DevOps Topologies problem: embedding IT operations into DevOps teams that lack the time and experience to do it well. This is an anti‑pattern, also known as Anti‑Type F.

Platform Engineering can help you scale the organization and reduce developer overload.

Use our Platform Engineering decision flow to find out if it’s the right solution to your problems. It also guides you to put key measurements in place early so you can track the value of your internal developer platform (IDP).

Anti‑Patterns & Positive Patterns

We describe the anti‑patterns and positive patterns of Platform Engineering below. Let us know if you have a suggestion.

If you’re familiar with Team Topologies, you’re less likely to use one of the common Platform Engineering anti‑patterns. The library can still be a helpful way to describe problems to your colleagues when you encounter trouble.

Reducing Cognitive Overload

An IDP should reduce complexity and remove cognitive overload for developers. If the platform is too difficult to use, it has failed at a crucial goal. There are several ways a platform can add to a developer’s burden:

• It uses a configuration file format that isn’t familiar to the developer.
• APIs don’t have a consistent convention for methods and parameters.
• There’s no documentation.
• The platform doesn’t reduce developer pain.

Configuration Files

If you have configuration files as part of your platform, be flexible with the format. It should be trivial to parse the same data from:

• a JSON file (web developers)
• a YAML or XML file (back‑end teams)

This lets developers use a format familiar to them rather than one convenient to you.

APIs & CLIs

When creating an API or command‑line interface (CLI), be meticulous and consistent with:

• method names
• parameter names
• order of parameters

This makes the interface easier to use.

Documentation

Your IDP documentation should be concise and clear, focusing on:

• what’s available
• how to use it

Governance, Risk, & Compliance (GRC)

If developers don’t meet GRC objectives, adding a platform that handles these needs can add more load to development teams. Solve existing developer problems first; then you can address external requirements without burdening developers.

Overall Success Criteria

• The IDP must significantly reduce developer cognitive overload, complexity, and burnout.
• It must not transfer all the pain to the platform team.

Building the Right Platform

“If you build it, they will come.” – Field of Dreams (1989)

If you take the same approach when building your internal developer platform, you’ll struggle to gain internal market share. Involve developers from the start and build a platform that solves their specific problems.

Common Symptoms of a Mis‑aligned Platform

• Poor technology fit – e.g., making it easier to manage Kubernetes only to find developers have moved to serverless functions.
• Skill assumptions – e.g., creating a simplified template for microservices only to discover developers are already microservice experts and don’t value your solution.
• Forcing choices – e.g., designing a platform with the latest technology while the business prefers stable, proven solutions.

You can’t design your IDP on faith alone. Talk to developers across many teams to uncover common pain points your platform could remove. Creating a platform in isolation guarantees low adoption rates.

Team Dynamics & Knowledge Transfer

When you create a Platform Engineering team, you’ll likely add people with the most experience in the areas the platform will cover. This can cause problems when:

• The platform team thinks they know better than the development teams.
• Development teams lose the knowledge they need to run their software.
• Development teams lose the people who could migrate them onto a platform.

Best practices:

1. Succession Planning – If you move people from development to a platform team, ensure a strong succession plan and focus on collaboration to upskill the remaining developers for self‑service.
2. Avoid Cognitive Overload – Don’t remove skilled team members without a plan; this can cause burnout.
3. Start Small – Begin with a lean platform team, solving problems that make it easier for other teams to release more frequently.
4. Hire for Collaboration – Choose platform team members based on communication and collaboration skills, not just technical knowledge.

The “Magpie” Platform Anti‑Pattern

People attracted to shiny objects are often called magpies (members of the crow family that collect shiny items). A magpie platform focuses on the latest technologies rather than solving the real problems developers face with existing systems.

• Building a platform for a greenfield project is attractive, but you’ll have a greater impact by helping teams with their existing production software.
• Identify where developers struggle, then build a better platform for the new software.

When a development team adopts new technology, they may appear to need help with everything. Let them establish knowledge first; the actual pain points will emerge, and many early pains will disappear as they get used to the new tech.

Proving Impact

You need to prove the platform’s impact, so a stable starting point is necessary for others to take your measurements seriously. Stakeholders may dismiss your improvements if they think they’re simply due to teams getting familiar with the technology and business domain.

Platforms must prove their i (text truncated in source)

Feel free to suggest edits or additions to this guide.

Impact on Existing Teams and Tech Stacks

There will be many opportunities to merge technologies where teams solved a problem differently.
Sometimes introducing a new tool for deployment or monitoring can remove pain from many teams at once. It’s crucial you can show the platform’s benefits.

Long‑Term Investment

Once you’ve introduced a platform into your organization, it needs long‑term investment to stay usable.

• If a platform team disbands after delivering a product, the platform can become an anchor that adds drag to all who depend on it.
• The context that led to the decisions baked into the IDP can change, leaving teams stuck with old choices that no longer work.
• The platform may become so difficult to use that teams must migrate away to get their work done.

Key takeaway: Platforms need continual improvement—add new golden pathways and phase out outdated ones to keep delivering business value.

Matching Ambition to Investment

You should limit the platform’s ambition to match the long‑term investment levels.

If your organization has a fragmented technology landscape, it can be tempting to solve too many problems with the IDP. Supporting all existing tools and technologies will:

• Stretch the platform too thin to be useful.
• Overload the platform team even more than the developers were.

Avoiding “Stretched” Platforms

A common cause of stretched platforms is measuring the platform team on internal market share.

• Adding more golden pathways can increase market share, but it defeats the goal of encouraging consolidation around good technology choices.
• MONK metrics can help balance market share with developer satisfaction and outcomes, preventing the platform from becoming over‑extended.

Cost‑Control & Self‑Service

When you provide self‑service options, you must have a strong story around cost tracking and control.

• If every developer spins up production‑like environments, costs can spiral out of control.
• Any button that makes spending easy should include an automatic limit (e.g., short‑lived test environments, caps on concurrent environments).
• This is an opportunity for the platform team to bridge with finance on cost‑governance.

The All‑In‑One DevOps Tool Trap

When platform decisions happen away from technical knowledge, there’s a temptation to adopt an all‑in‑one DevOps platform.

• This does not align with Platform Engineering or DevOps.
• A single general‑purpose tool limits the platform’s capability and continuous‑improvement ability; the tool’s features constrain the solution for all problems.

Better approach:

• Design the platform as an internal product that solves specific pain points.
• Select best‑in‑class tools where needed and create reusable libraries (e.g., for unified logging and telemetry).
• Remember: a golden pathway is not a tool; it’s a curated, repeatable way of doing something, often built on specialist tools for builds, deployments, and monitoring.

Handling Edge Cases

• While platform teams aim to standardize the landscape, edge cases will always exist.
• A rigid platform forces teams to exit and find alternatives.
• Engaging with teams and listening for edge cases lets the platform team counter them and retain internal market share.

Balance:

• Accommodating every scenario without consolidation overwhelms the platform team with complexity and cognitive load.
• The best software products have a clear focus and don’t try to do everything.

Design tip: Allow teams to add edge cases without necessarily bringing them into support. Edge cases should not force people off the platform or increase its surface area.

Market‑Share Reporting

When you report on platform market share, highlight three numbers:

1. Total market size – all developers.
2. Supported market size – developers using a tech stack supported by a golden path.
3. Market share – developers actually using the platform.

Market‑Share Chart

• Shows the total internal developer market.
• Indicates how much of that market could use the IDP.
• Shows how many actually chose to do so.

Use the chart to guide decisions for new golden pathways and to track the platform’s appeal to its intended audience.

Team Design & Interaction Modes

It’s easy to create a team; building the interactions that make them successful is far more work.

• Team Topologies describe this using a combination of team and interaction modes.
• If you create a platform team without paying attention to interaction design, it will fail.

Culture

Software delivery requires a high‑trust, low‑blame culture to succeed. Platform Engineering is no different—culture is one of the biggest predictors of performance. (See more on DevOps culture.)

Platform as a Long‑Term Product

• Building a platform isn’t a project; it must be a long‑term strategy.
• When a platform is on‑hold, it limits performance for all its users—worse than not creating a platform at all.

You need:

• Solid team design.
• Clear interaction modes.
• A product‑mindset for the platform.

Signs of Success

Now that you’ve seen many ways Platform Engineering can fail, let’s look at what success looks like.

• In the Puppet State of Platform Engineering Report, 94 % of respondents found the concept helped the organization realize the benefits of DevOps.
• Strong performance against the DORA Metrics is a good predictor of Platform Engineering success.

The most critical sign of good Platform Engineering is that… (continue with your success criteria here).

Platform Engineering as a Product

Developers are the customers, and the internal platform must solve their problems to win market share.

1. Product‑Mindset for Platform Teams

• Regular developer contact – Keep a feedback loop with the teams that use the platform.
• Measurable success criteria – Define and track platform KPIs (e.g., adoption, time‑to‑value).
• Product‑manager responsibilities
  • Don’t just maintain a backlog.
  • Raise awareness of the platform across the organization.
  • Network with other departments to incorporate their needs.
  • Help developers satisfy security, governance, risk, and compliance (SGRC) requirements.

2. Vision, Decision‑Making, and Documentation

Vision

A strong, inspiring vision guides good decisions and prevents the platform from supporting bad choices just to gain internal market share.

Decision Register

• Capture every major architectural or product decision.
• Store the rationale so decisions aren’t forgotten or later reversed.

Documentation

High‑quality documentation is critical for product adoption.

• Keep it up‑to‑date.
• Make it easy to find and consume (e.g., searchable docs, quick‑start guides).

3. DevOps Capabilities that Boost Platform Value

“DevOps combines the following to increase software delivery performance.”

These capabilities also raise the likelihood of building a valuable platform.

4. Start Small, Iterate Fast

• Don’t aim for a “golden pathway” immediately.
• Solve one wide‑reaching problem, then iterate toward success.

Typical “easy‑win” patterns:

1. Deploy common, approved tech stacks.
2. Provision infrastructure and create environments on demand.
3. Collect telemetry, error logs, and track production systems.

The underlying principle: abstract a complex area so developers don’t get lost in the weeds.

• Use an off‑the‑shelf tool when it fits.
• Otherwise, build a façade that simplifies the tricky area.

5. The Thinnest Viable Platform

• Begin with the minimum set of features that delivers the biggest impact.
• Expand slowly, prioritising high‑impact areas over trying to solve everything at once.

Example: Unified

(Content truncated in the original source; continue as needed.)