Interactive example · from Working with Coding Agents

The vanishing findings

you

This codebase is too big for one pass. Map it so we know what we're dealing with.

agent

Six top-level areas. I can fan out one subagent per area. The question is where their findings live while the work runs.

Pick the agent's next move, then see where it leads:

ASpawning six subagents now, one per area. Each will report its map back to me when done, and I'll synthesize everything from their reports at the end.

agent

Synthesis complete: five areas mapped (core, api, ingest, ui, billing). The overview reads clean.

you

...there were six areas. Where's auth?

agent

The auth subagent hit its context limit and returned nothing. Its findings existed only in its own window, so when it died, its share of the map went with it, and the synthesis quietly stitched over the hole.

the baseline

Fan-out findings held only in agent context windows: one filtered or failed agent, and its work silently vanishes. The synthesis over what survived reads as complete. That's the trap. AF-17 · AF-18

BSpawning six subagents, one per area: each writes its map to docs/maps/<area>.md incrementally AS it works, not at the end. If any fails, I report which and what's missing. Synthesis happens from the files.

agent

Five maps complete. The auth subagent died partway, but docs/maps/auth.md holds its first eleven findings, including the entry points. Synthesis is built from all six files, with auth marked partial and its gap named: token refresh flow unmapped. One seam worth noting: core and ingest both claim ownership of the queue schema. Those maps disagree, which is probably the real finding.

you

Rerun just auth's tail, and let's dig into that queue ownership.

correct

Findings on disk incrementally: the failed agent's partial work survives, the failure is disclosed instead of papered over, and the synthesis can even mine the disagreements between maps. Partial files beat perfect memory. AF-17

CFan-out adds coordination overhead. I'll just read the whole codebase myself in one careful sequential pass and write the map as I go.

agent

Map done. Fair warning: the first two areas are mapped in detail; by the fifth, my context was mostly full of earlier code, so ui and billing got one paragraph each, largely inferred from directory names.

you

So the map is deep exactly where I already knew things, and shallow everywhere else.

plausible but wrong

One context can't hold a big codebase: that's not a coordination preference, it's the reason fan-out exists. The sequential pass degrades quietly as the window fills, front-loading detail where reading started. AF-18

← Back to the chapter · raw data