Agent Harness · Reference sheet
Which mechanism?
You want something to happen every time. Should it be a line in a rules file, a skill, a reviewer, a hook, a test or an MCP server? And does it need a model at all? One question decides most cases: does this step have one right answer?
One right answer (format, build, a file pattern, a commit message shape): a script, a hook or a test does it, the same way every run. Needs judgement (write the code, is this change safe?): the model does it, and a second model with a fresh context checks it. Has consequences (approve the plan, accept a BLOCK, commit, push): you decide. A model is the most flexible part of the harness and the least reliable, so give it only the steps that need it.
Need → mechanism
| You need… | Build | Why this and not a rules line | Lesson |
|---|---|---|---|
| A fact every session should know (build command, the invariant) | A line in AGENTS.md | It is a rules line: short, loaded every session, re-read after compaction | 2 |
| A fact that only matters in one folder or file type | Nested AGENTS.md or .claude/rules/ with paths: | Loads only when needed, so other tasks don't pay for it | 2 |
| The agent to stop and ask at a real decision | The 1-3-1 rule in AGENTS.md, plus an ask rule for risky commands | The rule shapes the hand-over; the ask rule makes the stop happen even in auto mode | 3, 7 |
| Answers in a shape you like (explain as it goes, or keep it short) | An output style: Explanatory, Learning, Concise, or your own | It shapes every reply in the session; a rules line about tone is applied unevenly | 2 |
| A procedure you repeat (commit, release, new endpoint) | A skill | Loads only when used; steps run in order; a script inside gives the same result every run | 5 |
| A whole loop as one command | A workflow skill (ship-slice) that calls the others | One command, with the human stops written in | 9 |
| A second opinion on every diff | A reviewer subagent, read-only | Fresh context: it never saw the author's reasoning | 6 |
| Something the agent must never run | A deny rule, plus a PreToolUse hook for patterns | Blocks the call before it runs, whatever the model decides | 7 |
| Something no commit may contain, whoever wrote it | A git hook (pre-commit, commit-msg) | Runs on every commit, by a human or an agent, with any tool | 7 |
| Proof that an invariant holds | A guard test (12 orders for 3 units) | Fails the build when the code breaks it; a reviewer can be wrong | 7 |
| Live docs or data the model would otherwise guess | An MCP server (pinned, vetted) or one read-only command | Reading the source beats remembering it | 8 |
| The reason odd-looking code is that way | An ADR, plus a one-line comment pointing at it | The why lives in one file the agent reads before it edits | 9 |
| Docs that stay true | A checking skill (/update-docs) in the definition of done | Claims get checked against the code, not trusted | 9 |
| Work to continue somewhere else | A handoff file, or /fork | A new chat, tool or colleague can't see this one | 5 |
Claude hooks or git hooks?
Both run a script, and they fire at different moments. Most teams want both for the things that matter.
| Claude Code hook (PreToolUse, PostToolUse…) | Git hook (pre-commit, commit-msg) | |
|---|---|---|
| Fires when | The agent is about to call a tool, or just did | Anyone runs git commit |
| Sees | The tool call: the command, the file, the edit | The staged diff and the message |
| Binds | This agent, in Claude Code only | Every human and every agent, in every tool |
| Good for | Stopping a command before it runs (force-push, rm -rf); formatting after an edit | Secrets, build output, identity, message format |
| Misses | Anything you type yourself; an Edit-tool write when the hook only watches Bash | Anything that never reaches a commit |
Does it need a model at all?
Before you write a skill, ask whether a plain command would do. Formatting is dotnet format, not a request to "format nicely". A version check is dotnet --version, not a question. If the step can be a script, make it one, and let the skill call it: quality-gate runs gate.sh, and the model's job is only to read the output and fix the cause.
This is one way to split the work, built from the course's reference solution. Your team may draw some lines differently; keep the principle.