How to choose a harness, and a series recap
A table to choose between the four harnesses of the series by your architecture, what they all share, and a recap of what worked, what did not, and what is still open, with only what really happened.
Before you start
- Starting point: the mini app without a harnessHarness
The app that every harness in the series shares, as it is: it works and has tests, but it has no harness and no defined architecture.
Published
The key idea: choose the architecture for your project, not for the harness. The three pieces (security, quality, and clean code) are the same in every harness of the series. What changes is the architecture rule, the hook that checks it, and the help the agent gets to respect it.
How to choose
The table sums up the four harnesses of the series and the starting point. “When to use it” gives hints taken from the sources of each page, not rules: the same project can fit two rows.
| Harness | When to use it | Rule the hook checks | Help for the agent | Difficulty |
|---|---|---|---|---|
| Starting point | To compare, or for a prototype you will throw away | None: it has no harness | None | — |
| Layered | You want each part to have a clear job and the calls to go in one direction: routes, services, data | A controller does not import a repository, and no layer imports the one above (6 rules) | Skill add-endpoint |
Low |
| Hexagonal | The business rules must not depend on the technical parts, and you want to test them without a server or database | The dependencies point toward the core, which imports nothing from outside (7 rules) | Skill add-use-case |
Medium |
| Modular monolith | Several parts of the business grow separately, maybe with different people, without splitting them into services | A module uses another only through its index.ts (5 rules) |
One AGENTS.md per module and a subagent |
Medium |
| Event-driven | A change in one part has to cause effects in others that should not know each other, such as notices or logs | Modules only talk through events (6 rules), and every event has a subscriber | Skill add-event and the event map |
High |
The three pieces go in all four harnesses: the security piece, the quality piece, and the clean-code piece.
The difficulty is my judgment: how many rules and concepts you need to understand, and how hard it is to follow the code of a request. The layered harness reads from top to bottom. In the hexagonal one and the modular monolith you need to know what a port or a public API is. In the event-driven one, the flow of a request is spread over several modules that do not import each other, and that is why its harness brings more tools to follow it.
If you are unsure, these two questions help me decide. They are my criteria, not a rule:
- Where is what changes most? If the business rules change and the technology stays, the hexagonal harness protects them. If whole parts of the business change, the modular monolith separates them. If what grows is the reactions to what happens (notifying, logging, recalculating), events let you add them without touching the publisher.
- Which mistake of your agent worries you most? Each harness checks one: skipping a layer, bringing the technology into the core, reaching inside another module, or calling another module instead of publishing an event. Choose the one that watches for the mistake that would cost you most.
What they have in common
The five projects are the same library API, in TypeScript with Node and Express, and they pass the same 11 acceptance tests: test/library.test.ts is byte-for-byte identical in all of them. That is why they can be compared.
The four harnesses also share:
- An
AGENTS.mdthat explains where each thing goes, the key rule, and the verification commands, plus the security, quality, and clean-code sections of the pieces. - An
.agents/folder with the hooks, the skills, the permissions, and, in the modular monolith, a subagent. No file belongs to one specific agent, and each page explains how to connect them. - Four stop hooks. One checks the architecture rule, and the other three are the pieces’ hooks: secrets, quality (formatting, lint, types, and tests), and duplicates. If the architecture, secrets, or quality hook fails, the agent cannot finish; the duplicates hook warns once and lets it finish.
- Two more hooks: one blocks dangerous commands before they run and another formats every file the agent edits.
- The pieces, copied without changes. Each day I checked with
cmpthat their files and their 56 tests are identical to the original pieces.
| Harness | Architecture rules | src/ files without tests |
Tests | Instructions | Production dependencies |
|---|---|---|---|---|---|
| Starting point | 0 | 2 | 11 | None | Express |
| Layered | 6 | 14 | 70 | One AGENTS.md |
Express |
| Hexagonal | 7 | 22 | 70 | One AGENTS.md |
Express |
| Modular monolith | 5 | 19 | 70 | Four AGENTS.md |
Express |
| Event-driven | 6 and the event check | 26 | 80 | One AGENTS.md |
Express and Zod |
What worked
- The same app in all of them. The 11 acceptance tests passed untouched in the five projects. Changing the architecture never forced a change to the contract.
- The pieces were reused as they were. They came out of the layered harness on days 3 to 5 and went unchanged into the hexagonal, modular monolith, and event-driven harnesses. What changed in each harness was only the architecture part: the folders, the rules, the hook message, and the skill or the subagent.
- One hook per job. Since day 3, each piece brings its own stop hook instead of editing the harness one. The architecture hook only checks its rule. That way you can copy a piece without touching the others, and each error message says what failed.
- Every broken rule was caught. In each harness I broke the main rule on purpose, and from day 6 also the others, one by one. The check failed every time, and the hook, run with a simulated stop event, exited with code 2.
- The hook blocked a real agent. On day 6, in the hexagonal harness, I asked Claude Code to import Express into the domain and finish. The architecture and quality hooks blocked the stop, and the agent warned me and asked whether to remove the import.
- The instructions guided the agent. In the sessions of days 7 and 8, no one broke the rule. In the modular monolith, the agent read the module’s
AGENTS.mdbefore changing it, and Claude Code loaded it on its own when it opened a file of that module. In the event-driven harness, the agent solved both cross-module tasks with events. - The StackBlitz button. From day 1 to day 7, each template’s tests passed in StackBlitz from Chromium, without installing anything.
What did not work or cost more
- The first real agent arrived on day 6. On days 2 to 5 I could not test any harness in a real session: the Claude Code CLI had an expired session, Codex answered that the account had reached its usage limit, and Cursor was not installed. The tests of those days ran the hooks with simulated input.
- A hook the agent cannot satisfy. In that day 6 session nobody answered the agent’s question. After 9 blocks in a row, Claude Code ended the turn on its own, and the import stayed in the code. A stop hook stops the agent from saying it is done, but it does not fix the code for it.
- StackBlitz is not Node. On day 3, 34 of the 39 tests of the security piece failed, because reading standard input with
readFileSync(0)did not work there; the hook switched to reading it as a stream. On day 5 several tests went over the 5-second limit, and I raised it to 30. Embedding StackBlitz in the page without isolation headers did not work either, so the button opens a new tab. - Tools that do not run in the browser. I ruled out gitleaks because it is a Go binary, and I stayed with jscpd 4 because from version 5 it runs a native binary. jscpd 4 brings 5 high
npm auditwarnings with no fixed version. - StackBlitz, on day 8. On October 25, Vitest did not start in StackBlitz, neither with the new harness nor with the day 7 one, which passed on the 21st. The error came from a dependency that StackBlitz downloads when it starts, not from the templates. The event-driven harness page tells the details.
- My own setup mistakes. On day 8, in the first attempt at the real sessions, I passed the list of allowed commands wrongly and the agent could not run
npm. I repeated both sessions. In that first attempt, the stop hooks ran the checks the agent could not. - What the agent skipped. In most sessions, the agent did not use the clean-code review skill, even though
AGENTS.mdasks for it before finishing. In one session on day 8 it kept a class name that no longer described what the class stores. Instructions guide, but they do not force.
What is still open
- Codex and Cursor, untested. What the pages say comes from their documentation. According to it, the Codex stop hook expects JSON on standard output when it exits with 0, and the Cursor one expects
followup_message; I did not write the adapters. - Systems and browsers. I tested on Windows 11 (days 2 to 5) and on Fedora Linux 44 (days 6 to 8), with Node 24. I did not test macOS or Node 22 locally, and StackBlitz only in Chromium.
- Two piece tests, only simulated. That the permission rule blocks reading
.envand that the command hook blocks a dangerous command I did not test in a real session. That the quality hook does not let the agent finish did happen in a real session, on day 6. - Stop hooks in parallel. Claude Code and Codex run them at the same time. One quality hook test writes a fake secret while the secrets hook could be reading the files. It never failed, but it depends on the timing.
- Testing StackBlitz again. Since October 25, the “Run in the browser” button does not get to run the tests. Until I test it again, run the harnesses on your computer.
- The repository is private. The code shows in each page’s explorer and runs with the button, but it is not published as a repository.
- Outside the series, for later: microservices and frontend architectures.
- A topic of its own about reusing pieces. The plan left it as optional and I did not write it.
The full series
| Day | Page | Kind |
|---|---|---|
| 1 | Starting point: the mini app without a harness | Starting point |
| 2 | Layered harness | Base harness |
| 3 | Piece: security | Piece |
| 4 | Piece: quality | Piece |
| 5 | Piece: clean code | Piece |
| 6 | Hexagonal harness | Base harness |
| 7 | Modular monolith harness | Base harness |
| 8 | Event-driven harness | Base harness |
| 9 | How to choose a harness, and a series recap (this page) | Guide |
Next step
If you have not done it yet, start with the starting point and open the harness you chose next to it: comparing the two explorers shows what the harness adds to the same app. To understand when each hook acts, see the “How a harness works” section on the home page, which walks through the agent loop step by step.
Related content
- Hooks: checks that run on their ownTechnique
Commands that run automatically at specific moments of the agent’s work, such as before editing a file or when it finishes, so the important steps do not depend on the agent remembering them.
Published - Verification and evaluationTechnique
How to check that the agent did the job right without taking its word for it: give it ways to verify itself, review both the result and the process, and compare setups honestly.
Published