Rule
Map first: read the code that owns the behavior, find the existing patterns, name the risks, before anything is built. Then pave: turn what the map found into instructions files, contracts, and tests — a surface later agents can drive on without rediscovering the terrain.
Paving beats model quality. Public reports from one large open-source repository found that adding a repo instructions file roughly doubled an agent's task success rate — from about 38% to 69% — with no model change at all. Written-down conventions, machine-checkable contracts, and tests are cheaper than intelligence, and they don't reset when the session ends.
What AgentOps Enforces
- Read the files that own the behavior before changing it; search for existing patterns before adding new ones.
- Identify the validation commands before implementation begins.
- Write findings into repo instructions, contracts, and tests — not just into the current session.
- Treat every mapped trap as a paving candidate: if an agent fell in once, put a rail there.
Failure Signal
- The patch duplicates a helper that already exists.
- The agent says "I assume" when the repo can answer the question.
- The same terrain gets re-researched every session because nothing was written down.
- Conventions live in one person's head and surprise every new agent.
Done Looks Like
Before editing, the agent can name the owner files, the local pattern, the risk, and the proof command — and what it learned is paved into files the next agent inherits.