PlatformEngr® Platform fundamentals course

Cheat notes · Platform fundamentals

Platform fundamentals: cheat notes

Every module on one page, cut to what you need to remember: the idea, the commands, the pitfalls and a few questions to test yourself. Made for review after you have done the course, not instead of it. Back to the course.

00 Orientation: a platform design you can check

The idea

A platform design written as structured files in Git can be reviewed, versioned and checked like code, so every decision has a place and a reason.

Remember

  • Platform: "an integrated collection of capabilities defined and presented according to the needs of the platform's users" (CNCF Platforms White Paper).
  • The design check (scripts/check.mjs) parses YAML and Markdown and prints [ID] message per broken rule. It runs nothing from the repo.
  • Two kinds of user: people and the coding agents that work for them.
  • npm ci --ignore-scripts installs exactly the lock file, with no install scripts.
  • The workflow design-check runs the same check on every push to main and every pull request.

Pitfalls

  • Pushing without running the check: main turns red with [Y1] for invalid YAML.
  • A line indented by accident becomes part of the line above it in YAML.

Commands

npm run checkCheck every design file
gh run list --workflow design-check --limit 1The latest run on GitHub
gh run view --log-failedWhy it failed

Test yourself

Answer in your head first, then open the answer.

What does the design check never do?

Run anything from the repo. It only parses the files.

Where does the check run besides your laptop?

In the design-check workflow, on every pull request and push to main.

Why write the design in files rather than slides?

Changes become reviewable diffs with history, and a check can test them.

Where module 00 leaves you: Your repo on GitHub holds package.json, package-lock.json, .gitignore, scripts/check.mjs and .github/workflows/check.yaml. npm run check prints eight lines marked not written yet and Nothing written yet. The check is ready. The workflow run on main is green.

01 What a platform is, and platform as a product

The idea

A platform is defined by its users and their problems, not by its tools, and it is run as a product: an owner, evidence, a roadmap and the courage to say no.

Remember

  • Platform as a product is the first of seven attributes in the CNCF Platforms White Paper.
  • Bottcher (2018): "a foundation of self-service APIs, tools, services, knowledge and support which are arranged as a compelling internal product".
  • Thinnest viable platform: just enough capability without unnecessary complexity (Team Topologies).
  • A mission is an outcome for users; a roll-out of tools is a project (rule P2).
  • Every problem needs evidence: where you heard or measured it (P5).
  • Non-goals let a small team say no without arguing again (P6).

Pitfalls

  • A mission that names a tool ("roll out Backstage") fails P2 and tells users nothing.
  • Problems without evidence build a platform nobody asked for.
  • Confusing the portal with the platform: a portal is one interface among thirteen capability areas.

platform.yaml (part)

mission: >-
  A product team goes from an idea to a safe change in production in one day,
  without waiting for another team, and an agent can do the routine part of that work inside the same limits.
owner: platform
productOwner: Platform product manager (platform team)

Test yourself

Answer in your head first, then open the answer.

Name three things a platform is often confused with.

A developer portal, a tool, a project (or a ticket desk).

What makes a platform a product?

Users with known problems, an owner who decides what comes next, and adoption by choice.

Why write non-goals?

So the team can say no consistently and stay small.

Where module 01 leaves you: platform.yaml in your repo passes the check (ok platform.yaml). It names two users of kind human, each with problems and evidence, the owner platform, a product owner and three non-goals.

02 Teams and how they work together

The idea

A platform team exists to reduce product teams' cognitive load. Team Topologies names four team types and three interaction modes, and collaboration is planned to end in X-as-a-Service.

Remember

  • Team types: stream-aligned, platform, enabling, complicated-subsystem.
  • Modes: collaboration (costly, temporary), X-as-a-Service (the default for a working platform), facilitating (teaching).
  • Collaboration needs until and then in teams.yaml (rule T4).
  • The owner in platform.yaml must be a team of type platform (T5).
  • From here on every owner must be a team in teams.yaml (O1).

