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.
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.
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.
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.
The README is aspirational; the harness is forensic
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.
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.
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.
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.
What the README leaves out
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.
The harness does. Here are four kinds of lines the harness tends to carry and the human docs tend not to:
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.
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.
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.
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.
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.
Writing for two readers at once
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.
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.
Name the conventions, not just the rules. The harness gets sharper for the agent if rules are imperative — always X, never Y. The harness gets sharper for the new hire if the conventions have names. We call this the import-flow contract is more useful for a human than a list of three imperatives in the import directory, even if the latter is more usable for the agent. The trick is to do both: name the convention in the section header, then list the imperatives below.
Make the boundaries explicit. The harness should say which modules are owned by which sub-team, which directories require coordination, which areas are stable and which are in flux. The agent uses this to know where to be careful. The new hire uses it to know who to ask. The same line does both jobs.
Keep it readable end to end. A harness that is sectioned and skimmable is a harness a new hire can actually finish in an hour. A harness that is one unbroken list of rules is a harness the new hire gives up on at minute eleven. The agent does not care about pacing. The human reader does, and the human reader is the one who closes the file if it loses them.
The dual-role harness is not longer than the agent-only harness. It is the same length, with two or three extra lines per major rule and a structure that supports both readers.
The onboarding flow that puts the harness first
Our current first-week flow for a new engineer:
Day one: environment. Clone the repo, install dependencies, run the test suite locally. This is the boring stuff and it has not changed. The harness does not help with this; a good make bootstrap does.
Day two: read the project CLAUDE.md end to end. Read it slowly. Ask questions in the team channel as they come up. The questions become annotations the harness was missing. The whole day is for this.
Day three: read one subdirectory’s CLAUDE.md. The one closest to the engineer’s first task. The path-scoped harness has the local conventions, which are denser and more specific than the project-level rules. By the end of the day the engineer has a working model of the area they are about to change.
Day four: a small PR, with the agent assisting. The harness catches the failure modes the engineer would otherwise walk into. The human review is on the substance of the work, not on the conventions, because the harness handled the conventions before the PR was opened.
The first week ends with the engineer having absorbed more of the team’s accumulated practice than they would have in two weeks under the previous flow. The cost of writing the harness for the dual role was small — three or four hours of editing, spread over a couple of evenings. The return compounds on every subsequent new hire.
A new hire’s questions are a free audit
The thing I underestimated, before noticing this pattern, was how much signal a new hire’s questions are for the harness itself.
A new hire asking why does this module have a different error pattern than the others is telling me the harness does not name the convention clearly enough, or does not name it at all. A new hire confused about which directory a particular kind of code belongs in is telling me the harness does not encode the structural rule. A new hire surprised by a CI failure is telling me the pre-commit hooks are not communicating their constraints clearly. None of these are gaps in the new hire’s understanding. They are gaps in my document.
I treat the new hire’s first month as a free audit of the harness. Their questions are the gaps. Their confusions are the rules that need to be sharper. I patch as the questions come in, which means by the time the next new hire arrives, the document is a measurable amount better. The cycle has run six times now and the file has gotten better every single round.
This is the second dividend of the dual role. The harness is onboarding. The onboarding feedback is harness improvement. The flywheel runs in both directions, and it runs for free. The new hire is going to ask the questions either way.
What this does to the architecture doc
The first time I noticed all this, I asked whether the architecture doc was still earning its place. The answer turned out to be yes, but a narrower yes than before.
The architecture doc has the diagrams, the high-level shape of the system, the names of the services and how they communicate. It is the map. The harness is the ground truth: the conventions, the constraints, the practices the map does not capture.
The new hire reads the map first to know what they are looking at, then the ground truth to know how to walk on it. Both are still required. The harness did not replace the architecture doc; the harness made the architecture doc a smaller document, because the harness was carrying the load the architecture doc had been trying to carry and failing.
The map is short. The ground truth is detailed. That division turns out to be the right one. The diagram I used to update every quarter to keep up with the conventions is now stable for a year at a time, because the conventions live in the file that gets edited every week anyway.
Read your harness like a new hire this week
If you are running an AGENTS.md or CLAUDE.md or any equivalent file on a team project, three things to do this week.
Open the harness and read it cold. Pretend you joined the team last Monday. You do not know what the codebase does. You do not know who owns what. Read every line. Note every sentence that assumes context a stranger would not have. That list is your patch list. Annotate the reasons. Name the conventions. Fix the unexplained jargon. Do this in one sitting if you can; the cold-reader perspective decays fast.
Hand the patched harness to the next hire instead of writing them a new onboarding doc. Sit with them while they read it. Write down every question they ask out loud. Their questions are your next patch list. Do not defend the existing document. Edit it.
Move one section out of the architecture doc and into the harness. Pick the section that has gone stale fastest — usually the conventions section, or the section listing which team owns which module. Put it where the file is actually updated. Delete the now-empty section in the architecture doc, or leave a one-line pointer. The architecture doc gets smaller. The harness gets one more thing it is honest about.
After those three, the harness is doing on purpose what it had already started doing by accident. A document that is read by both the agent and the new hire has to earn its place twice. The rules that earn their place twice are the rules worth keeping. The rules that earn their place only for the agent are still load-bearing, but the dual-role audit makes them visible, which is the first step to making them better.
The harness is doing more work than you think. Notice the second job. Then write it on purpose.
