Stop searching. Start asking.

01 · Co-engineer, not code generator

Claude as co-engineer.

Two beats matter here: the workflow, and who brings what.

Claude executes. I stay in the loop.

I describe a confirmed change in plain English. Claude executes it via tools: SSH into a Proxmox host, edit a config, query Home Assistant, fetch a secret from 1Password. I review every diff before it is committed. Claude does the typing. The judgment stays with me. There is no autonomous mode, no agent churning in the background. Every commit is something I understood at the moment it went in.

The architectural mindset is the actual unlock.

My day job is product architecture. For fifteen years I have shaped how systems fit together: boundaries, separated concerns, what to specify versus leave open, failure modes anticipated before code exists. Claude is fluent in the syntax of every tool on this page. What it cannot do is decide the right boundaries between my systems, which failure modes are acceptable for my family, or how the pieces stay comprehensible six months from now. I bring the shape. Claude brings execution and a catalog of options I would never find alone.

The shaping never stops.

The active work, asking questions, pushing back, proposing approaches the model did not surface, is what separates "I used Claude to do this" from "Claude built this for me." If you sit back and let the AI run, you get the median outcome. Driving is the work. If you have ever asked "wait, what are the boundaries here?", you already have the most important skill for working with AI on infrastructure.

02 · The project brain

CLAUDE.md is the brain.

CLAUDE.md is the first file Claude reads at the start of every conversation: the difference between a smart AI giving a generic answer and a co-engineer who already knows your network. Mine is around 240 lines. It contains:

• Personas and family roles: who uses what and what tradeoffs matter to them (no names on this page).
• Core principles: local-first, no monthly fees, reliability over cleverness, WAF (the spouse-acceptance factor).
• Critical safety rules: operational footguns the AI must respect unprompted.
• Credential handling: how secrets move between 1Password, the macOS Keychain, and deploy scripts. What is allowed where.
• Access matrix: every host, the SSH alias, the user, how privileged ops work.
• File index: every doc in the repo with a one-line description of what is in it.
• Workflows: change protocol, deployment patterns, when to update docs.
• Spec discipline: how plans get written and reviewed before anything runs.
• Planning conventions: how I override the default Claude workflow for this project.
• Domain routing: "IP question? Check devices.md. Camera question? smarthome.md."

That list looks like a knowledge dump. Most of it is. But the safety rules are not suggestions. They are the things I have already been burned on, written down so Claude does not repeat them. The domain routing is not filler either: when Claude sees a VLAN question, it goes to vlans.md without being asked, because the file says so. Some of it is context, some of it is policy, and the policy parts are where it actually changes how Claude behaves.

A small excerpt, to give you the shape:

## Core Principles (apply to all advice)
1. Local-first / privacy — video and automations stay on the network. No cloud.
2. Reliability over cleverness — wired PoE beats Wi-Fi; proven beats bleeding-edge.
3. No monthly fees — zero-subscription is a hard constraint, not a preference.
4. WAF — clean installs, no visible wires, usable by the family without a manual.

## File Index
| File           | Contents                                          |
| :------------- | :------------------------------------------------ |
| CLAUDE.md      | This file — context, personas, protocols          |
| CHANGELOG.md   | Running log of every physical and config change   |
| network.md     | Physical topology, switches, ports, QoS           |
| vlans.md       | VLAN IDs, subnets, isolation rules                |
| firewall.md    | Firewall rules, DNS blocks, inter-VLAN policy     |
| devices.md     | All hardware — nodes, APs, NVR, UPS               |
| smarthome.md   | Home Assistant, cameras, integrations             |
| access.md      | SSH / sudo / secrets patterns                     |

## Domain knowledge — where to look
| Question                            | File           |
| :---------------------------------- | :------------- |
| IP address of a device              | devices.md     |
| Which VLAN a device is on           | vlans.md       |
| Switch port assignment              | network.md     |
| "X seems broken" — first look | diagnostics.md |

The file does more than describe the house. It tells Claude how to work in it.

03 · The source of truth

Living documentation.

This is the part I would most want someone to copy. It compounds the value of every other practice on this page. Every domain has one canonical file. No information lives in two places: if a device IP shows up in two files, one is the source of truth and the other is wrong.

The protocol: surgical edits, immediate on confirmation.

Change only the specific items affected. Never rewrite sections. Update immediately when a value lands (IP, port, VM ID, endpoint), before advancing. Never hold a confirmed value only in conversation context. And no doc updates during brainstorming: speculation stays in chat, docs change only when a real-world thing has changed.

Three views of the same truth.

Every confirmed change produces a dated CHANGELOG.md entry listing every file touched, landing with the git commit. Any one of these reconstructs what happened: the git history, the changelog, or the doc files themselves. They do not contradict.

The docs live in a private GitHub repo, which means:

