Platform engineering fundamentals for the AI era: printable course notes
Design a platform as a product for people and agents: mission and users, team topologies, a capability map, a golden path, an agent policy, a scorecard, an architecture decision record and a 90-day plan, all as files in Git with a check on every pull request.
These pages are the same content as the interactive course, on one page per module, for reading and printing.
Four pieces
| Piece | What it is |
|---|---|
| See the end result | Not the first step: a 20-minute preview. Clone the finished design, run its check, break one rule and read the files. Useful to know where you are heading. |
| Full course | 8 modules from an empty repo to a platform design with a decision and a 90-day plan: the platform as a product, teams, capabilities, a golden path, agents as users, a scorecard, and a capstone. |
| Reference repo | The finished design for the example company, and the check that reads it. |
| Your repo | platform-design: your platform's design as files. You create it in module 00. |
Your setup
Commands in these notes use these values (shared with the interactive course, stored only in this browser).
Outline
| Module | Part | Time | You are | You will |
|---|---|---|---|---|
| 00 Orientation: a platform design you can check | Orientation | 15 min | Platform team | Create your repo platform-design with the design check, and see the check run on GitHub. |
| 01 What a platform is, and platform as a product | The product and its people | 25 min | Platform team | Write platform.yaml: the mission, the users and their problems with evidence, the owner and the non-goals. |
| 02 Teams and how they work together | The product and its people | 25 min | Platform and product | Write teams.yaml: five teams with their Team Topologies types, and how each pair works together and why. |
| 03 The capability map: what the platform offers | What the platform offers | 25 min | Platform team | Write capabilities.yaml: eleven capabilities in seven layers, each with an owner, a status and the interfaces people use to reach it. |
| 04 Golden paths: the supported way, not the only way | What the platform offers | 25 min | Platform and product | Write golden-paths/new-service.yaml: six steps from repository to production, each on an offered capability, with support and an escape hatch. |
| 05 Agents: the platform's second kind of user | What the platform offers | 30 min | Platform team | Make coding agents users of the platform: an agent user in platform.yaml, capabilities they can call, AGENTS.md in the golden path, and agents/policy.yaml with identity, scope, approval, budget and audit. |
| 06 Measuring value: outcomes, not output | Prove it | 20 min | Platform team | Write metrics/scorecard.yaml: eight metrics for delivery, stability, adoption, experience and cost, each with a source, a baseline and a target, and a list of metrics to avoid. |
| 07 Capstone: the first decision and the first 90 days | Prove it | 35 min | Platform team | Write ADR 0001 and plan/90-days.yaml for the example company, then an ADR of your own, unaided, through a pull request. |
Between you and a real platform
- The design reviewed with users: Two or three developers from different teams read `platform.yaml` and the golden path, and recognise their problems in them.
- `main` protected: Changes to the design only through pull requests, with the design check required and a review from the platform's product owner.
- Baselines measured: Every `unknown` in the scorecard replaced by a number from your own systems, with its source.
- The agent policy enforced: The rules in `agents/policy.yaml` implemented where agents act: identity provider, API or MCP gateway, deploy approvals. The file is the design, not the control.
- Personal tokens found and replaced: An audit of where agents use people's tokens today, and a date by which each has its own identity.
- A regular review: The capability map, the team interactions and the plan reviewed every month; ADRs written for decisions that are expensive to reverse.
- The first path built: The golden path automated end to end: [Kubernetes](/learn/kubernetes/) and [Terraform](/learn/terraform/) for the runtime, [Argo CD](/learn/argocd/) for delivery, [Backstage](/learn/backstage/) for the catalog.