Prose is advisory, guardrails are mechanical

Abstract

Coding agents follow written instructions most of the time. Unfortunately, their exceptions tend to occur where mistakes cost the most. An agency shipping client work cannot build its operating model around "most of the time".

This is what I learned from building an engineering harness for headless commerce work. Vendor knowledge stays upstream and gets composed at pinned versions. House opinion lives in skills. Any rule that must hold is enforced through hooks, continuous integration or platform permissions, where an agent cannot simply overlook it. Every skill ends on a named check that either passes or fails.

Client projects are allowed to diverge, but the divergence is declared and reviewable. Useful components only move back into the shared layer after held-out evaluation. Eleven weeks into the work I also deleted one of the harness's two target variants, along with the abstraction built to support it. That result is less tidy than a method paper usually allows, and much more useful.

1. Introduction

We mostly steer coding agents with documents: CLAUDE.md, AGENTS.md, style guides and system prompts. All of them are advisory. The agent reads a rule, weighs it against the rest of its context and follows it with a reliability that varies with phrasing, context length and a little luck. On a personal project, the result may be a bad commit. At an agency, the same agent can touch several clients' repositories, stores and production infrastructure. A lapse can mutate a live storefront, put a secret into a tracked file or leave a client with code that quietly breaks their conventions.

I treated this as an enforcement problem. The useful rule from operating systems and organisations is simple enough: put each constraint at the cheapest layer that can actually hold it. A preference about code can stay in prose. A safety rule cannot.

The word "harness" follows the usage that emerged in mid-2026: the system surrounding a model that decides how it plans, acts, perceives context, stores artefacts, and evaluates results. Weng frames harness engineering as building operating systems rather than prompt templates, and observes that agents rarely address maintainability or ownership boundaries on their own. OpenAI's account of running large codebases agent-first reaches a similar place from the other direction: versioned context files pointing at deeper sources of truth, with background processes checking them. My setting is a client-services agency. It adds two awkward constraints: one house standard has to work across many repositories, and the client must own everything when the engagement ends.

What I would keep

1. Assign each rule to the lowest layer that can enforce it, from prose and review agents down through hooks, CI and platform permissions.
2. Never let a skill finish on "looks right". Give it a check that passes or fails.
3. Let client projects diverge in the open. Promote useful work back into the shared layer only after it passes an evaluation it was not written against.
4. Delete abstractions when their daily cost outweighs the optionality they preserve. The second harness variant proved that one the mildly painful way.

2. The problem shape

Agency work differs from product work in three practical ways.

There is one team and there are many client repositories. The house standard has to survive across all of them without being copied into each one. A copied standard is a fork, and forks have a habit of drifting quietly out of date.

There is also an exit test. On the day an engagement ends, the client should hold everything that matters in open formats and repositories they own. A harness component that only works while the agency operates it fails that test, however handy it was along the way.

Finally, platform vendors now publish agent-facing knowledge themselves. The commerce platform ships skills for its framework and the hosting platform does the same for its ecosystem. In one five-day window, the framework vendor's skill count changed twice. Re-teaching an agent the vendor's own framework would be wasteful and an impressive maintenance nuisance. The harness composes that knowledge at pinned versions, then adds house opinion on top.

3. The harness

3.1 Layers

The harness is organised as a stack, from the client project down to vendor ground truth. A client repository holds project context, a design-system contract, and its own local skills. Beneath it sit the agency's plugins: a core plugin carrying stack-agnostic standards (code and git conventions, accessibility and performance budgets, review and audit agents, the guard hooks), and a stack plugin carrying opinions for the specific target (architecture, content modelling, deployment conventions), which itself declares pinned dependencies on the vendors' own skills. Knowledge flows down through composition, and nothing is forked upward.

Two details matter more than the layer diagram. All knowledge is plain markdown in an open convention, so a client moving to another agent platform loses some enforcement but keeps the knowledge. Precedence also follows the platform's own resolution rules. A client repository can override a house opinion, and the override remains visible in the repository instead of disappearing into a conversation.

3.2 The enforcement ladder

Every rule is assigned to the lowest rung that actually holds it:

The design assumes an agent that is occasionally and unpredictably wrong, with a cost of wrongness that varies enormously by surface. Style belongs at rung 1. "Never write secrets into tracked files" belongs at rung 3, where a hook denies the write before it happens. "Never mutate a live store without an explicit staging-pinned opt-in" belongs at rung 3 and rung 5, because an agent-side guard is convenience and the platform token is the guarantee. Trust the platform layer most, and make daft behaviour non-fatal.

