Chapter 5 · Multi-Agent & Team Harnesses · Lesson 5.4

The Team Harness

The harness is a shared team asset, not personal config: commit it so everyone - and every agent - inherits the same earned rules.

Chapter 0 · Sprint Zero
Chapter 1 · The ratchet & the practice loop
Chapter 2 · Spec-driven development in depth
Chapter 3 · Scaling & trusting the harness
Chapter 4 · Measuring & evolving the harness
5.1 · When to add a second agent
5.2 · Orchestration patterns
5.3 · Worktrees & parallel isolation
5.4 · The team harness
5.5 · Fighting drift & governance

The shift

Every lesson so far has quietly treated the harness as yours - your rules file, your hooks, your skills, all tuned on your laptop. On a solo project that is fine. On a team it breaks down. If the harness lives only on your machine, every teammate's agent behaves differently, and every failure you ratcheted into a rule stays trapped where you sit. Nobody else gets the benefit, and the same mistakes keep resurfacing on the next person's screen.

The fix is a team harness: the same scaffolding - rules, hooks, and skills - shared by everyone on the project instead of reinvented per developer. It turns the harness from personal config into a shared team asset.

How: commit it

Making the harness shared is not complicated - you commit it. The rules file (CLAUDE.md or AGENTS.md, from Lesson 1.2), the skills, and the hooks all go into version control, next to the code, like any other project asset. They travel with the repo, get reviewed in pull requests, and change through the same history as the code they guard. Addy Osmani frames the harness as a first-class artifact you version and evolve deliberately, not a personal setup you configure once and forget.

Your harness belongs in the repo, not your dotfiles. The team-harness principle - see Osmani, Agent Harness Engineering

The payoff: onboarding

A new developer clones the repo and instantly inherits the entire earned harness. Every failure the team ever ratcheted into a rule or a hook now protects them from their first commit - no wiki to read, no mentor explaining tribal knowledge. The scaffolding that took the team months to earn is theirs the moment the clone finishes.

The payoff: consistency

And it holds the team together as it grows. Every teammate's agent obeys the same rules and runs the same checks, so agent output is consistent across the team instead of drifting per laptop. Improvements compound for everyone at once: one person fixes a real failure, commits the rule or hook, and the next pull protects the whole team - one person's fix helps all. Simon Willison's collection of agentic engineering patterns makes the same point - the durable wins live in shared, versioned scaffolding, not in one person's private prompting habits.

Make it a team asset

Commit the rules file (CLAUDE.md / AGENTS.md) so it travels with the repo.
Commit the hooks so everyone's agent runs the same checks, every time.
Commit the skills so the earned workflows are shared, not re-derived.
New hires inherit it on clone - the harness arrives with the code.
One fix helps everyone - a ratcheted rule protects the whole team on the next pull.

Check yourself

A team harness means that -

A team harness is the scaffolding committed to the repo so every teammate - and every agent - inherits the same earned rules, hooks, and skills. It is a shared asset, not per-laptop config.

Your harness should live -

The rules file, hooks, and skills belong in version control next to the code, like any other project asset - not in one developer's personal or global config where teammates never see them.

A new hire on clone -

Because the harness is committed, every failure the team ratcheted into a rule or hook protects the new hire from their first commit - no wiki, no mentor, no tribal knowledge to absorb first.

Do this now (5 min)

Check whether your agent's rules file and hooks are committed to the repo (shared with the team) or living only in your personal or global config. Ask for each one: if a teammate cloned this repo right now, would they get it?

If the answer is no and the rule or hook is genuinely project-wide, that is step one - move the shared ones into the repo so the whole team, and their agents, pick them up on the next pull.

I'm your teacher - ask freely. Not sure which parts of your harness are safe to commit versus genuinely personal? Tell me what's in your rules file and your dotfiles and I'll help you split the shared, earned rules from the machine-specific noise.

Go deeper

Primary source (read this): Addy Osmani - Agent Harness Engineering. The case for the harness as a versioned, first-class artifact rather than personal setup.

Secondary (patterns): Simon Willison - agentic engineering patterns. Practical patterns for scaffolding that a team shares and reuses.

Wisdom (test it on people): the HumanLayer community is a good place to pressure-test what belongs in a shared harness versus what stays personal.

← 5.3 Worktrees & parallel isolation Course map Glossary Next: 5.5 Fighting drift & governance →