Section 13Systematise — the repeatable system & the golden-path stack

Everything so far is a workflow you run by hand. The final move turns it into a system, so every new project starts at rung 4 instead of climbing from zero. Two layers, and inheritance between them.

A note on what this chapter hands you, and what it doesn't. There is no template repository to clone at the end of it — deliberately, because the chapter's own strongest argument is that the template is the last move, not the first. What you get instead is the specification of a golden-path stack (which categories must be present, and one concrete set of choices that satisfies them), plus the mechanics of turning your own first mature project into a template other projects inherit from. Clone someone else's starter and you inherit their unexamined decisions; extract your own and you inherit decisions you already paid for.

Section 12 closed with a promise: budgeted context and deterministic gates shouldn't stay habits you re-establish by hand every Monday. This chapter keeps that promise, and it starts with an observation about everything that came before. Nearly every practice in this guide has quietly produced a file: standing instructions in AGENTS.md, skills for grilling and test-first work, hooks that enforce house rules, a decision log of ADRs in docs/adr/ (Section 10), a pipeline definition (Section 8), an eval suite (Section 12). A workflow is those files plus your discipline. A system is those files arranged so the discipline is no longer required — so a new project physically cannot start without them.

Picture the salon owner a few months from now. The booking app took the whole guide to reach production-ready: grilling, tickets, tests, a pipeline, security gates — weeks of climbing. Then she decides to build a second product, a gift-voucher shop for the same salon. Without a system, project two starts the climb from the bottom: naked repo, no hooks, no gates, every lesson re-learned. With the two layers below, project two is born at rung 4 — her hooks fire in the very first session, tests and CI exist before the first feature, staging is a side effect of the first commit. That's what "inheritance" means here: not a metaphor, a mechanism.

Layer 1 — the config that travels with you

The first layer holds everything that is true for you regardless of project. In Claude Code that has a concrete address: a user-level CLAUDE.md (at ~/.claude/CLAUDE.md) is read at the start of every session in every project, alongside whatever the project itself provides — and your personal skills and hooks live in the same per-user config directory. That's the right home for the things you would otherwise re-type forever: the grilling and TDD skills you've refined over months, the pnpm-not-npm hook, standing preferences like "ask before adding a dependency" or "propose a plan before touching more than three files." The sorting test is one question: would I want this in every project I'll ever start? If yes, it's global. If it's about this codebase — its floor plan, its commands, its conventions — it belongs in the project's own AGENTS.md, which sits alongside and speaks for the repo.

Plugins — the inheritance mechanism, shipped

Loose files in ~/.claude/ are the right way to start, and they stop scaling at a predictable moment: when there's a second machine, or a second person, or a change you want to be able to undo. Copied files have no version, no source of truth, and no way to answer "which of these three machines has the good version of the hook?" The mechanism that fixes this is a plugin, and it is worth noticing what it is: a plugin bundles skills, subagents, slash commands, hooks and MCP server definitions into one versioned, installable package. That is this chapter's thesis — inheritance as a mechanism, not a metaphor — existing as a shipped product feature rather than a discipline you maintain by hand.

You install one with /plugin, which opens a browser of what's available and what you already have. Plugins come from a marketplace — a repository listing plugins, which you add with /plugin marketplace add. Anthropic maintains a curated official marketplace and a public community one; a marketplace can equally be a private repo belonging to you, which is the interesting case here. Your grilling skill, your TDD skill, the pnpm hook, the ticket-implementer subagent from Section 11 and the project-doctor skill below are not five things to remember to copy — they're one plugin with a version number, installed by one command, updated in one place, and rolled back if a change turns out to be wrong.

Attach the tools once, inherit them forever

The other half of Layer 1 is what the agent can reach. MCP is the standard for connecting an agent to an outside system — your error tracker, your issue tracker, a documentation service — and this guide has so far only ever mentioned it defensively: vet it (Section 9), load it on demand (Section 12). Here is the constructive half, because a system that can't reach anything isn't much of a system.

You attach a server on the command line, and the only decision that really matters is the scope:

# local (the default): this project, this machine, just you
claude mcp add my-tool -- npx -y some-mcp-server

# user: every project on this machine — Layer 1
claude mcp add --scope user linear --transport http https://mcp.linear.app/mcp

# project: written to .mcp.json and committed — the whole team inherits it
claude mcp add --scope project sentry --transport http https://mcp.sentry.dev/mcp