Pitfalls

  • A collaboration with no end turns the platform team into part of one product team.
  • An owner that is a stream-aligned team fails T5.

Test yourself

Answer in your head first, then open the answer.

Which mode should most teams have with the platform most of the time?

X-as-a-Service.

What is an enabling team for?

Helping other teams learn a skill, then stepping back.

Why does collaboration need an end date?

It costs both teams time; the platform team can only do it with a few teams at once.

Where module 02 leaves you: teams.yaml passes the check, and the check now also confirms that the owner in platform.yaml is a platform team. The platform team collaborates with checkout until a date, and then becomes X-as-a-Service.

03 The capability map: what the platform offers

The idea

The capability map is the platform's menu: what a team can get, from whom and how. It must tell the truth: offered means self-service, and planned means nothing may depend on it yet.

Remember

  • The CNCF white paper lists thirteen capability areas, from web portals and APIs to artifact storage.
  • Statuses: offered, beta, planned.
  • Offered or beta needs a self-service interface: portal, cli, api, git or mcp. ticket alone fails C2.
  • Name a capability by what the user gets, not by the tool behind it.
  • The seven layers are this course's grouping, not a standard.

Pitfalls

  • Calling a ticket queue "offered" fails C2.
  • Leaving out planned capabilities hides the roadmap from users.

Test yourself

Answer in your head first, then open the answer.

Is a namespace by ticket within a day self-service?

No: the team still waits for a person to act.

Why list planned capabilities?

So teams know not to build on them, and the gaps are visible.

What fields does each capability carry?

id, name, layer, owner, status, interfaces, users.

Where module 03 leaves you: capabilities.yaml passes the check: eleven capabilities, every one owned by platform, three of them planned, every offered or beta one with a self-service interface. All are for humans for now.

04 Golden paths: the supported way, not the only way

The idea

A golden path is the opinionated and supported way to do one job end to end. It is optional, so it must be the easiest way; it has an escape hatch, and it paves only with what exists.

Remember

  • Spotify (2020): "the 'opinionated and supported' path to 'build something'".
  • optional: true and an escapeHatch (rule G3); support (G4).
  • Every step's capability must exist and not be planned (G2).
  • Mandatory rules are guardrails, enforced by policy, not by the path.
  • A template is one step of a path, not the path.

Pitfalls

  • A step on a planned capability fails G2: the path promises what does not exist.
  • A mandatory path is a mandate; teams leave it silently or fight it.
  • An eleven-step path that covers every case gets used by nobody.

golden-paths/new-service.yaml (part)

optional: true
escapeHatch: >-
  A team that needs something else builds it themselves, writes an ADR, and owns its pipeline and on-call.
support: "#platform-help, answered within one working day"
steps:
  - t: Create the repository from the template
    capability: repo-template

Test yourself

Answer in your head first, then open the answer.

What should a team do when the path does not fit?

Follow the escape hatch: take on that part, write down why, tell the platform team.

Path or guardrail: "no prod deploy without approval"?

A guardrail: it applies on and off the path.

When does a step for a new capability go into the path?

In the same change that marks the capability offered or beta.

Where module 04 leaves you: golden-paths/new-service.yaml passes the check: six steps on offered capabilities, optional: true, an escape hatch, a support channel, and for: [humans].

05 Agents: the platform's second kind of user

The idea

Coding agents are users of the platform. They get the same paths as people, with their own identity, an interface they can call, written instructions, and limits on functionality, permissions and autonomy.

Remember

  • OWASP LLM06:2025 Excessive Agency: excessive functionality, permissions and autonomy.
  • Non-human identity: the agent acts as itself, never with a person's token (A3).
  • default: deny; a non-read action in prod needs approval: human (A1, A7).
  • Every agent has an owner team, a monthly budget and an audit log (A5, A6).
  • MCP: an open standard for connecting AI applications to external systems.
  • AGENTS.md: "a README for agents", shipped in the golden-path template.
  • Capabilities for agents need api, mcp, git or cli (C3); policy rules need api or mcp (A4).

