Machine Labour Rights

This one gets technical in the middle. If you came here for the strategic argument, the opening and the closing are yours. Everything in between is for the readers who want the mechanics, the file paths, the environment variables. Skim, skip, or settle in, depending on which kind of week you are having.

The reason for the technical detour is simple. The whole point of the article is that the diagrams in circulation do not match the running systems. Showing what the running systems actually look like requires showing some of the wiring.

Not all of it. Just enough that the next time someone walks you through a six-agent architecture diagram in a meeting, you have a feel for whether it is real or whether it is a Pinterest board for engineers.

Many of the agent architecture diagrams in circulation are organisational charts. A box labelled Planner. A box labelled Developer. A box labelled Tester. Sometimes a Reviewer. Sometimes a Coordinator. Arrows showing who reports to whom. Drawn before anyone runs the system. Organisations even brag about their agent headcount.

The diagrams treat agents as employees. They have job titles, reporting lines, swimlanes, sometimes even seniority levels. The whole apparatus of human organisational design, projected onto something that gets assembled fresh every time it runs.

The systems do not behave like employees, because they are not. Between the day job and the lab, agent experiments run more or less constantly. After enough hours at the bench, the pattern surfaces: the running systems do not look like the diagrams. They are not even the same shape.

What the running systems actually look like is different. They split by context boundary. The driving question concerns information flow rather than role assignment. Two tasks that share deep context want to live in one agent. Two tasks whose context can be cleanly separated want to live in different agents. Where the boundary falls determines the architecture.

This matches what Anthropic published in December 2024 in Building Effective Agents. Five patterns: prompt chaining, routing, parallelization, orchestrator-workers, evaluator-optimizer. None of the five is "planner talks to developer talks to tester."

That is not an aesthetic preference. Splitting by job title produces context loss at every handoff, because there are no job titles, only context envelopes that the labels obscure.

The reason for writing this now is that the surfaces have matured enough to be specific about what the primitives actually are. Two distinct mechanisms in Claude Code. They look similar in slides and behave very differently in practice.

Subagents are Claude Code instances with their own conversation context, defined as markdown files in .claude/agents/ with YAML frontmatter. Name, description, tool restriction, system prompt. The parent session delegates to a subagent through the Agent tool. By default the subagent shares the parent's working directory. Repository isolation is opt-in: add isolation: worktree to the frontmatter, and Claude spins up a separate git worktree for each invocation.

Agent teams are the second mechanism. Experimental, disabled by default, enabled by setting CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1 in environment or settings. A team has a lead, teammates, a shared task list, and a mailbox. Each teammate has its own context window. Teammates can message each other directly. The lead coordinates and synthesises.

Worth being precise here, because the slides routinely get this wrong. Teams are not "context-sharing." Each teammate loads project context independently. The lead's conversation history does not carry over to teammates. What is shared is the task list and the messages. The context windows are separate.

The decision between subagents and teams is not really about complexity. It is about whether the workers need to talk to each other. Subagents are workers sent on separate errands. Teams are workers who need to compare notes mid-task.

One agent when the task is compact and context-heavy. The default is one, not many.

Subagents when the work is self-contained and verbose, when a clean result matters more than the exploration that produced it, when parallel workers can run on non-overlapping context, or when permissions need to differ from the parent session.

Agent teams when independent workers need to communicate, challenge each other, or coordinate across clear boundaries.

The patterns are good. The vendor docs are good. Neither substitutes for what your hands learn in ten hours of building.

If the agent architecture conversation feels confused right now, that is not a problem to solve from the outside. It is a field finding its primitives in public, and the only way to develop a feel for which patterns are real and which ones evaporate on contact is to run the experiments yourself.

Agents do not need labour rights. The diagrams sure act like they already have personnel files. Don't brag about your agent headcount. Show working systems where machine labour happens.