The Design Harness

Position this module against the previous one before going anywhere else. Module 3 was about the brief: the per-task statement of intent, constraints, and review criteria. The recurring frustration people hit after Module 3 is that their briefs keep getting longer, because they keep restating the same facts — the spacing scale, the component library, the colours, the prohibitions. The harness is the answer to that frustration: it is where everything durable lives, so the brief only has to carry what is genuinely new about this task.

Name the deliverables of the module up front, because they are concrete files: a project instruction file (CLAUDE.md or AGENTS.md), optionally a few path-scoped rules, one or two skills, and a design-system source the agent can read — DESIGN.md and the token files. None of it is exotic infrastructure. It is a handful of Markdown files, some JSON, and a couple of commands.

Manage expectations honestly. The harness raises the floor of agent output and removes the preventable failures; it does not supply taste, and it costs a working session to set up plus an owner to keep it current. Both of those caveats get their own slides later in the module.

The framing that lands best with designers is the parallel to a design system. A design system exists because you do not want every designer re-deciding the button radius on every screen; the harness exists because you do not want every agent session re-deciding it either. The difference is the audience: a design system is written for people and tolerates ambiguity, while a harness is written for an agent and has to be checkable. 'Feel premium' works in a brand deck; it does nothing in a CLAUDE.md.

The second bullet is the practical heuristic and worth repeating until it sticks: audit your own corrections. The facts you have re-typed across sessions — token locations, spacing scales, component names, the no-gradients rule — are the harness writing itself. This is also why the harness should be built incrementally rather than as a big upfront project: grow it from real failures, not from imagined ones.

Close with the honest boundary. The harness encodes decisions that have already been made. It does not decide what a screen is for, whether the hierarchy serves the user, or whether the work is good enough to ship. Those stay with the designer, and the point of automating everything below them is precisely to give review time back to them.

Walk the diagram top to bottom and keep returning to the one dimension that matters: when the content enters the model's context window. Global and user-level instructions load every session and should hold only personal preferences — the moment team design rules end up in someone's home-directory file, the team has rules that only one machine knows about. The project instruction file also loads every session, in full, which is exactly why it has to stay short and factual. Path-scoped rules load only when the agent touches matching files, so a CSS rule costs nothing while the agent edits Markdown. Skills expose a name and description at all times but load their body only when the task matches. The brief is typed fresh every session.

Add the nuance about imports, because it surprises people: Claude Code lets a CLAUDE.md import other files with an @path reference, which is good for keeping one source of truth, but the imported content still loads in full every session. Splitting a long file into imports tidies the repository; it does not save a single token. The only mechanisms that genuinely defer cost are path-scoped rules and skills.

The most common mistake is the 500-line instruction file. It does not fail loudly — it just dilutes attention until the rules that matter get skimmed past. The fix is demotion: procedures move down into skills, file-specific constraints move into rules, and the always-loaded file shrinks back to a page of facts.

Read a few lines of the example out loud and point at what makes them work: every one is checkable. Spacing resolves to a named scale, small text has a numeric floor, colours come from named tokens, and the prohibitions are concrete enough that a reviewer can point at the violated line. Compare that with the sentences these files usually contain — keep it clean and modern, follow our brand — which cannot be verified against an artifact and therefore change nothing.

Spend a moment on length and audience. The file is loaded into every session, so the working discipline is roughly a page. The real AGENTS.md behind this school's site is thirty-eight lines; the example here is in the same spirit. The names differ by tool — Claude Code reads CLAUDE.md, Codex CLI and OpenCode read AGENTS.md, Gemini CLI reads GEMINI.md — but the job is identical, and a one-line import or a symlink lets one file serve all of them. What you must not do is maintain two diverging copies; they drift apart within weeks, and an agent reading the stale one will follow abandoned rules with full confidence.

The Checks section is the line people skip and should not. Listing the verification commands in the instruction file is what lets the agent run them itself before reporting completion, which means obvious violations never reach your review. That theme — executable gates — comes back in Module 6; here it just needs to be present in the file.

The motivation is easy to make concrete: rules about CSS custom properties are pure noise when the agent is editing a Markdown article, and rules about alt text are noise when it is writing a build script. Path-scoped rules resolve that by tying a small instruction file to a glob pattern. The rule about hex values only enters context when the agent is actually touching styling files — which is also when it is most likely to be violated.

There is a quality-of-review benefit beyond the context saving. When a constraint lives in a named rule file, a reviewer rejecting agent output can cite the exact rule that was broken rather than appealing to a vague preference. That tightens both the agent's behaviour and the team's conversations about what the rules actually are.

