Give the agent a component ownership map, not the whole monorepo

I used to dump half the monorepo into the agent context and hope for a clean Button tweak. What I got back was a PR that “fixed” the button and quietly renamed a shared hook three packages away, touched a Storybook config I didn’t open, and “aligned” prop names in a sibling feature nobody asked about.

The agent wasn’t being evil. It just had no map of who owns what. Without boundaries, every file it can see looks like fair game.

So I stopped pasting the world. I give it a component ownership map — a short, boring file that says which surfaces it may edit, which packages are read-only for this task, and who to ask (or leave alone) when something crosses a boundary.

What the map actually is

Not a full CODEOWNERS dump. A task-scoped cheat sheet, usually under 40 lines:

## Ownership for this task (Button density in `@acme/ui`)

### You may edit
- packages/ui/src/Button/**
- packages/ui/src/Button.stories.tsx
- packages/ui/src/__tests__/Button*

### Read-only (do not modify)
- packages/ui/src/theme/**          # design tokens — separate RFC
- packages/forms/**                 # owns field wrappers; open an issue if Button API blocks them
- apps/web/**                       # consumers; do not “fix” app call sites unless asked

### Ask / stop if you need to change
- packages/ui/src/IconButton/**     # sibling; share styles via tokens, don’t fork Button internals
- packages/ui/package.json exports  # public API — needs human review before expanding

### Out of scope
- Renames that ripple past Button
- New peer dependencies
- “While I’m here” cleanups in shared utils

That’s it. Ownership in plain language the model can follow before it starts rewriting.

Why “here’s the monorepo” fails

Agents are opportunistic. If SharedPressable is one import away and looks “cleaner,” they’ll refactor it mid-task. If apps/web has a local Button fork, they’ll “consolidate.” If theme tokens feel inconsistent, they’ll invent a one-off.

All of that is rational when the prompt is “improve Button density” and the context window is full of unrelated packages. The ownership map makes those moves explicitly illegal for this PR, so the model has to ask or stop instead of shipping a blast-radius surprise.

How I attach it to every agent UI task

1. Paste the map in the task — not as a link they might skip; inline in the prompt.
2. Repeat the edit list in the acceptance criteria — “diff may only touch paths under You may edit.”
3. CI / review check — git diff --name-only against the allowlist. Anything outside → reject, no debate.
4. Update the map when ownership changes — when Forms truly needs a Button API change, widen the map for that PR; don’t leave a permanent “edit anything in ui/” hole.

I keep a template in the repo (docs/agent-ownership-map.template.md) and fill the three lists per ticket. Takes two minutes. Saves an afternoon of untangling drive-by refactors.

What I reject on sight

• Diffs that touch theme/ on a component-only ticket
• “Helpful” renames in packages/shared to make Button imports prettier
• App call-site rewrites when the task was library-only
• New exports / package.json changes buried under a visual tweak
• Storybook global config edits to make one story look right

I’ll take a patch that stays inside Button/** over a “cleaner” PR that rewires three packages.

Tiny prompt add-on that helps

Before editing: list every file you plan to change and map each to a row in the ownership map.
If a needed change has no “You may edit” row, stop and ask — do not invent ownership.
Do not mark done if `git diff --name-only` includes paths outside the allowlist.

When the agent lists the file plan first, you catch scope creep before tokens get spent on the wrong tree.

Tiny habit

Next monorepo agent task: don’t paste “the relevant packages.” Paste a map with may edit / read-only / ask / out of scope. Then enforce it with a path allowlist on the PR.

Agents are good at local edits. They’re bad at knowing which walls are load-bearing. The ownership map is the wall diagram — so they stop remodeling the neighbor’s kitchen while fixing your sink.