Claude Code for platform teams: a setup that survives contact

Agentic coding tools are good at the work platform teams have most of: repetitive manifest edits, migrations across dozens of repositories, reading logs, writing the fifteenth CronJob. They are also one kubectl credential away from being the most expensive mistake in your week.

The difference is configuration, and most of it is decided in the first hour.

Write the context file for a competent stranger

A project context file — CLAUDE.md at the repository root — is read at the start of every session. Its job is to carry what a new engineer would need on day one and would otherwise get wrong.

What earns its place:

• Commands that are not guessable. make verify rather than npm test, and what each actually runs.
• Conventions with consequences. “Manifests go in deploy/overlays/<env>, never in base.” “We use Kustomize, not Helm, and PRs adding a chart get rejected.”
• Hard constraints. “Never edit files under generated/.” “Production values live in Vault; there are no secrets in this repo.”
• Local idioms. The internal tool nobody outside the team has heard of.

What wastes it: restating the language’s conventions, listing the directory tree, or explaining what Kubernetes is. Long context files get skimmed by humans and dilute attention for models. Ours run to about a page.

The test for a line: would a competent engineer joining the team get this wrong without being told? If not, cut it.

Permissions are the real safety boundary

Prompts are advice. Permission rules are enforcement.

Allow the things that are read-only or trivially reversible, and require approval for the rest. In practice that means allowing your test runner, linter, formatter, git status/diff/log, and read-only cluster queries; and gating anything that writes to a cluster, pushes, deletes, or touches infrastructure state.

The distinction to hold onto: reversibility, not risk of being wrong. A command that produces a bad diff is cheap — you read it and discard it. A command that scales a Deployment to zero in production is not, and no amount of model quality changes that. We covered the same principle from the API side in using Claude in DevOps: put the gate in the tool, not in the prompt.

Two rules that have saved us:

• terraform plan yes, terraform apply never unattended
• kubectl get/describe/logs yes, everything mutating gated — and against production, not even reads without a reason

Hooks are where determinism belongs

A hook runs on an event — after a file is edited, before a command runs — and it is code, so it behaves the same every time.

Anything you would otherwise write as “always remember to…” in the context file is better as a hook. Formatting after every edit. A linter that fails the edit. A check that a manifest still passes kubeconform. A block on any write to a protected path.

The reason to prefer a hook is not tidiness. An instruction in a context file is followed most of the time; a hook is followed every time. For anything where “most of the time” is a security or correctness problem, that gap is the whole point.

We use a hook on this site’s own repository: the design detector runs after every UI file edit and reports anti-patterns inline. It has caught real defects that the model and I both missed.

Subagents, and when they earn their cost

A subagent runs with its own context window and reports back a summary. That is useful in exactly two situations:

Search that would flood the main context. “Find every place we set imagePullPolicy across 40 repositories” produces hundreds of lines you do not want resident for the rest of the session. A subagent reads them and returns the list.

Independent work that can run in parallel. Ten repositories needing the same mechanical change, each isolated from the others.

They are a poor fit for tightly coupled work. A subagent cannot see your conversation, so anything requiring the reasoning you have already done together has to be re-specified, and you usually spend more effort writing the brief than doing the task.

Where it genuinely helps a platform team

From our own use, ranked by how reliably it pays:

Cross-repository mechanical change. Bumping a base image across every service, migrating a deprecated API version, adding a label everywhere. Tedious, well-specified, easy to verify by diff.

Reading a lot of output. Correlating a 200MB log dump, diffing two clusters’ resource inventories, working out which of 60 CronJobs has not succeeded this month.

First drafts of runbooks and postmortems. From a real timeline, with a human owning the conclusions.

Terraform and manifest review as a second pair of eyes. Not as a gate. It catches the details a tired reviewer misses at 5pm and misses things a careful reviewer would not.

Where it does not

Anything you cannot cheaply verify. The rule holds everywhere: if checking the answer is as expensive as producing it, generating it saves nothing.

Incident response. Triage and summarising, yes. Deciding to fail over, no. The blast radius and the time pressure are the two conditions under which you least want a confident guess.

Capacity and cost decisions. These need numbers from your own cluster and a judgement about the business. An agent will produce a plausible answer from neither.

The failure mode to watch for

The one that costs teams real time is not a bad edit — you catch those in review. It is progress that outran verification: a report that the migration is complete across all repositories when three of them silently failed.

Two things reduce it. Ask explicitly for faithful reporting, including what failed and what was skipped. And require that every claim of success point at a command output from the same session. If it says the tests pass, the test output should be in the transcript.

Then read the diff. Every time. The value here is a fast, tireless engineer with no judgement about consequences, and that is worth a great deal as long as somebody with judgement is still reading the output.