TL;DR

I point Claude at a problem, give it a direction, and let it run — and most of the time I don’t read the merge request it opens. On an internal homelab where the blast radius is my own cluster, backups are real, and everything’s reproducible from code, line-by-line diff review is the wrong altitude. Instead I supervise after the fact by reading the artifacts the agents leave behind: the /docs/ folder, a Wiki.js wiki full of Mermaid diagrams, auto-generated architecture SVGs, and this blog. Reading those — not the diffs — is what’s actually caught problems: dead systems still wired in, duplicate config, a deploy that quietly deleted itself.

The diff is the wrong altitude

Here’s the uncomfortable thing I’ve made peace with: I do not review most of what Claude does in my homelab. Roughly 55% of the commits in my cluster repo — about 1,958 of 3,559 — carry a Co-Authored-By: Claude trailer, and I have read maybe a tenth of those diffs with any real attention.

That sounds reckless until you look at what it’s touching. This is internal infrastructure. Nothing here is customer-facing. The state that matters is on Longhorn with backups, the config is all in Git, and a bad change is a git revert and a redeploy away. The cost of a mistake is my own evening, not someone else’s data. When the downside is that cheap and that recoverable, sitting and grading a 40-file merge request line by line isn’t diligence — it’s theater. I covered the broader version of this in the autonomy trust ladder: trust is earned per-agent, per-repo, and infra agents stay capped lower than the rest. But within those caps, I let them run.

So if I’m not reading the diff, what am I doing? I read the documentation. A diff tells you what changed. A good architecture doc tells you what you now have — and that second question is the one I actually care about, because the thing I lose fastest when I let agents run is a current mental model of my own system.

The four surfaces I actually read

I lean on four artifacts, in roughly ascending order of how often they catch something:

  1. The /docs/ folder. My cluster repo carries 31 markdown docs — a platform reference, a hardware inventory, a long ai-lessons.md of failure patterns, a CI_AUTOMATION.md describing the LLM harness. Agents write and update these as a side effect of doing the work. I read them like a newspaper about my own house.
  2. The Wiki. Wiki.js, heavy on Mermaid. This is where the human-facing narrative lives — the stuff I want to skim on a phone, not in a repo.
  3. The diagrams. I had Claude write a Python generator that turns the architecture into SVGs — 27 of them at last count, replacing 53 hand-maintained Mermaid blocks. Data-flow, auth flow, storage tiers, alert routing.
  4. This blog. Writing a post forces a level of explanation that internal docs let you skip. More than once, drafting a post is where I noticed the thing was dumber than I’d assumed.

The pattern across all four: I made Claude the writer and myself the reader. That inversion — produce a lot, consume selectively — scales in a way that “review everything” never did.

What reading the docs has actually caught

This is the part that justifies the whole approach. None of these came from reading a diff. All came from reading what the agents documented.

A dead service still wired into the cluster. While reconciling some firing alerts, an agent audited the documented application list against what was actually deployed and found a media-library namespace that existed in three docs — the platform reference, the secrets inventory, the deployed-apps list — but had no live workload behind it. The backing store was gone; the blog’s image pipeline had quietly moved to local ComfyUI and direct S3 upload months earlier. The service was a ghost referenced only by its own documentation. Decommissioning it (2026-04-23) was a 123-line deletion of RBAC and stale docs. I’d never have spotted it in a diff — there was no diff. It was an absence, and only an audit of the docs against reality surfaced it.

Duplicate config inflating every session. A cleanup pass found four skill definitions sitting locally in the cluster repo that were byte-for-byte identical to global copies. They were costing tokens on every single session in my busiest repo for zero benefit. 576 lines of redundant definitions removed (2026-05-29). Pure redundancy, found by an agent reading the tree it lived in.

Orphaned credentials nobody was tracking. A review noticed one repo was authenticating to my container registry with a robot account that had been rotated out everywhere else. Pulling that thread revealed the registry had quietly accumulated three generations of CI robots (ci-builder, ci-builder-v2, ci-push-v2) because the rotation runbook only ever covered some repos. The fix consolidated to one robot and added a lint rule to block new ones (2026-04-17). Again: surfaced by an agent reading documentation against state, not by me reading a PR.