Do not skip the portability warning, because it bites mixed-tool teams. Path scoping is a Claude Code feature; Codex CLI, OpenCode, and Gemini CLI will not read .claude/rules/. Constraints that must hold for everyone belong in AGENTS.md or in a skill, with path-scoped rules used as a Claude Code-specific optimisation layered on top. The rule of thumb: the portable core lives in the shared file, the per-tool refinements live in per-tool mechanisms.

Skills are where most of the genuinely long material in a harness should live, because they are close to free until used. The frontmatter name and description are always visible to the agent — that is how it knows the skill exists — but the body, which can be a full procedure with rubrics, supporting files, and scripts, only loads when the task matches. A design review checklist, a prototype workflow, a token audit procedure: all of these are skills, not paragraphs in CLAUDE.md.

The example on the slide is worth reading closely because of its last line: do not redesign, reviews produce findings. Skills are good at encoding not just steps but boundaries — what this procedure must not do — which is exactly the kind of instruction that gets lost when procedures live in chat history. The other detail to point out is the description: it includes the words people actually type — review, critique, QA — because a skill that is vaguely described simply never fires. That is the most common skill failure and it is silent.

On portability: the SKILL.md format has become an open standard read by all four major CLIs, with .agents/skills/ as the shared discovery folder for Codex, OpenCode, and Gemini CLI, and .claude/skills/ for Claude Code. Teams that mix tools usually keep one folder and symlink the other. Keep skills lean — workflow and rubric in the entry file, long references beside it — and let them point at DESIGN.md and the token files rather than pasting copies that will go stale.

The shift to make here is from tokens as a build artifact to tokens as instructions. A primitive palette — blue-500, gray-900, spacing-4 — tells the agent what values exist but not when each one belongs, so it still guesses, and its guesses regress to the most common patterns on the web. Semantic tokens carry the product meaning: color.status.escalated.foreground tells the agent this colour is for escalated work, not for decoration. Component tokens go one level further and encode local rules — a status chip radius that stays compact in dense tables. The DTCG format adds a description field on every token, and those descriptions are read by the agent; they are some of the cheapest design instruction you can write.

The layering also matters for verification. Source tokens are the decision; generated CSS variables are what the application consumes; and an audit can check that components only reference the runtime variables, never raw hex values. That is what makes the colour rules in the instruction file falsifiable — either the output uses semantic tokens or the audit fails — and it is the same audit you saw catch ten hardcoded colours in the Module 1 worked example.

Be clear about division of labour with the next slide: token JSON is the data layer, CSS variables are the runtime layer, and DESIGN.md is the explanation layer. Forcing one file to do all three jobs is how token systems become unreadable to both people and agents.

This excerpt is from the real DESIGN.md that produces the site the course lives on, and the thing to point at is the structure of each section: a short identity statement, immediately translated into exact values. The mood line — clear, instructional, bookish — is allowed to exist because it is followed by OKLCH values, a radius ceiling, and named components. A DESIGN.md that stops at the adjectives is just a brand deck with a different file extension, and it changes nothing about agent output.

The anti-slop section deserves special attention because it does the most work per line. Agents inherit the most common UI habits from the public web — gradients, card soup, oversized heroes — and explicit negatives are the only reliable way to keep those habits out of your product. Vague positives produce vague output; explicit negatives prevent specific failures. Every team's anti-pattern list is different, and writing it is a genuinely useful design exercise even before any agent reads it.

On placement in the hierarchy: DESIGN.md is not pasted into the always-loaded instruction file. The instruction file names it as the source of truth, and the agent reads it at task start or when a skill requires specific sections. There is also an emerging formal spec for the format — Google Labs published one, currently in alpha, and community collections gather examples — but the working pattern does not depend on the spec: concrete values, real component paths, explicit prohibitions, kept current.

This is the most honest case study available, because it is the repository that builds the page the course is published on, and it is documented in full in the school's harness article. Walk the rows: a thirty-eight line AGENTS.md that names the stack and the verification commands; a DESIGN.md that carries the tokens, the radius ceiling, the anti-slop rules, and a component inventory mapped to real files; thirty-one skills indexed by a catalog so only the relevant one loads; a folder of owned page snapshots as taste references; and two executable gates wired into npm scripts.

Then give the comparison numbers and their caveats. The same small brief — a field-notes section, three cards — was run in a bare scratch project and in this repository. Without the harness: a gradient hero, hardcoded hex values, an invented call-to-action, ten token-audit violations, four correction rounds, roughly fifty minutes. With the harness: existing components reused, semantic tokens throughout, the audit passing first try, two rounds, roughly fifteen minutes. These are traced runs, not a benchmark, and the counts depend on the model and on what you accept as done.

