Architecture-Powered Claude Engineering: The Judgment Under the Toolkit
Everyone's racing to write a CLAUDE.md and a folder of skills. But those files are containers — what goes in them is architectural judgment, and if the judgment is wrong, you've just automated a mistake five times faster. I built a five-service event-driven job board with Claude Code, and the .claude/ toolkit isn't the achievement. The architecture that authored it is. Hand the same tools to someone without that experience, and you get a plausible alpha. With it, you get something you'd actually push.
There's a lot of excitement right now about moving AI discipline into the repository — CLAUDE.md files, rules, skills, subagents, hooks. I'm all for it; I do it, and I'll show you exactly how below. But there's a quiet assumption underneath the excitement that's worth dragging into the light: that the toolkit is the hard part. It isn't. Writing a rule that says "no shared database" takes thirty seconds. Knowing that rule is load-bearing — knowing the eleven other boundaries that matter, in what order to prove them, and what breaks in production if you get one wrong — is the work of years. The file is easy. The judgment inside it is not.
That's the whole thesis of this post, and the reason I frame what I do as Architecture-Powered Claude Engineering rather than just Claude engineering. The public proof is at github.com/architect4hire/jobboard: a genuinely functional job board built as five bounded .NET services behind one gateway, an Angular front end, an event bus, all orchestrated locally by Aspire, driven agentically with Claude Code. The .claude/ toolkit that drives it is real, and it's good. But it's downstream. It's architectural experience compiled into a form an agent can execute — and it's only as good as the architecture it encodes.
The tool is neutral. The judgment is not.
Here's the uncomfortable part for anyone selling "just add a CLAUDE.md and go."
Claude Code will happily encode a bad architecture as faithfully as a good one. Ask it to build a job board with no guardrails, and it produces plausible code — code that compiles, demos, and looks right in the diff. Plausible is not correct. In a distributed system, plausible-but-wrong is where the money leaks out: the agent helpfully opens a second database connection to grab data it needs, and now two services share a table, and you have a distributed monolith wearing a microservices costume. It passes review if the reviewer doesn't know what they're looking at. I call this the Plausibility Trap, and no amount of tooling closes it — because the tool has no opinion about whether your boundaries are right. It just executes.
So the interesting question was never can Claude Code build a microservice system. It's: can it build one that behaves correctly when things go wrong, without the architecture drifting — and the answer to that lives entirely in the judgment you feed it. That's the experience I'm actually selling. Not "I know how to write a rules file." Anyone can. I know which rules are worth writing, because I've watched the alternatives fail in production. As my application-development service puts it: I don't just draw the architecture — I build in it, so the design and the code never drift apart. This is how I build the toolkit now. The architecture is why the toolkit is right.
Trace one decision, and you'll see where the value is
Take the single most important rule in the whole repo: no shared database, ever. A service reads and writes only its own database. Watch where that rule actually comes from, because the origin is the point.
It does not start in the .claude/ folder. It starts as a decision, reasoned out in the High-Level Design and recorded in an Architecture Decision Record — ADR-0001, database-per-service — with its context, its consequences, and the alternatives I rejected and why. That ADR exists because I've lived the failure it prevents: two services quietly coupled through a shared table, evolving independently right up until the day one migration takes them both down. The judgment is: pay the cost of duplicating a little reference data now, or pay for a rewrite later. That's not a preference. It's a scar.
Only then does it become tooling. The decision becomes a rule that the agent loads when it touches a service. It turns into a subagent that reviews for the violation. It turns into a compiler-enforced reference graph — the project references are one-way and acyclic, Contracts ← Shared ← Service.Core ← Service host ← AppHost, so a service reaching sideways into another is a build error, not a code-review conversation. I checked the repo: no service's .Core references another's. Not because everyone remembered to be careful — because the architecture made carelessness impossible.
That's the chain that matters: experience → decision → record → guardrail → enforcement. The .claude/ folder is the last two links. The first three are the architect. Remove the architect and the chain still runs — it just encodes whatever plausible thing the agent invented, and enforces that with the same mechanical rigor. You'd get a beautifully automated, ruthlessly consistent mistake.
The toolkit is architecture, encoded four ways
With that framing, here's what's in the .claude/ folder — and notice that every layer is a decision an experienced architect made, not a clever use of a feature.
Rules are the conventions the agent should know, and they're path-scoped so they load exactly when relevant — five of them (aspire.md, backend.md, frontend.md, gateway.md, messaging.md). Touch a service, the layered-architecture rules load; touch the bus, the outbox-and-idempotency rules load. But the layered architecture those rules describe — thin host plus a .Core library, facade → business → data → repository, ViewModel in and ServiceModel out — is ADR-0005's judgment. The rule is just its enforcement. A different architect's rules file would describe a different architecture, and the agent would obey it just as well. The rule is only as good as the layering it encodes.
Skills are procedures the agent should follow when a task matches — and the crown jewel, add-endpoint, encodes the single most error-prone operation in this architecture. Adding a REST endpoint here is a lot of correct steps in a specific order: pick the owning service, build the full controller → facade → business → data → repository slice, enqueue the integration event on the outbox atomically in the same transaction as the write, add the gateway route, wire the DI, write the tests. That ordering is architectural knowledge. The skill fires and the agent does it right every time — but only because someone who knew the right way wrote the skill. Hand the same skill mechanism to someone who thinks a fat controller is fine, and it'll reproduce a fat controller with perfect consistency.
Subagents are work to delegate, and I keep all three strictly read-only on purpose — code-reviewer, test-gap-analyzer, api-contract-checker. They report; they never touch code. And what they hunt for is not generic — it's the specific mistakes this architecture is prone to. The test-gap analyzer flags a consumer with no idempotency test, because at-least-once delivery means that callback will fire twice and a handler that isn't safe to run twice is a latent double-effect bug. Knowing that's the test that matters is the judgment. The subagent is just where I parked it.
Hooks are the non-negotiables — the things that happen whether the agent decides to or not — and there are two. secret-guard.sh runs before every edit and physically blocks anything credential-shaped from being written, no matter how I prompt or how tired I am. format.sh formats every touched file after the fact. Rules ask. Hooks enforce. Deciding which invariants deserve a hook instead of a rule — which things must be true versus merely encouraged — is, again, an architectural call.
Rules teach, skills guide, subagents check, hooks enforce. Four ways to encode a decision. But the encoding is the easy 20%. The decisions are the 80% you're hiring an architect for.
SCRUB: how I serialize judgment into something an agent can run
The connective tissue is a discipline I've used for months: SCRUB — Scope, Constraints, Restrictions, Usage, Behavior. It started as a way to write a good prompt. What it really is, I've come to understand, is a format for transferring architectural judgment into an executable form. Scope names what's in and out of bounds. Constraints pin the stack and conventions. Restrictions are the hard do-NOTs. Usage points at the right tool. Behavior demands a plan before any change.
The JobBoard's CLAUDE.md — the constitution loaded every session — is itself written as a SCRUB prompt, because the constitution is architecture. Its Scope declares that adding a service is an architectural decision, not a feature: "propose it, don't scaffold it." Its Restrictions are the load-bearing rulings — no shared database, the gateway is the only public door, publish through the outbox in the same transaction, consumers are idempotent. Every one of those is a decision with an ADR behind it. SCRUB is just the grammar that lets me hand those decisions to an agent without losing their meaning, and diagnose exactly which one failed when something goes wrong.
Alpha versus polished — which is the whole pitch
Here's the contrast I most want a client to hold onto, because it's the value stated plainly.
Give Claude Code to a competent developer with no distributed-systems architecture background, and you'll get an alpha: a working, demoable job board that looks finished. Post a job, apply, watch a status change — it all works on the happy path. And it's quietly wrong at every seam. A declined payment leaves stock reserved because there's no compensation path. A redelivered message is double-processed because the consumer isn't idempotent. Two services share a table because that was the plausible way to get the data. The design and the code drift apart the day after the build ships, because nothing was recording why anything was done. It'll get to about ninety percent and stall there forever, because the last ten percent is all the correctness-under-failure work that doesn't show up in a demo.
Give an architect the same tools, and the guardrails carry the experience the developer didn't have. The outbox and idempotent inbox make it correct under partial failure — no lost events, no double effects — by design, not by luck. The acyclic references keep the boundaries safe, enforced by the compiler. The ADRs and developer docs keep the design and the code locked together so nothing drifts. That's the difference between an alpha and something you'd push: not the toolkit, which is identical in both cases, but the judgment the toolkit is carrying. The architecture is what turns "it runs" into "it's ready."
And there's a document ecosystem that keeps it that way, each link feeding the next: the design (the high level design and its C4 diagrams) reasons out the decisions; the decisions become the .claude/ guardrails; the guardrails drive Claude Code to produce the src/; the output is recorded in twelve ADRs; and the ADRs are explained to the next human in developer docs — an add-an-endpoint-by-hand walkthrough, a seed-data guide, an ongoing architecture review with a ranked risk table. Design → guardrails → code → record → explanation, kept deliberately in sync, because a design that's drifted from its code is worse than no design at all. That closed loop is the deliverable. The job board is just the proof it works.
The contrarian bit: I barely write prompts anymore
Here's what surprises people. Once the architecture is encoded, I mostly stop writing prompts. The rules auto-load, the skills carry the procedures, the subagents catch the drift, the hooks enforce the invariants — so day-to-day work needs nothing more than "add a withdraw-application endpoint," because the repository already knows what "endpoint" means here and which service owns applications.
But read that carefully, because the reason I can stop prompting is not that the tooling is clever. It's that the architecture is doing the constraining. The leverage was never the automation. It was the judgment the automation carries.
Prompt engineering optimizes the prompt; architecture-powered Claude engineering makes the prompt unnecessary — by building years of hard-won structural decisions into the repo once, so they're paid forward on every task without me re-typing a single one.
What the architecture experience buys a business
I work with two kinds of decision-makers, often in the same room. So, plainly:
- Polished, not alpha. You get the ninety-to-a-hundred percent that the correctness-under-failure work represents — the part a toolkit alone never reaches.
- Correct when it counts. Compensation on every failure path, idempotent consumers, safe boundaries — stated as outcomes: partial-order incidents at zero, double-effects at zero, oversells at zero.
- No drift. The design, the code, and the reasoning stay locked together, enforced by the compiler and the hooks, so the system six months out still matches the diagram.
- Cheap onboarding. A new engineer reads the ADRs and developer docs and is productive in an afternoon, not a month.
- You own all of it. SCRUB is a discipline, not a dependency. No proprietary framework to keep paying for. Clone it, run it, keep it.
The honest part
Let me label the scaffold as a scaffold, because I always do. JobBoard is a reference build — a spike. It runs entirely on local Aspire-orchestrated containers at zero cloud spend, talking to the real Azure Service Bus SDK through an emulator; going live is a configuration and DevOps change, not a rewrite, but it is a change I haven't made here. Two of the twelve ADRs are still marked Proposed, not Accepted — the cross-service read-model strategy is named as a pending decision, not pre-built, because pretending to have solved it would be a dishonest move.
And the standing advice in the toolkit is verify before trusting: Aspire, the Service Bus emulator, YARP, and Claude Code all ship fast, so confirm the exact API names against the live docs before you lean on them. That caveat is in the repository, in writing, because a scaffold that lies about its completeness is worse than useless.
Where this starts
If your team has adopted an AI coding assistant and it keeps producing plausible-but-wrong output — code that demos and then drifts, an architecture that erodes a little with every generated file, a build that's perpetually ninety percent — the missing piece isn't a better tool. You already have the tool. The missing piece is the architectural judgment that tells the tool what "right" is, and encodes it so it holds.
That's the work I do: architect4hire.com/services/application-development. Read the repo first — github.com/architect4hire/jobboard — and the SCRUB framework in full at architect4hire.com/scrub. Then, if it's the shape of what your team needs, reach out at robert@architect4hire.com. Fractional or contract, the first conversation is the same: what you're trying to build, and whether I'm the right person to help you build it. If I'm not, I'll tell you.
Robert Felkins is the principal architect at Architect4Hire — Chicago-based fractional and contract architecture for small and mid-sized teams. I design right-sized .NET and Azure systems, modernize the ones you already have, and bring AI-assisted development into teams in a way that survives contact with production: senior judgment without the full-time price tag. Reach me at robert@architect4hire.com.