• They travel with me. Work laptop, gaming PC, phone: same docs, no sync ceremony.
• Claude in other projects can read them. Point Claude at the repo URL and pull live docs as reference. No copy-paste, no drift.
• The house could burn down and the rebuild plan would still exist. Hardware is replaceable. The documented state is not.

The loop.

Every change, no exceptions. Tedious for the first week. Compounding from week two onward: every session opens with full context, and the system gets smarter as it grows instead of harder to maintain.

All of this is a public repo, too. Real docs from this house, sanitized, plus blank versions to start your own. More in the Starter Pack below ↓

04 · Spec-driven configuration

Spec it before you run it.

Single-model improvising works fine for small, reversible changes. It falls apart on multi-step infra projects where one mis-ordered command costs you a recovery weekend. The answer is to spec the project before any command runs.

The structure.

Plans live under docs/superpowers/plans/<date-project-name>/: a 30-line README that maps the phases, then one phase file per session, around 300 lines each. One phase, one session, one validation gate at the boundary. Specs live in a sibling directory and end with a Pre-Approval Verification section, where every concrete reference (a version, a file:line, an IP, a port) is verified live against the running infrastructure during the writing pass. Not from memory. Catching drift at write time costs one command. Catching it post-deploy costs hours.

Dual-Opus adversarial review.

Once a spec is drafted, I open a second Opus session and have it read the spec cold, prompted to find failure modes rather than validate the plan. It catches things the first one rationalized past. The merge of both passes becomes the approved spec.

Task tagging.

Inside each phase file, every task gets one tag:

• DIRECT  execute in the main conversation. The default: SSH, config edits, doc updates, commits.
• SUBAGENT  dispatch a subagent. Only when a task makes significant verification chatter or a logic-bearing artifact worth its own review.
• HANDOFF  I do it. Physical actions, Touch ID, browser UI, anything outside Claude's reach.

Pre-deciding who executes each step removes a whole class of mid-execution confusion.

Validation gates.

Phases do not close until their gates ratify. Gates are objective: this command returns this value, this service responds on this port, this metric stays under X for 48 hours. If the gate does not pass, I do not move on. The closure is binary.

A deliberate override of the off-the-shelf workflow.

The default "superpowers" workflow produces one monolithic plan file and expects subagents for most execution. That broke down at homelab scale: a multi-day plan in one file is unreadable, blows past a session's context window, and an LXC rebuild does not want a subagent (the verification overhead is higher than the work). So I rewired it, documented in CLAUDE.md: a 30-line README nav plus per-phase files of ~300 lines, every task tagged with where it runs, one phase as one session. Same discipline, shaped for the actual constraint.

05 · Capability-bounded AI

Secrets and boundaries.

The fastest way to derail a homelab project is to give the AI too much access or too little. Both have the same symptom: you stop trusting the work. I solve it with hard boundaries the AI cannot widen on its own. I use 1Password with two paths into it:

SSH discipline.

Bare SSH aliases only, no raw IPs. The alias picks up the user, the key, and the connection multiplexer in one go. The agent is the 1Password agent: every signing operation prompts for Touch ID, with multiplexing batching commands inside a 10-minute window. Private key text never leaves the agent process.

Tell the AI what it cannot do.

The Home Assistant MCP integration is deliberately non-admin: a dedicated read-only user, twenty-plus deny rules blocking every write tool, service call, and entity update. Claude can read HA and that is the full extent of it. To change something, the change goes through the same workflow as everything else: edit a YAML file in git, run the deploy script, watch the reload. The MCP is not a control plane. It is a sensor. Capability-bounded AI is more useful than fully-capable AI, because I never have to wonder whether a session has gone sideways and started silently rewriting or turning things on or off in my house.

06 · Continuity

Memory that compounds.

Claude has a persistent memory system. Used well, every future session starts smarter than the last. Used badly, it accumulates noise. Four types:

The triage rule.

Memory persists only what future sessions need that they cannot reconstruct from files. Preferences. Project facts. External references. Not in-progress work, not derivable patterns, not anything already in the docs. The docs are the system. Memory is the meta: the things about how I work with the system that the system itself does not know.

The compounding effect.

Most workflows get harder as projects accumulate. This one gets easier. Every project starts with a more thoroughly documented base, every memory entry refines how Claude collaborates with me, every CHANGELOG entry is one more bit of recall the next session opens with. The more I build, the less I have to re-explain. I have done all of this on the $20/month Claude Pro plan, because the context layer does the work the tokens would otherwise have to.

07 · The real unlock

Context is the product.

The reason this works is not that Claude is smart. Claude is smart in a generic, internet-shaped way. What is specific is the context layer about my situation loaded on every session: my network, my hardware, my constraints, my family, my workflows, my past decisions and why I made them. The methodology in Part One is how that context layer gets built and kept honest. Everything in Part Two is what it makes possible. The mindset shift is small and load-bearing:

