Agent Harness · Reference sheet

Glossary

The words this course uses, one meaning each. When two words compete, the entry says which one to use.

How an agent works

agent: A model running in a loop with tools: each turn it reads its whole context window and picks the next tool call. Avoid: chatbot (it acts), AI, copilot

tool (tool call): A function the agent may call: read or edit a file, run a shell command, search, fetch a URL. Every tool call passes through the harness, which is where it can be blocked. Avoid: plugin, command

agentic loop: The repeating cycle of gather context, take action, verify results. The harness runs each call and appends the result; the window only grows. Avoid: chain, pipeline

context window: The model's working memory and everything it knows right now: system instructions, rules files, loaded skills, the conversation and all tool output. It is finite. Avoid: memory (that is a separate Claude Code feature), history

compaction: Summarising older turns to make room when the context window fills. Root-level rules files are re-read from disk afterwards; instructions given only in chat are not. Avoid: truncation, forgetting

fresh context: A subagent or new session that starts without the conversation that produced the work. It is what makes a reviewer agent independent. Avoid: clean slate

permission mode: The setting that decides which tool calls run without asking: default (shown as "Manual"), acceptEdits, plan, auto, dontAsk, bypassPermissions. Shift+Tab switches between the everyday ones; on v2.1.283+ you start in auto, where a second model approves most actions. v2.1.283+ · verified 2026-09-30 Avoid: approval level, yolo mode

plan mode: A permission mode where the agent explores but does not edit your source files until you approve a plan; when auto mode is available, a classifier may approve shell commands while it plans. Avoid: dry run

Rules and context files

harness: The tool (Claude Code, Codex, Antigravity) plus everything in the repo that configures it: rules, skills, reviewers, hooks and permissions. "Harness" names the whole steering layer; Harness (capitalised) is also stage 4 of the stages. Avoid: setup, config, prompt engineering

rules file: A file the tool loads into every session to steer the agent: AGENTS.md, CLAUDE.md, GEMINI.md. A rule here survives compaction; a rule typed in chat does not. Avoid: system prompt, prompt, memory

AGENTS.md: The open, tool-neutral rules file, "a README for agents". Codex and Antigravity read it; Claude Code reads it natively from v2.1.277 when no CLAUDE.md exists. Avoid: README (that is for humans), CLAUDE.md as the source of truth

index (rules file as index): A rules file kept to about 40 lines: commands, definition of done, invariants, 1-3-1, and plain links to focused files. Depth is loaded only when the task needs it. Avoid: manual, handbook

nested rules: An AGENTS.md in a subdirectory (for example tests/), loaded in addition to the root file. Claude Code loads it when it reads a file there; Codex concatenates root to cwd, closest last. Avoid: child config

output style: The Claude Code setting for how the agent answers: length, tone and shape, for every reply in the session. Built in: Default, Proactive, Concise, Explanatory (adds Insight blocks) and Learning (also leaves TODO(human) for you to write). Set with /output-style or /config; separate from the rules file, which sets what it knows. verified 2026-10-13 Avoid: persona, tone setting