Three scopes, three different answers to "who is this for?" — and it is the same sorting question as the rest of this chapter. user scope is for tools that follow you: they belong to Layer 1 alongside your skills and hooks. project scope is the one that makes this a system rather than a personal setup: it writes the server into .mcp.json at the repository root, which you commit, so anyone who clones the repo — a teammate, a stand-in developer, an agent in a fresh CI container — gets the same connections without a setup document to follow. Put that file in the template and every project born from it inherits the wiring too. Remote servers are attached the same way with --transport http; ones that need an account walk you through an OAuth login the first time the agent uses them, so no token has to be pasted anywhere it might get committed.

Two cautions carry over unchanged rather than being repeated here. Every server you attach spends context on its tool definitions, so attach what a project actually uses and no more (Section 12). And a committed .mcp.json is a shared decision about what every agent on the project may reach, which makes it exactly the supply-chain review from Section 9 — with the useful side effect that, unlike a server someone added on their own laptop, it arrives as a diff in a pull request where somebody can see it.

Layer 2 — a golden path for the stack you actually use

The second layer is project-shaped: a starter repository for the kind of thing you build, with every hard-won standard from this guide already wired in. The name for this idea is a golden path, and it's worth taking seriously rather than treating the template as a convenience.

The point of the template: inheritance guarantees coverage. The non-functionals from Section 7 and the pipeline from Section 8 become impossible to forget — they're already there before the agent writes a line. One concrete stack that satisfies every category, for a PWA at scale:

• Build: Vite + TypeScript in strict mode (noUncheckedIndexedAccess); Workbox for offline/PWA.
• Tests: Vitest for logic, Playwright for behaviour — with video recording on, so every run produces a demo reel (Section 6).
• Pipeline: CI to Cloudflare Pages, where each preview deploy is your staging; Lighthouse performance budgets and security scans are merge gates. Whatever the hosting needs configured — domains, environment variables, the database, the access roles — lives in the repo as infrastructure as code rather than in a console someone clicked once, so a fresh copy of the template stands up its own environment instead of waiting on a memory.
• Operate: feature flags, error tracking, and Core Web Vitals RUM wired from the start.
• Steer: a lean AGENTS.md (with CLAUDE.md importing it), the pnpm-not-npm hook, the skills, docs/adr/, context.md, and a PR template that encodes the definition of done.

The full-stack extension of this template — a real database, auth, background jobs — is walked through step by step in the companion page Setup, part two: production infrastructure.

Mechanically, turning a repo you already trust into a template is one checkbox — and that is the whole of the tooling, which is the point: the work was building the first project well, not the promotion. Mark it as a template repository on GitHub and it grows a "Use this template" button that stamps out a fresh copy — your files, none of your git history — as a brand-new project. So the gift-voucher shop begins as a click: commit one already carries strict types, both test layers, the pipeline, the security scans, and the PR template that encodes the definition of done. The agent's first session reads the inherited AGENTS.md, finds the floor-plan conventions from Section 10 waiting, and starts building the first tracer bullet inside a fully-gated project. Weeks of climbing, replayed in a minute.

Compounding — one fix, every project

Two layers turn maintenance upside down. When something goes wrong in any project — an accessibility gate that turned out to be missing, a deploy step that flakes, a lesson learned at 11pm — the reflex question becomes: does this fix belong upstream? Patch it in today's repo and one project improves. Patch the template, a skill, or the global config, and every future project improves — and every past one can be pulled up to match. The skill below is that reflex made executable.

The same compounding works on your standing instructions — with one guard. When a session ends with a lesson worth keeping ("always run the migration check before seeding"), have the agent propose it as a permanent rule rather than letting it evaporate. But cap the list — around fifteen entries, oldest pruned when a new one lands — because a learnings file that only ever grows quietly eats the instruction budget Section 12 tells you to protect, and old lessons go stale just like old docs.

The mechanics of "have the agent propose it" are worth pinning down, because the difference between a learnings file that compounds and one that rots is a human gate. End each significant session with one question: "Anything from this session worth making permanent? Draft it as a one-line rule and tell me which file it belongs in — global config, this project's AGENTS.md, or the template." You approve or reject, the same way you gate any other change. Then it goes into a file rather than into the chat: say "add that to CLAUDE.md" and the rule is written where every future session reads it, and /memory lists every instruction file currently in play — user-level, project, local — and opens any of them for editing. Make that command your audit: once a month, read what's accumulated and prune, because this is where the fifteen-entry cap actually gets enforced.