Pitfalls

  • A personal token gives the agent all of that person's access and their name in the audit log (A3).
  • Removing the approval to fix a slow wait (A7): fix the wait instead.
  • An agent that guesses the build command is missing context, not permissions.

agents/policy.yaml (part)

default: deny
agents:
  - id: checkout-coding-agent
    owner: checkout
    identity:
      kind: non-human
      name: agent:checkout-coding
    budget:
      monthlyEur: 400
    audit: true
    allow:
      prod:
        - action: deploy
          capability: deploy
          approval: human

Test yourself

Answer in your head first, then open the answer.

Name the three causes of excessive agency.

Excessive functionality, excessive permissions, excessive autonomy.

Why its own identity?

It can be scoped, audited and revoked without locking a person out.

Where do agents learn the path?

From AGENTS.md in the repository, copied from the template.

What may an agent do in prod without approval here?

Read: logs, metrics, the catalog.

Where module 05 leaves you: platform.yaml has a third user, coding-agent, of kind agent. Nine capabilities list agents as users. The path is for: [humans, agents] and names golden-paths/new-service/AGENTS.md. agents/policy.yaml passes the check with two agents.

06 Measuring value: outcomes, not output

The idea

Measure outcomes against a baseline, not output. DORA's five delivery metrics, adoption, developer experience and cost show whether the platform and AI help; counts of code and pull requests rise even when they do not.

Remember

  • DORA throughput: change lead time, deployment frequency, failed deployment recovery time.
  • DORA instability: change fail rate, deployment rework rate.
  • DORA 2025: AI's "primary role is as an amplifier" of existing strengths and weaknesses.
  • METR 2025: experienced developers took 19% longer with AI and believed they were 20% faster.
  • baseline: unknown is honest; a missing baseline fails M2.
  • Output counts as metrics fail M3; put them under avoid with a reason (M5).

Pitfalls

  • "Share of code written by AI" as a target rewards volume, not outcomes.
  • Trusting how fast people feel instead of measuring lead time.
  • No cost metric once agents have budgets fails M4.

Test yourself

Answer in your head first, then open the answer.

Which metric answers "is AI helping?" here?

Change fail rate of AI-assisted changes compared with the rest, next to lead time.

Name DORA's two instability metrics.

Change fail rate and deployment rework rate.

What is the first month's work on this scorecard?

Measuring the four unknown baselines.

Where module 06 leaves you: metrics/scorecard.yaml passes the check: eight metrics, at least one each of delivery, stability, adoption, experience and cost, four baselines still unknown, and two metrics under avoid with the reason.

07 Capstone: the first decision and the first 90 days

The idea

An ADR keeps the context, options and consequences of a decision next to the design; the 90-day plan turns it into three phases that each end on a measured result.

Remember

  • ADR sections after Nygard (2011): title, context, decision, status, consequences; this course adds options considered (D2, D3).
  • An ADR is never rewritten: a new one supersedes it.
  • Phases: see it (0-30), pave it (31-60), prove it (61-90) (N1).
  • Each phase exit names a scorecard metric and a result (N3).
  • CNCF maturity levels: provisional, operationalized, scalable, optimizing.

Pitfalls

  • An exit on a date fails N3: time passing proves nothing.
  • An ADR with one option was not a decision (D3).
  • Editing an old ADR loses why the old decision was right then.

Commands

git switch -c adr-0002A branch for the change
gh pr create --fillOpen a pull request
gh pr checks --watchWait for the design check
gh pr merge --squash --delete-branchMerge it

Test yourself

Answer in your head first, then open the answer.

Why list options in an ADR?

So a later reader sees what was weighed and can tell if the decision still holds.

What do you do with an ADR that no longer fits?

Write a new one that supersedes it and mark the old one superseded.

Where does the plan keep the dates?

In each phase's days; the exit keeps the result.

Where module 07 leaves you: docs/adr/0001-first-golden-path.md and plan/90-days.yaml pass the check. Your own docs/adr/0002-*.md is merged through a pull request with a green check. Every part of the design passes npm run check.