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
This module only · Full module
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] messageper broken rule. It runs nothing from the repo. - Two kinds of user: people and the coding agents that work for them.
npm ci --ignore-scriptsinstalls exactly the lock file, with no install scripts.- The workflow
design-checkruns the same check on every push tomainand every pull request.
Pitfalls
- Pushing without running the check:
mainturns red with[Y1]for invalid YAML. - A line indented by accident becomes part of the line above it in YAML.
Commands
npm run check | Check every design file |
gh run list --workflow design-check --limit 1 | The latest run on GitHub |
gh run view --log-failed | Why 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
This module only · Full module
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
P2and 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
This module only · Full module
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
untilandtheninteams.yaml(ruleT4). - The owner in
platform.yamlmust be a team of typeplatform(T5). - From here on every
ownermust be a team inteams.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
This module only · Full module
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.
ticketalone failsC2. - 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
This module only · Full module
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: trueand anescapeHatch(ruleG3);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
This module only · Full module
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 needsapproval: 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
This module only · Full module
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: unknownis honest; a missing baseline failsM2.- Output counts as metrics fail
M3; put them underavoidwith 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
This module only · Full module
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
exitnames 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-0002 | A branch for the change |
gh pr create --fill | Open a pull request |
gh pr checks --watch | Wait for the design check |
gh pr merge --squash --delete-branch | Merge 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.