There is a second, quieter memory to know about, precisely because it does not go through your gate. Claude Code also keeps an auto memory — notes it writes for itself, per repository, about build commands and things you corrected it on — and loads the top of it into every session. It is genuinely useful and it is not a substitute for the ritual above, because nothing about it is reviewed: it records what the agent inferred, not what you decided. The division that works: auto memory holds the incidental ("the test suite needs Redis running"), and the rules you approved and wrote into CLAUDE.md hold the load-bearing. Auditing the first is another line for the project-doctor skill; /memory opens it too.

For the salon app, a real entry might read "Playwright tests must create their own bookings, never rely on seeded data" — earned during an afternoon lost to a flaky test, worth exactly one line of the instruction budget, and destined for the template so the voucher shop never loses that afternoon at all.

A living docs site, not a stale wiki

AGENTS.md is terse and machine-read every session; docs/adr/ is a raw, append-only decision log. Neither is what a new teammate — or an auditor, or future-you in a year — actually wants to read. Build a third thing: an HTML documentation site generated from files in the repo, rebuilt and republished by CI on every merge to main, the same pipeline that ships the app. Docs written once and left alone rot faster than code, because nothing forces them to change when the code does; a site that only exists as a fresh build of current repo state can't drift the same way a hand-maintained wiki does.

What belongs on it, concretely — the questions this guide keeps coming back to, answered for your project specifically, not in the abstract:

Tooling: Starlight (Astro-based, fast, good defaults out of the box) or Docusaurus (React-based, larger plugin ecosystem, more moving parts) for a JS/TS project; MkDocs with the Material theme if your team leans Python. Whichever you pick, the mechanism matters more than the choice: a docs-build-and-deploy step in the same CI that ships code, and a merge-gate check that flags a PR touching auth, access, pricing, or architecture with no corresponding docs change — the same "did you update the runbook" discipline this guide already asks of disaster-recovery playbooks, applied to documentation generally. The mechanism is unglamorous: a path-based rule — a CODEOWNERS-style list mapping sensitive code paths (the auth module, billing, the schema folder) to the docs pages that describe them — so CI flags any PR that changes the left side without touching the right. Back it with one line in the reviewing agent's checklist ("does this change alter anything a docs page currently claims?") to catch the renames and logic-only changes a path list can't see. As the team grows past a handful of people, a fuller internal developer portal (Backstage is the standard open-source reference) can absorb this same content plus service ownership and catalogues — but the CI-published docs site is the right size for a small team, and grows into that later rather than needing it from day one.

For the salon owner, a documentation site can sound like enterprise ceremony — she's one person; who's the audience? The honest answer: it's insurance against exactly the situations a one-person business can't absorb. A stand-in developer taking over while she's ill for a month. An auditor — or a bigger client's procurement form — asking who can access customer data and where the DPA lives. Future-her, a year after the last change, needing to know why bookings and vouchers share a customer table. Each of those is answered today by archaeology through old chats; the docs site answers them with a URL. And because agents draft the pages from files that already exist — the ADRs, the pipeline config, the access roles — the marginal cost of the insurance has never been lower.

Measure the system, not vibes

Track whether the system actually helps, using DORA metrics: deploy frequency, lead time, change-fail rate, restore time. And run the evals from Section 12 so you improve on evidence, not gut feel.

Used alone with agents, the four numbers have a specific job: watch trends, not absolutes. Agents inflate the speed pair almost for free — of course you deploy more often when implementation costs minutes. The stability pair is where the truth lives. If change-fail rate climbs alongside deploy frequency, the message is precise: your gates are now too weak for your new speed, and the fix is tightening the template's merge gates, not slowing down by hand. DORA measures the pipeline; the evals measure the agent workflow flowing through it. One dashboard for the factory, one for the machine — and both feed the same upstream reflex: every bad trend becomes a fix to the template or a skill, not a resolution to try harder.

Fast agentic output accumulates technical debt silently unless someone looks on purpose. Thoughtworks' Tech Radar practice is a lightweight way to do that: periodically review the tools, libraries, and patterns actually in use and rank each one adopt / trial / assess / hold — so a dependency an agent pulled in eight months ago gets revisited deliberately instead of forgotten until it breaks.

The solo version fits in one quarterly session, and it's another saved prompt: "List every dependency with what it does, when we adopted it, and when its maintainers last released. List every recurring pattern in the codebase. Rank each adopt / trial / assess / hold, and propose tickets for the holds." Half an hour, four times a year — and the charting library an agent pulled in for one graph, unmaintained upstream since spring, becomes a scheduled ticket instead of a security surprise (Section 9's supply-chain worry, handled on a calendar instead of in a crisis). As with Section 10's architecture review, the session ends in tickets, not vibes.

