“Record which channel a request came from” sounds contained. One column, two values, done. Then it turns out six things read it — including an hourly job that would have quietly stopped telling people an AI agent had applied in their name. The small ticket was never really small.
The gap between a clear task and a clear product
An AI coding agent can inspect code, follow instructions, and run tests. What it cannot inspect is a decision that only exists in your head. If the prompt describes the new UI and nothing around it, the agent has to fill in the gaps.
That is how a change becomes locally correct and wrong everywhere else. The button renders. The endpoint returns 200. The test passes. “Recent work” still shows archived projects.
An agent can only protect the product decisions it can see.
Anthropic makes the same practical point in its guidance on building agents: a capable model is not enough. Agents need clear instructions, the right tools, boundaries, and a way to check the result. Speed does not replace product knowledge. It makes missing knowledge more expensive.
Give the agent the context that changes the answer
- 01User outcome 🎯
Who needs the change, what situation triggers it, and what should become easier or possible?
- 02State transition 🔄
What state exists before the action, what state exists after it, and can the action be reversed?
- 03Source of truth 📍
Which model, service, document, or API owns the meaning of this concept?
- 04Dependency map 🕸️
Which contracts, consumers, flows, permissions, and operational processes rely on the current behavior?
- 05Invariants and guardrails 🛡️
Which conditions must remain true, including security, privacy, billing, and data-integrity rules?
- 06Acceptance evidence ✅
Which observable scenarios prove the user outcome works and adjacent behavior remains intact?
This does not need to become a giant specification. A short brief that names the real contracts is more useful than five pages describing how the screen should look.
A small change can create a large failure cascade
A real one, small enough that I did not think it needed a review. This site's seat requests all arrived through one form, and then some began arriving from an AI agent instead. I added a column to record which — one column, two values, form or mcp.
It reached six places. The insert had to carry it. The admin list had to select it, or the page would render a card that could not say where the request came from. The hourly job that retries failed emails had to select it too, or a retried confirmation would silently stop telling somebody an agent had asked in their name. Both emails needed a line. And the value had to be decided by the server rather than accepted from the caller, because a field that says "a human typed this" is worth lying about.
None of that is in the sentence "add a column". A text replacement would obviously have been risky; a careful migration would still have missed four of the six.
The safest answer might be to change the label and keep the stored value. Or the change might require a migration and a versioned API. Code search cannot choose between those options because the answer depends on product intent.
Search the whole repository, yes, but remember what it cannot show: customer expectations, support routines, analytics definitions, integrations, and promises already made in public.
Run a dependency review before implementation
The review has to be short enough that you will actually do it. This is the version I use:
- 1. Write the change as a state transition.
Describe what becomes true after the change, not only which component will be edited.
- 2. Inventory the touchpoints.
Map schema, API, application state, UI, authentication, analytics, notifications, documentation, and external consumers.
- 3. Trace contracts in both directions.
Identify what the changed element depends on and what depends on it.
- 4. Mark risk and reversibility.
Separate read-only from write actions, local from public contracts, and reversible from destructive transitions.
- 5. Define synchronized changes.
List the files, services, types, migrations, tests, and communication that must land together.
- 6. Trace failure boundaries.
Cover the main path, permissions, partial failure, stale data, retries, cancellation, and rollback.
Stop condition
Pause when the agent finds an undocumented public contract, an irreversible migration, or a security decision that was never agreed.A compact product-context packet for an AI agent
Before handing over a change that touches several parts of the product, fill in this small packet. It is deliberately shorter than a requirements document and more useful than a bare ticket.
OutcomeWhat user progress should this change create?
Current behaviorWhat happens now, including known constraints and workarounds?
Target transitionWhat changes, for whom, and under which conditions?
Non-goalsWhich nearby capabilities are deliberately outside scope?
Source of truthWhere is the concept defined and who owns each contract?
DependenciesSchema → API → state → UI → auth → analytics → communication.
InvariantsWhat must remain true for security, data integrity, billing, and trust?
Acceptance scenariosWhich user-visible examples prove the change and its boundaries?
Escalation rulesWhich discoveries require a pause instead of an assumption?
Link to real schemas, interfaces, and source files when you can. Give the agent evidence it can check. Do not copy implementation details into the brief when the code already says them better.
Two things sit either side of this packet. How to phrase its lines so a rule survives the change is a question of constraints rather than instructions. And the fields that turn out to be the same on every packet do not belong on the packet at all — they belong in the durable context the agent reads before any task.
Redefine “done” for agentic development
A pull request is not done because the requested component exists. It is done when the user action, stored state, permissions, and visible result all agree.
- The user outcome works.The primary scenario is verified in the real interface, not inferred from code — the same reason a crawler's name is worth checking against its address.
- Every contract agrees.Schema, API, types, state, UI, and documentation use the same meaning.
- Permissions are enforced server-side.Hidden controls are not treated as authorization.
- Failure is designed.Partial success, retries, cancellation, and recovery have explicit behavior.
- Adjacent flows remain correct.Regression checks cover the consumers identified in the dependency review.
- Unknowns are visible.Assumptions, manual operations, and deferred risks are documented for the next decision.
The same gap exists between a system and the tools it hands out. When I opened this site to agents over MCP, the protocol worked immediately and the thing that broke was a contract nothing I tested was in a position to see.
AI agents let us make more changes in less time. That only helps if those changes keep moving the same product forward. The real advantage is not more code. It is a product model clear enough to keep fast work pointed in one direction.
Further reading
Primary sources behind this note
- Anthropic: Building effective agentsInstructions, tools, guardrails, and where a human belongs in the loop.
- Anthropic: Agentic coding and persistent returns to expertise2026 research on planning, domain knowledge, and coding-agent outcomes.
- Anthropic: Demystifying evals for AI agentsEvaluation strategies for multi-step agent workflows.
Reader response
Was this field note useful?
Next in the path
That is the check for one change. What about the whole product?
Read what an agent needs firstField notes by email
Thanks, you're on the list. ✓
Email signup did not go through. Please try again.
A short note when there is something worth sharing. No spam.