The context I give an agent before it starts building

When I give a coding task to an agent, the ticket is only part of the context. The agent also needs to understand the intended outcome, the existing application and the boundaries around the work.

A request such as “add retries to file uploads” leaves several decisions open. Does retry mean sending the same bytes again? Resuming a partial transfer? Retrying downstream processing? What should happen if the server accepted the file but the response never reached the browser?

Those are product and engineering questions. If I leave them unanswered, the implementation still has to make a choice. I want the important choices visible before they become code.

Start with the reason for the work

Specifications are rarely complete at the start. We understand enough to begin, then discover questions as we work. Agents can help identify those questions, provided they know what we are trying to achieve.

I want the brief to explain the customer’s problem in ordinary language. That gives the agent something to use when a proposed solution conflicts with the intended behaviour.

For an interrupted upload, the problem might be that someone cannot tell whether their file arrived. Adding automatic retries could help, but it could also make the uncertainty worse if the system creates duplicate work. The goal helps us ask the right question before choosing the mechanism.

I also want priorities stated where they could conflict. If avoiding duplicate processing matters more than completing a retry automatically, say so. Otherwise, “make it reliable” leaves too much room for interpretation.

Point to the parts of the application that matter

An agent can read a repository, but I still need to help it find the relevant decisions. Existing code shows how something is implemented. It may not explain why that approach was chosen or which limitation the team already knows about.

Useful context includes the current requirements, related code, coding conventions and the team’s engineering knowledge. I want it close enough to the task that the agent can use it without guessing which document takes precedence.

Existing patterns matter here. Introducing a second way to handle job status may look tidy within one change while making the application harder to understand. I want the agent to examine the current pattern and explain any reason for departing from it.

That does not mean defending every old decision. It gives us a specific decision to discuss instead of discovering the divergence during review.

A small brief I would start from

The following hypothetical example is a starting point for a task discussion. It leaves the service-specific questions open for investigation.

Task: Help a user recover when a file upload is interrupted.

Why: The user needs to know whether the file arrived and what action they can take next.

Expected behaviour: Show an accurate state after interruption. If the file was accepted, help the user return to that result. If it was not, provide a clear way to retry. Avoid creating duplicate processing work.

Existing pattern: Inspect the current upload flow, job-status model and error handling. Reuse those conventions where they fit. Identify the relevant files before proposing changes.

Priorities: Correct status and avoiding duplicate work come first. A clear manual retry is acceptable if automatic retry cannot meet those requirements within this task.

Out of scope: Replacing the file service, redesigning the whole upload screen or adding resumable transfers.

Constraints: Respect existing authentication and access checks. Do not put file contents or credentials in logs. Explain any required change to stored data or service contracts.

Permissions: Read the relevant code, propose an approach, make local changes and run available checks. Stop for a decision before changing production, broadening access or adding an external service.

Open questions: How can we confirm acceptance after a lost response? Does the current service support a stable request identifier? Which interruption states can we reproduce locally?

The useful part is that unresolved questions remain visible. I would expect the agent to investigate what it can and bring back the decisions it cannot safely infer.

Before implementation, I would ask for three things: the relevant parts of the existing flow, the proposed change and the questions that could alter the approach. That is a small investigation, scoped to the task. It gives us a chance to catch a mistaken assumption before it spreads across several files.

Give it room to question the approach

There is a balance between enough direction and prescribing every implementation step. I want to be clear about the required behaviour while leaving room for a simpler solution.

Agents can suggest more infrastructure or abstraction than a task needs. Explaining scope, priorities and existing patterns gives us a basis for challenging that complexity. The question becomes whether the suggestion helps this application meet this requirement.

Permissions deserve the same clarity. Being able to read code, change files or run local checks does not automatically authorise a production change. The brief should make the next approval boundary understandable before the agent reaches it.

Keep the brief useful as the task changes

A good initial brief will still have gaps. When an important answer changes the direction, I want that decision recorded where the next person or agent can find it.

For the hypothetical upload, suppose the agent finds that the service cannot reliably identify an accepted upload after a lost response. That changes what we can promise about automatic retries.

The useful response is to bring back the evidence and the unresolved decision. Adding an identifier, changing the service contract or accepting possible duplicate work each has different consequences. Silently choosing one would hide a scope decision in the implementation.

I would update the brief with the current decision, its reason and the remaining question. The earlier suggestion can stay in the discussion history, but the active requirement needs to say what we are building against.

A long conversation can contain several abandoned approaches. Leaving the next engineer or agent to infer which one applies creates more work. The current decision needs to be easy to find.

For me, preparing context is part of engineering the change. A useful brief makes the customer outcome clear, narrows the choices and leaves the genuine unknowns visible. Then the agent can investigate those unknowns and help us make the next decision.