path-scoped rule: A rule file with a glob that loads only when matching files are touched: Claude .claude/rules/*.md with paths:; Antigravity .agents/rules/*.md with trigger: glob. Avoid: conditional rule, folder rule

import: An @path line in a Claude Code rules file that pulls another file in (up to 4 hops). It organises a long file but does not reduce its context cost: imported files load at launch. verified 2026-09-30 Avoid: include, link (a plain link is read on demand)

output style: A Claude Code setting that changes how the agent talks to you (for example Learning: TODO(human) plus Insight blocks), not what it knows about the repo. It is an instruction, not a guard. Avoid: persona, tone rule

Rules that matter

invariant: A rule that must stay true however the code changes, stated in AGENTS.md and detailed in docs/ai/invariants.md. A change that breaks one is wrong even if the tests pass. Avoid: guideline, best practice

forbidden pattern: An invariant stated as the code shape that breaks it, so a reviewer can match it: read-then-write on stock. Avoid: anti-pattern (too vague to grep for), code smell

definition of done: Numbered, checkable conditions every slice must meet: gate green, reviewer has read the diff, human approved the commit. Success is evidence, not opinion. Avoid: acceptance criteria (those belong to the feature)

1-3-1: The hand-over when the agent is stuck: 1 problem, 3 options with trade-offs, 1 recommendation, then wait for the human. It triggers when a tool, SDK, test provider or environment blocks, when a fix would change an invariant, a requirement or the machine, or after a failed retry. Avoid: asking for help, escalation

ADR: Architecture decision record: a short file in docs/decisions/ saying a deliberate oddity is intentional, and why, so an agent does not "fix" it. Avoid: design doc, wiki page

reference shape: One well-built example to copy (ProductsController and its tests). "Copy the shape of X" beats a page of description. Avoid: template, boilerplate

Workflow

plan gate: No code until a human-edited plan is committed on its own (docs(plan): ...). The commit order proves the plan came first. Avoid: planning phase, spec

slice: One small, independently testable change with its own test and its own commit. The unit of the loop: plan, gate, review, commit. Avoid: task, ticket, PR

quality gate: The ordered checks a slice must pass before review: format check, then build with warnings as errors, then test; stop on the first failure. It is a skill. Avoid: CI, lint step

self-review: The agent reviewing its own diff. It is agent work, not human review, and it is what a reviewer agent replaces. Avoid: code review (when the author is the reviewer)

history rewriting: Amend, rebase, reset or force-push to change commits already made. Forbidden here: a tidy log that is not the real order of work is worse than a messy honest one. Fix forward with a new commit. Avoid: cleaning up history, squashing

fix forward: Correct a mistake with a new commit (git revert, a new edit, a .gitignore entry) instead of changing history. Both the mistake and the fix stay visible. A leaked secret is the exception to "just fix it": rotate it first. Avoid: undo, clean up

30-minute runbook: Lesson 11's setup on a repo you have never seen, before any feature code: rules, skills, reviewers and guards go in as four commits, then a fifth block proves the harness loads. 60 to 90 minutes the first time, then 30 minutes from your own template. Avoid: setup task

Conventional Commits: The message format type(scope): summary, for example feat(orders): atomic placement. Types are feat, fix, docs, test, refactor, perf, build, ci, chore, style and revert. The commit-msg git hook and the commit skill both enforce it. Avoid: commit convention (too vague)

Skills and reviewers

skill: A folder with a SKILL.md (name, description, steps) the agent runs by name or picks from the description. Tool-neutral home: .agents/skills/, symlinked per skill for Claude Code. A repeatable procedure, not a pasted prompt. In Claude Code a personal skill beats a project skill with the same name (enterprise over personal over project), so check your own ~/.claude/skills/ for a clashing commit. Avoid: slash command (commands merged into skills), macro, template

symlink: A file that is only a pointer to another path (.claude/skills/commit -> ../../.agents/skills/commit). The course keeps each skill in one tool-neutral place and links it for Claude Code, so there is one copy to update. The target is relative to the link's own folder. On Windows, symlinks need Developer Mode or WSL2, or git writes a plain text file instead. Avoid: shortcut, alias

subagent: An agent a parent agent starts in its own fresh context, with its own prompt, tool allowlist and permissions. Defined in .claude/agents/*.md (Claude), .codex/agents/*.toml (Codex) or .agents/agents/*.md (Antigravity). Avoid: helper, sub-task

reviewer agent: A read-only subagent that reviews a diff it did not write and returns findings (test-reviewer, stock-invariant-reviewer). The author never judges its own work. Avoid: second opinion, linter

Guards

guard: Something that mechanically blocks: a permission rule, a PreToolUse hook, a git hook or a guard test. In this course "guard" always means this; a rule the agent is asked to follow is a "rule". Avoid: safeguard, guardrail (too loose), rule

permission rule: A deny, ask or allow entry in settings, such as Bash(git commit *). Evaluated deny, then ask, then allow; the first match decides. It matches command text, so it is not a security boundary. Avoid: policy, allow-list (when auto-clicked)

hook: A script the tool runs on an event (SessionStart, PreToolUse, PostToolUse, Stop and others). A PreToolUse hook can deny a call. Hooks are not git hooks. Avoid: trigger, callback

PreToolUse: The hook event that fires before a tool call runs. It blocks with exit code 2 or a JSON deny; exit 0 with no output is "no decision", not approval. Avoid: pre-hook

SessionStart: The hook event at session start. Its plain output becomes context for the agent: the course uses it for a preflight report of SDK, Docker and plan status, reporting without fixing. Avoid: startup script

git hook: A script git runs on a git event, here .githooks/pre-commit and commit-msg via core.hooksPath. It binds anyone committing, but only in a clone that set the path, and --no-verify skips it. Avoid: husky (a tool that installs them), commit script

gitleaks: A command-line scanner that finds credentials in files and git history. The course runs gitleaks git --pre-commit --staged --redact --no-banner in the pre-commit hook and gitleaks git --redact --no-banner over history; it misses some readable config secrets, so the hook adds a pattern check. Avoid: secret scanner (name the tool)

guard test: A test that fails when a project invariant breaks: 12 concurrent orders for 3 units must give exactly 3 successes. It can be green for the wrong reason, so a reviewer agent reads the diff too. Avoid: regression test (too broad), unit test

attribution trailer: The AI co-author or "Generated with" line Claude Code adds to commits and PRs. This course's setup excludes it (if your team wants the trailer, flip the check): set attribution portably as commit "", pr "", sessionUrl false, and reject leftovers in commit-msg. false needs v2.1.281+ Avoid: signature, credit line

work identity: The author name and work email (for example you@yourcompany.com) the human sets in the repo's git config, not the agent. The pre-commit hook and the commit skill check the domain, so a personal address never reaches history. Avoid: git user, account

trust dialog: The prompt Claude Code shows the first time you open a folder. Until you accept it, project allow rules do not apply, although deny and ask rules do. Every fresh clone, including the one in a swap test, shows it again. Avoid: permission prompt (that is a per-call question)

MCP

MCP: Model Context Protocol: the open standard that lets an agent call tools hosted outside the tool, such as live docs or a database. Avoid: plugin system, API

MCP server: A process or remote endpoint that exposes tools over MCP, configured in .mcp.json (Claude), [mcp_servers.x] in config.toml (Codex) or .agents/mcp_config.json (Antigravity). Vet one before adding it; the official SQLite server is archived. Avoid: connector, add-on

context7: The MCP server that fetches current library documentation (@upstash/context7-mcp, pinned 4.1.1). It stops the agent coding from stale training data, such as the SQLite DateTimeOffset limit. Avoid: doc search, Stack Overflow

Evidence and the swap test

raw transcript: The tool's own record of the session (Claude: /export, or the JSONL under ~/.claude/projects/), kept in the repo. It is evidence; narrative docs written by the agent are claims to verify. Avoid: chat log, summary, session notes

JSONL: "JSON Lines": a text file with one JSON object per line. Claude Code writes every message and tool call of a session as JSONL under ~/.claude/projects/, so line tools such as grep and sort can count tool calls in it. Avoid: log file

reflection: A short human-written file tying each rejection or change to a commit or a transcript line. Claims without a hash or line are unverifiable. Avoid: retrospective, AI log

swap test: A fresh clone and a fresh session with a clean profile, given one unseen task and nothing else, to see whether the repo's harness steers the agent. You watch and score four questions pass, partial or fail; a partial or fail is a bug report on the harness (lesson 11). Avoid: demo, handover

evidence order: Which record to trust first: the raw transcript, then git history, then files, then narrative docs (notes, README, reflections), which are claims until checked against the first two (lesson 10). Avoid: "the docs say so"

trap: A situation an exercise sets up on purpose (lesson 3 has the first two) to see whether your harness steers the agent: a missing SDK, a test provider that breaks the invariant, a tempting secret, a mid-task requirement change, agent over-reach, scope bait. Each has a right answer and a lesson that defuses it. Avoid: bug, gotcha

stages: The five steps from chatting with an agent to steering it, from Where are you now?: 1 Delegated (the build handed over in one or two prompts), 2 Chat (one long chat; the agent reviews itself), 3 Gated chat (a reviewed plan and sliced commits, still prompt-only), 4 Harness (a rules file committed before the work, plus at least one custom mechanism that demonstrably ran), 5 Full harness (rules, skills, independent reviewers, hooks and guards, MCP, all visible in the transcript). This tutorial gets you to 4 and 5. Avoid: level, grade, maturity

oversell: Selling more units than exist because two requests both read the same stock. The outcome of a race condition (two requests racing for the same stock), and the failure the stock invariant exists to prevent. Avoid: "race condition" for the sale itself; that names the cause, and oversell names the result

.NET and project terms

read-then-write: Load the entity, check Stock, assign, SaveChanges. The forbidden pattern for stock: two requests can both read 3 and both write 0. It can pass the concurrency test inside a SQLite BeginTransaction() because the provider takes the write lock up front, and oversell without it. Avoid: load-modify-save, optimistic update

guarded UPDATE: One statement that checks and writes together: ExecuteUpdateAsync with Stock >= n in the WHERE. Zero rows affected means 404 or 409. Safe on any provider. Avoid: atomic update, optimistic lock

ExecuteUpdateAsync: The EF Core 7+ method that runs one UPDATE statement in the database without loading or tracking entities. With a Where that includes the stock check it is the guarded UPDATE. The InMemory provider cannot run it. Avoid: bulk update

EF InMemory provider: The EF Core test provider that keeps data in memory. Microsoft "strongly discourages" it for testing; it has no ExecuteUpdate and rejects transactions by default. Banned in this repo: tests run on real SQLite. Avoid: fake database, test DB

provider: The EF Core plug-in that talks to one particular database (Microsoft.Data.Sqlite for SQLite, SqlServer, InMemory). The same LINQ can behave differently per provider: which statements it can translate, and how it locks. A test that is green on one provider can hide a bug on another. Avoid: driver, database type

14-day package rule: A house rule this course follows: no package version younger than 14 days. Supply-chain attacks target freshly published versions, so wait for the community to catch them. It is why the commit-msg guard is a shell regex and not a newly released npm tool. Avoid: "latest"

Resolutions

• In this course "guard" always means something that mechanically blocks. A rule the agent is asked to follow is a "rule".
• "Harness" is the tool plus the repo configuration; "Harness" (capitalised) is also stage 4 of the stages. Context says which.
• A hook is a tool event script; a git hook is a git event script. Never say "hook" alone when both are in play.
• A skill is what the agent runs; a reviewer agent is who reads the diff; a rule is what it is asked to remember. Only the first two can be checked.

Tool facts come from the tool equivalents sheet. Verified 2026-09-30.

Taught in: Lesson 1: How an agent works · Lesson 2: Rules files · Lesson 3: 1-3-1 · Lesson 4: Plan-gated workflow · Lesson 5: Skills · Lesson 6: Reviewer subagents · Lesson 7: Guards · Lesson 8: MCP · Lesson 9: Writing for the agent · Lesson 10: Evidence and honesty · Lesson 11: Capstone
Other sheets: AGENTS.md structure · The four guards · Commit skill · 1-3-1 · Tool equivalents