Do not skip the shared miss, because it is the most instructive part. Both runs let long titles wrap awkwardly against the badge. The token audit passed it, the slop rules passed it, the skill checklist did not mention it; a human caught it in review. An automated gate only catches what it encodes — which is why the harness keeps a critique skill and a human review step above it, and why the right response to a miss is a deliberate decision about whether it recurs often enough to encode.

Two related ideas share this slide. The first is auto memory as a mechanism: Claude Code, when the setting is enabled, writes its own notes about the project — where the token file lives, which component is canonical, what broke last time — and loads an index of them at session start, with detail files read on demand. For designers this is mostly free value, but it comes with a governance caveat: memory records what the agent observed, and observations fossilise. A workaround that was true in March will be repeated confidently in June unless someone reviews the notes, promotes the ones that deserve to be standards into the instruction file or a skill, and prunes the rest.

The second idea is broader and matters even on platforms with no memory feature at all: chat history is not a harness. Teams make real decisions inside agent conversations — we agreed the table stays dense, we agreed not to use that component — and then the session ends and the decision evaporates. The next session, or the next person, re-litigates it from scratch. The discipline is simple: if a correction or a decision matters beyond today, it gets written into a file that is versioned, reviewable, and visible to the whole team.

This is also the maintenance loop for the harness itself, and it connects back to the dashed feedback line in the Module 1 loop diagram: recurring critique is the signal that a rule is missing, and the end of a session is the cheapest moment to add it.

Take these one at a time, because each maps to a failure you will see in real teams. Restating the design system in the instruction file feels thorough and doubles the maintenance burden: the moment a token changes, two files disagree, and the agent reads whichever one it loaded. The 500-line file is the most common one — it accumulates because adding a line always feels safer than deciding where the line belongs, and it degrades quietly as attention dilutes. Vibes instead of criteria is the writing failure: if two agents would interpret an instruction in opposite ways, it is not an instruction, it is a hope.

Stale rules deserve the strongest warning. Tokens move, components get renamed, the example screenshots stop matching the shipped product — and the agent keeps following the old truth with full confidence, because nothing in the file tells it the file is wrong. The fix is ownership and cadence: review the harness when the design system changes, not when someone notices drift.

The last two are about restraint and portability. Over-encoding after a single miss produces a harness so heavy nobody maintains it; the better response to a miss is a deliberate decision about whether it recurs. And duplicated per-tool instruction files — a CLAUDE.md here, an AGENTS.md there, each edited by different people — drift within weeks. One source of truth, with imports, symlinks, or pointers as the adapters.

The exercise is deliberately grounded in correction history rather than imagination. Asking people to write a harness from scratch produces speculative rules that never get triggered; asking them to audit what they have already corrected twice produces the rules that pay for themselves immediately. Most participants find the audit step uncomfortable in a useful way — it shows how much of their session time has gone into re-supplying the same facts.

The checkable-or-cut step is where the writing discipline gets built. Have participants read their own draft and mark each line: a value the agent can copy, a behaviour a reviewer can check, or neither. The neithers are usually brand adjectives, and the fix is the same translation exercise from Module 3 — turn the adjective into the observable behaviour that expresses it, or delete it.

The last step closes the loop with the running thread of the course: re-run the Module 1 task — the one participants sketched on paper and ran in Module 3 — with the new harness file in place, and count what changed. Set expectations honestly: a one-page file will not eliminate corrections, and the residual ones are usually judgment calls no file could carry. That residue is exactly what Module 6's critique and quality-gate material is for. Setup time for the whole exercise is roughly thirty to sixty minutes for a small project, and it is paid once.

Recap by walking the layers one more time, but emphasise the connective logic rather than the file names: the hierarchy exists because context has a cost, the instruction file stays short because it pays that cost every session, rules and skills exist because most guidance is only sometimes relevant, and tokens plus DESIGN.md exist because the design system itself has to be readable by the agent for any of the rules to be checkable. If participants remember only one heuristic, it should be the demotion habit: when the always-loaded file grows, something in it wants to become a rule, a skill, or a pointer.

Restate the limits so nobody leaves overpromised. The harness removes preventable failures and cuts correction rounds — the worked example showed roughly half the iterations on a traced run — but it does not supply judgment about audience, hierarchy, or whether the work is good enough, and its gates only catch what they encode. It also costs a setup session and ongoing ownership; a stale harness is actively harmful.

Preview Module 5 concretely: it steps back from the harness to the materials it operates on — why diffable design files are the precondition for all of this, what the four agent platforms and the connected canvases actually offer, where Figma still fits, and how to pick a starting stack without betting the team on a moving target. Participants who did the exercise should bring their draft harness file; Module 5's stack decisions will determine which tool-specific adapters it needs.