Building a Personal AI Harness: A Guide for Software Architects

An AI Harness Is Not a Better Prompt

It's tempting to think better results come from a cleverer prompt. In practice, the biggest performance gap isn't between models — it's between a model running with no scaffolding and the same model running inside a proper harness. Anthropic's own engineering team has described the harness as the infrastructure around the model that manages context, tools, memory, and execution flow: the thing that curates what the model sees, decides what it's allowed to touch, and keeps it oriented across a task too long to fit in one context window.

A useful mental model: the model is the engine, the harness is the car. A powerful engine bolted to nothing still doesn't get you anywhere. The harness is the chassis, the fuel system, the steering — the part that turns raw capability into work you can actually rely on.

Why This Is an Architect's Problem, Not Just a Developer's

Most AI-coding advice is written for someone working inside a single repository on a single feature. An architect's context is wider and messier: decisions live across several repos, in Confluence pages, in Slack threads, and in the heads of people who've since moved teams. A generic coding agent that reads one package.json and starts editing is the wrong shape of tool for "should this service be active-active or active-passive, given what we decided about the payments system eighteen months ago."

That's exactly the gap a personal harness closes. It's not about writing code faster — it's about giving an agent enough standing context, the right narrow tools, and a place to leave its work, so it can reliably do the parts of your job that are repetitive but require judgment: drafting an ADR from a discussion, reviewing a design doc against your team's standards, or turning a whiteboard sketch into a proper C4 diagram.

The Four Layers Every Harness Needs

Regardless of which vendor's agent you're driving, a harness that holds up on real work has the same four layers.

Context. A standing file the agent reads automatically at the start of every session — your architectural principles, the systems you own, the decisions that are settled and shouldn't be re-litigated, and the tone you want ("flag tradeoffs, don't just agree with me").

Tools. A narrow, explicit set of things the agent can do — read specific repos, query a specific API, generate a diagram — rather than blanket access to everything. The tighter the tool set, the more predictable the output.

Memory. Somewhere the agent's work persists between sessions: a progress log, a decisions folder, a running feature or task list. Anthropic's research on long-running agents found that without this, an agent restarting in a fresh context window either tries to redo finished work or wrongly declares an unfinished task complete — the fix was a written progress file plus git history the next session reads before doing anything else.

Verification. A step where the agent's output gets checked before you trust it — tests for code, a checklist for a document, a second pass that compares the draft against your standards file. Skipping this is the single most common way harnesses go wrong: the agent sounds confident and is quietly incomplete.

Building It With Claude: CLAUDE.md, Skills, and Subagents

Claude Code and the underlying Claude Agent SDK expose the harness as something you can configure directly. Start with a CLAUDE.md at the root of your standards repo — not a project's build instructions, but your architectural context: the systems you're accountable for, non-negotiable constraints (data residency, latency budgets, approved vendors), and the questions you want it to always ask before proposing a design.

Layer on Skills for anything you do repeatedly. A skill is a folder with a SKILL.md file — a short description of when to use it plus the instructions to follow — and optionally scripts or reference files it can pull in only when needed. An "ADR writer" skill that knows your team's template, a "multi-region review" skill that checklist-walks a design against your failover standards, a "diagram generator" skill that turns a description into a Mermaid or C4 diagram in your house style — each becomes something you invoke instead of re-explaining from scratch.

For heavier work, subagents let you delegate a broad exploration — "read every service's deployment config and summarize which ones violate our region-pinning rule" — to a separate context that reports back a conclusion instead of flooding your main conversation with raw file contents.

Building It With GitHub Copilot: Instructions, Skills, and Custom Agents

Copilot's harness is split into three deliberately separate pieces, and keeping them separate is what makes it maintainable. Repository and organization-level custom instructions (.github/copilot-instructions.md, or an AGENTS.md the coding agent also reads) tell Copilot how your repos work in general — build commands, conventions, things never to touch. Skills teach it a specific repeatable workflow that loads in just when relevant, the same idea as Claude's Skills. Custom agents go a step further and define a specialist persona with its own tools and operating style — worth setting up if "architecture reviewer" is a hat you put on often enough that it deserves its own agent rather than a one-off prompt every time.

As of 2026, Copilot also supports agent-specific instructions, so you can scope a rule ("always flag cross-region data transfers") to only the review agent without it leaking into the general coding agent's behavior.

Building It With OpenAI Codex: AGENTS.md Done Right

Codex reads an AGENTS.md file before it touches anything, and the format has since been adopted widely enough — Cursor, Cline, Windsurf, and Gemini CLI all read the same file — that it's now stewarded as an open, vendor-neutral spec. The evidence from large-scale analysis of these files is consistent: shorter is better. Aim for 20 to 30 lines of concrete, specific rules rather than a long essay; Codex enforces a hard size cap and silently truncates anything beyond it, and models in practice spend less time parsing a short file and more time on the actual task.

For an architect, that discipline is useful beyond Codex itself — it's a forcing function to distill your standards down to the handful of rules that actually change what an agent does, rather than a document that reads well but doesn't steer behavior.

A Reference Layout You Can Copy

A minimal but complete personal harness, usable from Claude, Copilot, or Codex with small adjustments, looks roughly like this:

/standards — a repo just for you, containing:

CLAUDE.md or AGENTS.md — your architectural principles and settled decisions, kept under 30 lines of dense rules rather than prose.
/decisions — one file per ADR, so any agent can be pointed at "read our last five decisions before proposing anything."
/skills/adr-writer, /skills/design-review, /skills/diagram-generator — one folder per repeatable workflow, each with its own short instructions.
progress.md — a running log so a session that starts fresh next week doesn't have to guess what the last one concluded.

The specific file names shift between tools, but the shape doesn't. Build the layout once, in your own repo, and you can point any of the three at it.

What Not to Automate

A harness makes an agent more capable, not more trustworthy by default — treat the two as separate problems. Keep irreversible actions (merging to a protected branch, deleting infrastructure, sending a decision externally) outside what the agent can do unsupervised, no matter how good its harness is. Design tradeoffs with real organizational cost — the kind you'd want a second architect's eyes on — are a place to use the agent to accelerate your thinking, not to replace the review. The harness should make you faster at the parts of the job that are repetitive; it shouldn't quietly become the one making the calls only you're accountable for.