Architecture · System Architecture

How to give coding agents the right repository context

When agents edit the wrong package, the failure is often missing local ownership rules. This note shows a small handbook layout, one worked task, and how precedence should work.

3 min read · Updated 2026-07-08

Reader takeaway

A minimal handbook layout with example AGENTS.md excerpts
One worked task that stays in the right package tree
How root hard rules and local ownership should resolve

Wrong tree, confident patch

Illustrative failure: you ask an agent to fix a checkout bug in a monorepo. It copies patterns from packages/ads, invents a helper that checkout never had, or edits a shared library because the root readme only listed package names. One common cause is that nothing near the task stated what checkout owns and what it must not touch. Missing context is not the only cause (bad prompts and stale code still fail), but it is a fixable one.

Status: practical repository pattern. Not a measured before-and-after study. Use it to reduce ambiguity, not to claim agents will never invent APIs.

A minimal layout with real content

Keep three kinds of files short and findable:

AGENTS.md                          # root: org, hard rules
packages/checkout/AGENTS.md        # local ownership
.agents/skills/verify-preview/SKILL.md

Hypothetical root handbook (excerpt):

# AGENTS.md
- Packages: checkout (payments UI + intents), ads, rewards.
- Hard rules: no secrets in commits; do not edit production configs.
- For package work, read that package’s AGENTS.md before editing.

Hypothetical checkout handbook:

# packages/checkout/AGENTS.md
Owns: checkout UI, intent client, webhook consumer stubs.
Does not own: ad placement, rewards ledger, shared auth package.
No-gos: do not add payment rules inside packages/ads.
Verify: run pnpm --filter checkout test; attach preview URL.

Put durable ownership in handbooks. Put repeatable procedures in skills.

Root handbook pointing at skills and nested package handbooks — Closest handbook wins for local conventions. Root hard rules still apply.

Worked task: fix double-charge on retry

Task given to the agent: “Checkout charges twice when the user retries Pay. Fix it in checkout.”

With the handbooks above, a sensible path:

Read root AGENTS.md, then packages/checkout/AGENTS.md.
Stay in checkout: find the intent client; add or honor an idempotency key on POST /intents.
Do not open packages/ads for a “shared retry helper” unless the handbook says ads owns that path.
Run the package verify step; stop if tests fail.

Without local ownership text, the same task often becomes a speculative shared helper in the wrong tree. The handbook does not guarantee a correct fix. It makes the correct tree and stop condition legible.

Precedence and a first step

For a task in packages/checkout, read root, then the closest package handbook, then any skill those files name. Local detail wins for package conventions. Root hard rules win when they forbid an action.

Someone must own each handbook. When a boundary changes, update the closest handbook in the same change as the code. First step: pick one boundary agents already get wrong, write ten lines of ownership and no-gos, run the same task again, and expand only after edits stay in the right tree.