A deploy that deleted itself. My favorite, because it’s the blog you’re reading. The deploy pipeline does a two-pass aws s3 sync. On 2026-04-21 a single-pass --delete with an --exclude "*.html" filter treated every HTML file already in the bucket as “not in source” and deleted them — index.html, 404.html, the lot. The site root just evaporated. The fix is now a comment block carved directly into the CI file, explaining exactly why the order matters, and it’s duplicated into a second deploy job so nobody re-introduces it. That post-mortem-in-a-comment is itself a documentation artifact I read every time I touch the pipeline. (The blog’s full plumbing is in how this blog is built.)

The throughline: redundant and dead systems don’t show up in diffs, because their defining feature is that nothing is changing them. They show up when you read a description of the whole system and notice a box that shouldn’t be there. Agents are good at generating that description; I’m good at noticing the wrong box. That division of labor is the actual product.

Why the diagrams earn their keep

Visualizing data flow is the single highest-leverage thing in the stack, and it’s the thing I’m worst at maintaining by hand. A request-path diagram that’s current is worth more than a thousand lines of correct-but-unread YAML. When the auth-flow SVG and the storage-tier SVG sit next to each other, you can see a dependency you’d never notice spelunking through manifests one file at a time. The diagrams are generated from the system, so they don’t drift the way a hand-drawn diagram rots the moment you change an ingress.

I run the generation the same way I run everything else — point Claude at it, let it write the generator, read the output. The agents even document their own automation: there’s a harness that reviews merge requests, diagnoses failed pipelines, and proposes fixes on its own, and it has a doc explaining itself. I wrote about that machinery in LLM-powered GitLab CI. The autonomous jobs post findings and open follow-up MRs without waiting on me; I gate on the user-facing stuff and let the internal stuff flow.

The honest caveats

This works because of specific conditions, and it would be malpractice without them:

  • Blast radius is internal. Nobody else’s data is on the line. The moment something is customer-facing, stateful without backups, or security-exposed, the diff goes back under the microscope. “Don’t read the PR” is a privilege the blast radius grants me, not a universal stance.
  • Backups and reproducibility are load-bearing. I can skip review because I can recover. Take away the backups or the infra-as-code and the whole posture collapses.
  • Documentation can be confidently wrong. Agents hallucinate. A doc that describes a system as the agent imagined it rather than as it is is worse than no doc, because it reads authoritative. I treat every generated doc as a claim to spot-check against reality, not as ground truth — the dead-service catch only worked because something compared docs to the live cluster.
  • You’re trading one review burden for another. I don’t read diffs, but I do read a lot of prose, and curating which docs are worth reading is its own skill. This isn’t less work. It’s work pointed somewhere higher-signal.
  • It rewards the lazy failure mode. It is genuinely tempting to read the nice diagram, feel informed, and never verify. The diagram is a hypothesis about your system, not a measurement of it.

Lessons

  • Make the agent the writer and yourself the reader. Produce abundantly, consume selectively. It scales where “review everything” doesn’t.
  • Redundant and dead systems hide from diffs. They surface when you read a description of the whole and notice what shouldn’t be there.
  • Generate diagrams from the system, not by hand. A current data-flow picture is the highest-leverage artifact you can have, and the only way to keep it current is to generate it.
  • The escape hatch is recoverability. Skipping review is only sane when a mistake costs an evening, not a customer. Know which side of that line you’re on before you let go of the wheel.
  • Treat docs as claims, not truth. The value shows up when something checks the generated description against the running reality.

No homelab to let an agent loose on? You can practice this pattern safely on a throwaway DigitalOcean droplet or a managed Kubernetes cluster — somewhere a bad change costs you a terraform destroy and nothing more. The whole approach hinges on the downside being cheap; rent a cheap downside and you can learn the workflow without risking anything you care about.