Extract the system — don't build it first

One warning saves weeks: the template is the last move, not the first. Building a perfect golden-path template before shipping anything is procrastination wearing safety gear — you can spend a month wiring gates for projects that don't exist and learn nothing. The sequence that works is the one the salon owner actually lived: build the first project by hand, the whole climb, every chapter of this guide the slow way. Then, when the second project starts and you catch yourself re-doing something — re-writing the same hook, re-explaining the same convention, re-wiring the same pipeline — that is the moment to extract it into the template. Extracted machinery has earned its place, because it demonstrably worked in a shipping project; invented machinery is a guess with a maintenance cost. The same rule governs the small stuff: the third time you type the same correction, make it a hook; the third time you paste the same prompt, make it a skill. The system follows the work. It never precedes it.

When it stops being just you

This guide has spoken to one person throughout, because that is how most projects start and because the moves are the same either way. But the goal it keeps pointing at — software a million people depend on — is never maintained alone, and the system this chapter builds is exactly what a second engineer inherits on their first morning. So it's worth being explicit about what changes when the team grows, because one thing changes fundamentally and most things don't.

What changes is where the bottleneck sits. Without agents, a team's constraint is how fast it can write code. With agents, five engineers can generate far more code than five engineers can meaningfully read, and the scarce resource quietly becomes review capacity and shared understanding. Every practice below follows from that one shift. If you take nothing else: the team's job is no longer producing code, it is staying collectively certain about code that arrives faster than anyone can read it.

Which is why human review doesn't go away — its job changes. The agent review from Section 6 covers the mechanical layer properly: does it match the spec, does it hold the standards you encoded, does it break anything. Leave that to the machine, because it does it tirelessly and at 3 a.m. What remains is the part no agent can hold — is this the right thing to build at all, does it fit where this system is going in six months, and does the person who submitted it actually understand what shipped. State the boundary plainly to your team, because it will be tested the first busy week: "an agent reviewed it" is not a substitute for a human approving it. The failure mode is a team where every pull request carries a green checkmark, nobody has read the code, and everybody assumes somebody did — a state that feels like velocity right up until the first outage nobody can explain.

Ownership is the next thing to make explicit, via a CODEOWNERS file — a plain map from paths to people, which your repo host uses to request the right reviewer automatically. The agentic case for it is stronger than the traditional one. When changing an unfamiliar subsystem took a week of reading, distance was its own protection; nobody wandered into the billing code by accident. When anyone can generate a plausible change to any subsystem in ninety seconds, that protection is gone, and the person who will be paged when billing breaks needs to be in the loop by default rather than by luck.

The deeper shift is that your instruction files stop being preferences and become contracts. Solo, AGENTS.md, the ticket template and the definition of done are notes to yourself, and you can change them on a whim. On a team they steer everyone's agents at once: a rule merged into AGENTS.md on Tuesday changes what five people's agents do on Wednesday, without anyone reading the diff. Treat them accordingly — reviewed, versioned, and argued about like code, because they now have more leverage over the codebase than most code does. This is the single most under-appreciated consequence of a team adopting agents, and the cheapest one to get right early.

The genuinely good news is onboarding. An agent-ready repository is already an onboarding document, and you built it for other reasons. A newcomer's first day is reading AGENTS.md, then the ADRs in docs/adr/ for why things are the way they are, then running the golden path end to end to prove their machine works. Their first week's instruction is the one that used to be impossible: ask the agent, not a senior. "Why does this project store bookings locally first?" now has a documented answer the agent can find and explain at whatever depth they need, at 11 p.m., without occupying the one person who knows. The traditional cost of a new hire is the senior engineer they consume for a month; a well-instructed repo returns most of that month.

Finally, branches want to be shorter, not longer. Agents make it effortless to accumulate a fortnight of parallel work across several worktrees, and effortless accumulation is exactly the trap — the merge pain scales with the square of everyone's divergence, and it lands on whoever merges last. The Section 11 machinery is for running work in parallel over hours and days, not for maintaining private universes over weeks. Keep branches short, merge behind a feature flag when the work isn't finished, and let the flag rather than the branch be the thing that hides unfinished features from users. That is the same advice teams have given for a decade; agents merely raised the penalty for ignoring it.

And that ordering points at the one thing no template can contain. This chapter is the last mechanical move the guide has to offer — config, templates, docs, metrics, all of it inheritable, all of it file-shaped. What remains is not file-shaped at all: knowing when to trust the system, when to override it, and when not to hand a task to an agent in the first place. That judgment is Section 14.