See what breaks before you build

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.

OpenAI and Anthropic both make the same practical point in their guidance: 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

1. 01
   User outcome 🎯

   Who needs the change, what situation triggers it, and what should become easier or possible?

2. 02
   State transition 🔄

   What state exists before the action, what state exists after it, and can the action be reversed?

3. 03
   Source of truth 📍

   Which model, service, document, or API owns the meaning of this concept?

4. 04
   Dependency map 🕸️

   Which contracts, consumers, flows, permissions, and operational processes rely on the current behavior?

5. 05
   Invariants and guardrails 🛡️

   Which conditions must remain true, including security, privacy, billing, and data-integrity rules?

6. 06
   Acceptance 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

Suppose you ask an agent to rename the plan status “Draft” to “Exploring.” A text replacement is obviously risky, but even a careful enum migration may be too much.

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. 1. Write the change as a state transition.

   Describe what becomes true after the change, not only which component will be edited.

2. 2. Inventory the touchpoints.

   Map schema, API, application state, UI, authentication, analytics, notifications, documentation, and external consumers.

3. 3. Trace contracts in both directions.

   Identify what the changed element depends on and what depends on it.

4. 4. Mark risk and reversibility.

   Separate read-only from write actions, local from public contracts, and reversible from destructive transitions.

5. 5. Define synchronized changes.

   List the files, services, types, migrations, tests, and communication that must land together.

6. 6. Trace failure boundaries.

   Cover the main path, permissions, partial failure, stale data, retries, cancellation, and rollback.

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.

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.

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.
• 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.

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.