The first gets you a Reddit thread and a five-hour rabbit hole. The second gets you a deployment plan that fits your actual constraints. Three worked examples, two homelab, one from outside the genre to show this generalizes.

Same lesson every time. The methodology in Part One is how you build the context layer. The rest of Part Two is what that layer makes possible at home.

09 · Hardware

Hardware and physical architecture

Two-rack layout, primary up top, secondary below. The top rack carries the networking backbone: switches, patch panels, and the NVR. The bottom rack holds the two compute nodes, the UPS, and a tool drawer.

I had Claude help me research what to buy, how to install, and where to logically place (and place again... many times as I kept adding devices) everything.

▸ Compute

Two nodes, two purposes.

▸ Power

Always on.

▸ Storage

Three paths.

▸ Surveillance

Cameras, kept local.

10 · Network and VLANs

One tree, four VLANs.

The topology is a tree. The ISP feeds the router, the router feeds the core switch, and the core switch feeds every branch in the house.

▸ Segmentation

Four VLANs.

VLAN A is the architectural answer to "I want a smart thing but I don't want it phoning home." The device works locally with HA and is cut off from the internet entirely. That is the rule, not the exception.

HA dual-home.

Home Assistant runs as a single VM but sits on two VLANs at once, management plus IoT, via a tagged virtual interface. The router-on-a-stick pattern applied to a hypervisor guest. It lets HA see local broadcast traffic (mDNS, SSDP) on both networks natively without weakening segmentation. No cross-VLAN reflector to maintain. HA is just on both segments.

Inter-VLAN policy at the firewall.

L3 enforcement happens on the router. Cameras cannot initiate outbound except to the few explicitly allowed endpoints. IoT devices cannot initiate outbound at all. The guest VLAN, when used, is fully isolated. The default for new things is closed.

Remote access via VPN, not exposed services.

Nothing on the homelab is publicly reachable. To hit HA, Frigate, or the reverse proxy from outside, I connect through WireGuard on the router and land inside the home network on my own VPN subnet. Internal hostnames resolve via the home AdGuard instances over the tunnel, and the wildcard TLS cert still validates (issued via DNS-01 against a Cloudflare-hosted apex, no public port exposure). Four devices have WireGuard profiles. Zero services on the public internet. Full remote access whenever I want it.

11 · Software stack

What runs on it.

12 · What this unlocks

A foundation, not a finish line.

The hard part is done. VLAN segmentation, a hypervisor on each node, dual-home networking, local AI hardware, and a living documentation system mean every future project plugs into a foundation instead of starting from scratch.

13 · The journey

Five months of confirmed changes.

Five months ago I hadn’t done literally any of this. I didn’t even know what Proxmox or Home Assistant were. I’d heard of Docker, knew people did “homelab” stuff, but had zero real exposure to any of it. I’ve completely replaced my 1–2 hours of gaming every night (a 20-plus-year habit, we can fairly call it an addiction) with learning and building in my homelab with Claude. Every item below was the first time I did it.

14 · The starter pack

Build your own version.

The prompt isn’t the magic. The context you build is.

You can copy the prompt below verbatim and get a head start. But the prompt is the spark, not the engine. The engine is the documentation system you build with Claude on the other side of that first conversation. Treat the prompt as the seed.

I want to start working with you the way a product architect collaborates
with an engineering team - I describe what I want, you do the execution
via tools, I review every change before it gets committed. (If you don't
have tool access in this conversation, help me plan it and I'll run things
myself.)

Before we do anything, help me set up the foundation. Here's my context:

ROLE: [your job / how technical you are / how you learn best]

SCOPE: [the one system you're going to document and operate together -
        home network, a single server, a codebase, etc.]

GOALS: [what you want this system to do well over the next 6 months]

CONSTRAINTS: [budget, time, family/WAF, anything you won't compromise on,
              anything you can't change]

WHAT EXISTS TODAY: [hardware you own, services that run, accounts you use,
                    how it's currently set up - rough is fine]

WHAT I WANT HELP WITH FIRST: [the thing that pushed me to do this today]

Start by asking me at least five questions about my context, goals, or
constraints that would change your recommendation. Push on things I
haven't told you. Assume I don't know what I don't know - the questions
are how I find out what I should be thinking about. In your first reply,
only ask the questions. Don't propose anything yet.

Once I've answered, propose three things:
  1. A CLAUDE.md skeleton - section headings + one-line descriptions of
     what goes in each, tailored to my context.
  2. A starting file index - which living docs make sense for my scope.
  3. Five "critical safety rules" relevant to my context - operational
     footguns you'd want to be warned about unprompted in future sessions.

Don't write the full files yet. Show me the structure first. We'll iterate
before anything gets created.