The Harness Is Also Onboarding. A new engineer joins the team. Their… | by Ian Johnson | Jun, 2026 | MediumSitemapOpen in appSign up<br>Sign in
Medium Logo
Get app<br>Write
Search
Sign up<br>Sign in
The Harness Is Also Onboarding
Ian Johnson
8 min read·<br>Just now
Listen
Share
A new engineer joins the team. Their first question (even if they don’t know it): Where should I read first to understand how things work here? I started to answer with the usual list — the README, the architecture doc, the deployment runbook — and stopped halfway through. The most useful document in the repo, by a wide margin, was the project’s CLAUDE.md. I had not written it for an agent, not a human. It still answered most questions better than the docs I had written for humans.<br>After reading, a new team member will have sharper questions than the previous three hires had asked in their first week. The questions are sharper because the harness had taught him the team’s conventions, naming, escalation patterns, and what not to do. The things that take months to absorb from code review and tribal memory had been compressed into a file he read on day two.<br>The harness is also onboarding. We had not designed it that way, but it was working that way anyway, and once I noticed it I started writing it that way on purpose.<br>This is the post about what changed when I noticed. Not a lot, in terms of effort. A lot, in terms of who the file was for and how the team treated it.<br>The README is aspirational; the harness is forensic<br>A harness captures the things the team has learned, mostly by paying for them. Every rule has an incident behind it. Every annotation explains a choice that was not obvious at the time. Every scope adjustment reflects a misread that the team made, noticed, and corrected. The file accumulates the way a scar accumulates; one event at a time, each event leaving a mark.<br>A traditional onboarding doc is written before the team has made the mistakes. It says what the architecture is supposed to look like, what the deploy process is supposed to be, what the conventions are supposed to be. It is aspirational. The harness is forensic.<br>The forensic document is more useful for a new hire because it tells them what actually happens when you do the wrong thing, not what you are supposed to do in theory. The new hire’s first PR is going to break three conventions. The harness tells them which three, and why, before they write the PR. The architecture doc does not. It cannot, because the conventions did not exist when it was written.<br>The accidental onboarding works because the harness is honest about the team’s reality in a way the docs built for humans tend not to be. A new hire does not need to know what the system should be. They need to know what happens when they touch it.<br>What the README leaves out<br>The README has the project’s pitch and the commands to run. The architecture doc has the diagrams. The contributing guide has the PR template. None of these tell a new engineer what the team has learned to be careful about.<br>The harness does. Here are four kinds of lines the harness tends to carry and the human docs tend not to:<br>A rule that says in the migrations directory, always test against a real database. That line tells the new hire this team has paid for a mocked-migration mistake. They learn the lesson without paying for it.<br>A rule that says errors in this service propagate as Result types, not exceptions. That line tells the new hire about a convention that pervades the codebase and would otherwise be invisible until their first review came back red.<br>A rule that says do not edit anything in legacy/; coordinate in #team-platfrom first. That line tells the new hire about a political-technical boundary that nobody put in a doc but everyone on the team knows.<br>A rule that says the test for this module hits a real Redis; bring it up with docker-compose up redis. That line gives them the exact command they would otherwise spend twenty minutes searching for.<br>The harness is dense. Every line is something the team chose to say. A new hire reads density they can use; they do not read fluff. That density is also why the harness wins against the README on day two. The README has the bird’s-eye view, but the new hire does not need a bird’s-eye view to ship their first PR. They need the things that will get them in trouble.<br>Writing for two readers at once<br>Once you accept the dual role, a few writing choices change. None of them make the harness longer. They make it more useful per line.<br>Annotate the reason. A rule that says use the structured logger is enough for the agent. A rule that says use the structured logger; we had a parsing outage in February because grep-style logs broke the alert pipeline tells the new hire the why. The agent does not need the why to apply the rule. The new hire does. The cost is one extra line. The benefit is a harness that explains itself the first time it is read.<br>Name the conventions, not just the rules. The...