A free, hands-on tutorial · .NET examples · checked against tool docs on 2026-09-30
The Agent Harness
Configuring AI coding agents on real projects: the harness, not just the prompt. A harness is the set of files committed in your repo (rules, skills, reviewers and guards) that steer any agent working in it. You'll go from typing into a chat to building one.
11 lessons and a capstone, in order. Each lesson ends with an exercise and a "Done when" list: tick every box to earn that lesson's plaque in the top bar. The orange flag always marks where to pick up, and all 11 plaques unlock a completion page you can keep or share as proof.
Most developers use a coding agent as a chat: type a request, accept the result. Then the agent quietly makes calls that were yours to make. Real sessions we studied show it downgrading the framework when an SDK was missing, rewriting a safe stock update so a test tool could run it (and overselling), and committing without being asked. Every lesson starts from one of those real, anonymised moments and shows the piece of harness that prevents it.
How it works
- One practice repo. agent-harness-practice (StockApi: products, orders, one concurrency invariant). Lesson 1 shows how to get it. Each lesson's exercise adds one piece of harness to it. The reference solution is that same repo after all 11 lessons, with the complete harness and the features the exercises build (except lesson 4's
skuPrefixfilter, which is yours to build). Treat it as the answer key: try each exercise first, then compare. - Keep moving work into the harness. Each lesson ends with a "Harness it" tip: a step you can stop doing by hand. Keep going until your job is mostly planning the work and validating the result.
- One way, not the only way. Everything here (the 1-3-1 hand-over, a ~40-line rules file, the commit skill's steps, the four guards, the swap test) is one setup that works, built from real sessions. Treat each as a starting point: keep the principle, then shape the details to your team, your stack and your tools.
- Tool-neutral first.
AGENTS.mdand.agents/skills/work in Claude Code, Codex and Antigravity. Claude Code specifics come second, and each lesson shows the Codex and Antigravity equivalent. - Short lessons, real exercises. About 20 minutes of reading and 30–45 minutes of hands-on work each. Quizzes check what you remember from earlier lessons as well as the current one. Your quiz results show up in the list below, stored only in this browser.
- Stuck? Ask your agent. Lesson 1 puts two folders side by side in
~/projects:agent-harness-course(these pages) andstockapi(your practice repo). Start your agent in~/projectsso it can read both, then name the files. For example: "Read agent-harness-course/lessons/0003-one-three-one.html and explain its exercise step 4 using my stockapi repo." Or: "Quiz me on lessons 1 to 4, one question at a time, without showing the answers." Each lesson also ends with a prompt to try in your own repo.
Before you start
Do the lessons in order, 1 to 11. Each one builds on the repo from the last. Plan about 12–15 hours over one or two weeks: roughly 20 minutes of reading and 45–90 minutes of hands-on work per lesson, plus the capstone. You finish with your own practice repo carrying a full harness, and a second repo where you built one against the clock.
Check your setup
Run each command; the right-hand column is what you need to see.
| Tool | Check | Need |
|---|---|---|
| .NET SDK | dotnet --list-sdks | an 8.x line |
| git | git --version | 2.28 or later |
| Your agent | claude --version (or Codex / Antigravity) | Claude Code 2.1.277 or later |
| Node.js | node -v | 18 or later, for the MCP server in lesson 8 (nodejs.org) |
| gitleaks | gitleaks version | any 8.x, for lesson 7 (install) |
| sqlite3 | sqlite3 -version | any 3.x, for lesson 8 (download) |
Optional, while you learn: in Claude Code, run /output-style explanatory so the agent explains its choices as it works, or /output-style learning to have it leave the key parts for you to write. Lesson 2 covers output styles.
The commands, hooks and scripts in this course are bash. Do the course inside WSL2 (Ubuntu), where everything works exactly as written: wsl --install in an admin PowerShell, then install the tools above inside Ubuntu (Microsoft's guide).
Git Bash also works, with three differences:
- Symlinks become copies unless Developer Mode is on. Copy the skill folders instead, and re-copy them after edits.
- Windows has no exec bit. Run
git update-index --chmod=+x .githooks/* .claude/hooks/*.shafter adding hooks. - Your agent's session files live under
%USERPROFILE%\.claude\projects.
PowerShell on its own is not supported.
Anything marked verified 2026-09-30 is version-specific; re-check it against the linked docs if your tool is newer. unverified means test it yourself before relying on it.
Lessons
- 01How a coding agent actually worksThe loop, the context window, why chat rules drift, permission and plan modes
- 02Rules files: AGENTS.md as the source of truthAn index of about 40 lines, nested and path-scoped rules, committed first
- 03When the agent is stuck: 1-3-1One problem, three options, one recommendation, then wait. The net7 and InMemory traps
- 04Plan-gated workflowExplore, plan, slice, gate, review, commit, and changing the plan mid-task
- 05Skills: procedures the agent runs by nameA commit skill and a quality-gate skill
- 06Reviewer subagentsFresh-context reviewers; the author never grades itself
- 07Guards: rules that blockPermission rules, hooks, git hooks, guard tests, attribution
- 08MCP: live docs and real datacontext7 for current library docs, and read-only database access
- 09Writing code and docs for the agentADRs, one reference shape, docs audited against code
- 10Evidence and honestyRaw transcripts, a reflection on what you rejected, never rewriting history
- 11Capstone: harness in 30 minutes, then the swap testBuild a full harness on a fresh repo, then see if it steers a brand-new agent session
Reference sheets
Print these or keep them open while you work. They are the compressed version of the lessons.
| Sheet | Use it when |
|---|---|
| AGENTS.md structure | Writing or reviewing a rules file |
| The 1-3-1 format | The agent is stuck, or you are |
| Commit skill checklist | Building or checking a commit skill |
| The four guard types | Deciding what should block, not just ask |
| Which mechanism? | Choosing between a rules line, skill, reviewer, hook, test or MCP, and what needs a model at all |
| Tool equivalents | Claude Code ↔ Codex ↔ Antigravity |
| Glossary | A term is unclear, or you want the exact name for something |
Where are you now?
Five stages from chatting with an agent to steering it. Stages 1 to 3 are all prompt-only; this tutorial gets you to 4 and 5.
| Stage | What it looks like |
|---|---|
| 1 · Delegated | The build is handed over in one or two prompts; the human doesn't steer |
| 2 · Chat | One long chat with some scope steering; the agent reviews itself |
| 3 · Gated chat | The human reviews a plan before code, commits are sliced, and AI output is really challenged, but it's 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 (the reference solution) |
Where to get wisdom
A harness proves itself on someone else's agent. After the capstone, swap repos with a colleague and run each other's swap test. For tool questions, the Claude Code repo, the OpenAI developer community and the Google AI developers forum are the maintained places to ask. Sources for every claim are listed in RESOURCES.md.