How to give AI coding agents real product context

The expensive failure is plausible, reviewed, well-tested code built around a product decision nobody made. Product context is the current decision, its evidence, boundaries, and proof of done; a decision packet is the short, versioned handoff that makes it usable.

Coding agents can inspect a ticket, search a repository, and read designs. That is retrieval. When those artifacts disagree, the agent still has to choose. A longer prompt can hide the fact that the team has delegated a product decision to implementation.

Use a decision packet for consequential work: a short, versioned statement of what is true now, why it is true, what must not change, and how a reviewer will know the change is right. It gives an engineer or an agent enough authority to implement without inventing policy.

Product context and context engineering solve different problems

Context engineering concerns what information an agent can retrieve, fit, and use reliably. Product context settles the product decision that retrieval cannot settle when a ticket, design, and older roadmap point in different directions. Both matter. This guide addresses the handoff from the person who owns the decision to the person or agent who implements it. For the retrieval side, see Martin Fowler's context-engineering discussion for coding agents.

Test the decision before assigning the task

Suppose a B2B product wants “team workspaces.” The ticket says “add a workspace switcher.” A Figma frame shows a new item in the sidebar. A six-month-old roadmap says billing follows the workspace. Three recent interviews say consultants need to move between client spaces while keeping personal drafts private.

An agent can find all of that. It cannot know whether “workspace” means a billing entity, an authorization boundary, or a navigation convenience. If it chooses the first interpretation, it may produce a perfectly coherent migration that makes the interviews impossible to honor.

Before assigning the task, ask whether the implementer can explain which user outcome wins when two reasonable choices conflict. If they cannot, the work is under-specified.

A worked packet: adding workspace switching without leaking projects

This illustrative composite packet stays small. Linked evidence remains available without becoming required reading.

# Decision: active workspace

Status: confirmed • Owner: product owner • Date: <decision date>
Supersedes: <earlier decision, if any>

Decision
A signed-in person may belong to several workspaces and choose one active
workspace. Switching changes the projects they can browse; it does not change
their account, role, or billing plan.

Why
Interview synthesis: consultants must move between client spaces.
They must not see one client’s projects while working in another. Personal
projects remain personal.

Non-negotiables
- Every project read and mutation is scoped to active_workspace_id server-side.
- Switching cannot discard an unsaved editor draft.
- Existing personal projects and URLs retain their behavior.
- Billing, invitations, and cross-workspace project sharing are out of scope.

Open implementation choice
Store active_workspace_id in the signed session or in a signed cookie. Choose
the option that preserves server-side authorization and document the reason.

Relevant surfaces
apps/web/middleware.ts; project query service; editor draft store; sidebar.

Acceptance evidence
1. A member of A and B sees only A’s projects after selecting A.
2. Direct navigation to a B project while A is active is denied.
3. Switching A → B leaves a dirty draft recoverable.
4. A user with no workspace still sees personal projects.

The first draft of this feature often puts activeWorkspaceId in local storage because the sidebar needs it. The packet makes the defect visible: the browser preference may drive the interface, but authorization must be made on the server. It also prevents an apparently helpful expansion into billing work.

After implementation, ask the agent for a short decision trace: which files enforced each non-negotiable, which acceptance checks it ran, and which open choice it made. That is more useful than asking it to repeat its plan.

The reusable packet template

Copy this for a task that crosses files, teams, or a product boundary. For a one-line typo, it is needless ceremony.

# Decision: <plain-language outcome>

Status: proposed | confirmed | superseded
Owner: <person who can resolve ambiguity>
Date: <YYYY-MM-DD> • Replaces: <link, or “none”>

Decision

Why now

Non-negotiables
- <authorization, data, compatibility, policy, or UX boundary>
- <another boundary>

Explicitly not included
- <tempting adjacent work>

Open choices
- <implementation choice and its decision criterion>

Relevant surfaces
<paths, services, contracts, and designs; avoid a repository dump>

Acceptance evidence
1. <observable behavior or test>
2. <negative case>
3. <migration/compatibility case if applicable>

Write “supersedes” when an earlier decision exists. A visible replacement tells a future implementer that the older document was considered rather than overlooked.

The packet governs a product decision; a repository instruction file governs how tools work in the codebase. A product spec can carry the decision into a larger implementation and learning plan. If your team needs a home for shared context, start with what a context layer holds.

Review the packet before the code

Use this rubric in a short handoff review. Score each item yes or no. A “no” identifies a decision that still needs a human owner.

Three ways this fails in practice

The packet becomes a transcript

Teams paste interview notes, Slack threads, and a full design export into “context.” The agent then has more material and no hierarchy. Keep the source linked; include only the interpretation that affects the decision. If a reviewer cannot read the packet in a few minutes, split the task or resolve the decision first.

Acceptance checks only describe the happy path

“A workspace switcher appears” does not test the boundary the feature exists to protect. Add an unauthorized direct URL, a stale session, a migration case, or another negative example. Agents are capable of making a button appear; the packet should teach them what must remain impossible.

The packet is treated as immutable after discovery

An engineer may discover that the proposed session model cannot preserve a draft safely. Record the finding, return to the named owner, and either make a replacement decision or split the delivery. A packet creates a visible place for that conversation and leaves room for new information.

A handoff protocol

Send the task with the packet, the relevant surfaces, and a bounded request: first identify conflicts, then propose an implementation plan, then make the change. Require the agent to call out any instruction it cannot reconcile. This sequence is valuable even when the eventual implementer is human, because it tests whether the decision survives contact with the codebase.

At review, trace where the authorization boundary is enforced, where compatibility is protected, and which test proves the negative case. If the code needs a policy absent from the packet, pause for a decision.

Packets can live in an issue, a decision log, or alongside a spec. Choose one canonical location and link it from the task. Copies in chat are a common source of stale authority. A dated packet with a replacement link is more reliable than a polished document whose reader cannot tell whether it still governs the work.

When a packet is overhead

Do not write one for formatting, a local refactor with unchanged behavior, or a defect whose expected behavior is already captured by a failing test. Do write one when the task changes data ownership, permissions, customer-visible behavior, pricing, compatibility, or a decision a reviewer might reasonably challenge.

The method cannot settle a live disagreement. If product says “private by default” and sales says “share by default,” stop implementation and obtain a decision.

Put it to work

Pick an upcoming change with a real boundary: a permission, a migration, an irreversible interaction, or a product tier. Draft the packet with the owner, give the agent the packet and relevant code surfaces, then review the change against the acceptance evidence. Record every conflict the agent finds before implementation begins.