What a subagent actually is

A second conversation, started by the first, given one job and a boundary.

It cannot see your conversation. It gets the instruction it was handed, does the work, and reports back. That is the whole idea.

Why that separation is the point

You have been reading everything it reads. Fifty files inspected to answer one question, and all fifty are now sitting in your session, crowding out the thing you actually care about.

A subagent does the reading in its own head and hands you the conclusion. You get the answer without the pile.

What that looks like in your work

"Look through every project folder and tell me which ones are missing a delivery spec. Do not change anything."

Four of those can run at once across four archives, and you get four reports.

Nothing collided, because nothing wrote.

Two hands on the same project file

This is the real failure from Module 10 of the main course, and it is the reason this deck exists.

Two processes pointed at one editing application at the same time, to go faster.

Nothing errored. Nothing warned. Days later a timeline was missing shots that had definitely been cut.

Why it fails silently

An application that holds your project in memory writes it when it feels like it.

Two things driving it do not crash into each other loudly. The second one saves its version of reality over the first one's, and both of them report success, because from where each was standing everything worked.

The lock, in one sentence

If a thing can only be safely used by one process at a time, make it impossible for a second one to start, rather than remembering not to.

Your studio ships a lock for exactly this. The principle generalises: a rule you have to remember under pressure is not a safety measure.

The other reason to stay with one

Running four agents costs roughly four times the tokens and gives you breadth, not reliability.

Default to one. Reach for more when the work genuinely splits into independent pieces.

Where they live

my-film/
  .claude/
    agents/
      dailies-logger.md
      delivery-checker.md

One file per agent, and it is just a description of a role, written in plain English, the same way you would brief a person.

What a good brief contains

---
name: delivery-checker
description: Checks deliverables against their spec. Read only.
---

You check finished exports against the spec files in `delivery/`.

For every file: duration, resolution, aspect, codec, loudness.
Report a table, one row per deliverable, pass or fail per column.

You never fix anything. You never re-export. You report.
If a spec is missing, say MISSING. Do not infer it.

"You never fix anything" is the most important line in it. A boundary stated is a boundary kept.

One task and one boundary per brief

Anything vague gets interpreted, and you will not be there when it is.

Model choice is about recoverability

Use the strongest model for work that would be expensive to get wrong. Use a cheaper, faster one for mechanical work.

A file inventory is not hard, but a wrong one sends you looking in the wrong place for an hour. An audit is where you spend the good model, always.

Verify by id, before and after

When agents touch things, the report is not the evidence.

"Before you start, list the ids of everything you are about to touch. Afterwards, list them again with what changed. Show me both."

Then compare the two lists yourself. This catches the failure where something worked perfectly on the wrong target, which is the one no success message will ever reveal.

The exercise

Twenty minutes. Read-only work only, on purpose.

1. *"Write me an agent that checks deliverables against their specs and only reports. It must never

fix anything."*

1. Read the file. Find the sentence that stops it writing. If there is not one, add it.
2. Run it on a finished project. Read the table.
3. *"Now write one that inventories a folder of generations and reports what is unmatched to a

log."* Same rule: reports only.

1. Run both at once on different folders. Notice nothing collides.
2. Ask yourself which of your tools holds state, then write down: **that one is single writer,

always.**

1. Put that in your CLAUDE.md as one line.

What you should have now

• Two agents that read and report and cannot write
• The habit of writing the boundary into the brief, because you cannot say it later
• One named resource in your workflow marked single writer, in writing
• The knowledge that more agents buys breadth, never reliability
• A verify-by-id habit for anything that touches real files

You can hand off the reading. You still hold the pen.