Review agents sit at rung 2, below hooks. A read-only reviewer is useful, but it catches mistakes after the fact. Where a rule can be expressed as a matcher over tool calls, the harness prevents the mistake.

3.3 Named checks

Every skill ends on a named check: theme validation, schema validation against the real API, a smoke test or a budget assertion. The platform vendors already put forced validation loops into their skills; I turned that into a house rule. No skill finishes on "looks right". Each piece of agent work becomes falsifiable, while the growing library of checks becomes the harness's own regression surface.

3.4 Divergence and harvest

Left alone, N client projects will produce N versions of the harness. The layering makes room for that divergence, but each client-local component must declare what it is: an override (which must pin the exact upstream it shadows, plus a one-line rationale), an extension (client-specific, no upstream counterpart), or a candidate (built on engagement, looks generalisable). Undeclared shadowing is a lint failure, because the agent platform silently resolves project skills over plugin skills by name, and an accidental name collision could invisibly disable a guardrail.

Candidates flow back through a harvest loop: generalised, stripped of client specifics, and promoted into the shared layer. Promotion is eval-gated: a candidate lands in a plugin only after passing that plugin's evaluation suite, and the suite is held out from the component being promoted, so promotion cannot regress behaviour that other clients inherit. This is the same regression discipline that self-improvement frameworks apply to harness edits, run at human speed with human review.

The shared component registry handles distribution through an open specification. Client repositories install harvested components as source, so they retain custody of the result. The registry records provenance and distributes files; it is never a runtime dependency. At the time of writing it carries 69 items.

4. A negative result: deleting a variant

The harness began with two target stacks: the headless framework and the platform's native theme language, with a variant abstraction keeping the two pure per repository (cross-stack standards are actively wrong, not merely untidy). Eleven weeks in, the second variant was deleted, along with the abstraction itself: the manifest field, the guard, the lint checks. The reasoning was not that the second stack lacked value. The abstraction had a real daily cost in every layer it touched, and the strategic direction had consolidated on one stack. A future engagement on the other stack can fork the repository and rebuild the guard. Current engagements no longer pay every day for optionality they do not use.

Architecture accounts tend to make every decision look inevitable in retrospect. This one was wrong about a major assumption for eleven weeks. The fix was deletion, which the layering absorbed cleanly because variant opinion lived in one place. Core standards, guards and the client contract were left alone.

5. Related work

Weng's harness-engineering essay supplies the framing and several of the bottlenecks this design answers directly, particularly evaluators isolated from what they evaluate, and file-systems-as-memory. OpenAI's account of agent-first development at scale converges on versioned, repository-rooted context with automated freshness, which the harness adopts as its documentation plane. The vendor ecosystems supply the ground-truth layer this harness deliberately composes rather than reproduces. The registry mechanism builds on an open component-registry specification from the UI tooling ecosystem, repurposed as a provenance channel for harvested components. The agency-specific additions are declared divergence with eval-gated harvest, plus an enforcement ladder that ends with platform permissions.

6. Limitations

The field results are one agency, one stack, a three-run proof sequence, and guard coverage verified against a test repository rather than a statistical sample of live engagements. The eval suites that gate harvest are young, and their coverage grows engagement by engagement, so a promoted component is only as protected as the checks that exist at promotion time. Enforcement below rung 5 is specific to one agent platform's hook and permission model. On another platform the knowledge ports but the teeth do not, and CI becomes the lowest hard rung. Nothing here measures whether the harness makes agents better. It limits the damage when they fail and gives their output a testable finish line.

7. Conclusion

Prose is advisory; guardrails are mechanical. For agency work, that means composing vendor knowledge, ending skills on named checks and keeping client divergence visible. Shared improvements have to pass held-out evaluation, and the final enforcement layer should sit somewhere the agent cannot reach.

None of this is especially new. Agencies have always needed enforceable standards, client-owned deliverables and a reliable way to tell whether work is finished. Agents have simply made the absence of those things expensive much faster.

References

• Weng, L. "Harness Engineering for Self-Improvement" (July 2026). lilianweng.github.io/posts/2026-07-04-harness/
• OpenAI. "Harness engineering: leveraging Codex in an agent-first world" (February 2026). openai.com/index/harness-engineering/
• The shadcn registry specification, the open component-registry format the distribution layer builds on. ui.shadcn.com/docs/registry

Appendix: the harness at a glance