A year of AI coding / 04
Longer agent runs need better briefs
Long-running coding tasks need explicit acceptance criteria, limits, and checkpoints so persistence does not magnify an early misunderstanding.
By Grafty team · · 3 min read
Written in .
"Update the authentication code" is an instruction you might give a colleague who already knows the project. For an agent that can continue working across many files, it leaves a lot of room for interpretation.
Does update mean replace the session library, add a provider, or fix a redirect? Can the agent change cookie behavior? Should existing sessions survive deployment? The longer the task runs before someone checks those assumptions, the larger the potential correction.
OpenAI's November 13, 2025 release of GPT-5.1-Codex and GPT-5.1-Codex-Mini emphasized long-running agentic coding. The official changelog records the release. That emphasis brought a familiar engineering issue into sharper focus: delegating a larger unit of work requires a more explicit agreement about the result.
Open full-size diagram Describe the observable behavior
A useful brief does not need to prescribe every function the agent should write. It needs to define what the finished change must do and what must remain unchanged.
Before delegating an authentication migration, we would want the brief to answer these questions:
- Which login methods must still work?
- What should happen to an existing session?
- Which origins and redirect destinations are allowed?
- How will staging verify the failure paths?
- Which files or systems are outside the task?
Those answers constrain the result without dictating the implementation. The agent still has room to inspect the repository and choose an approach.
Include a checkpoint when the next action would make the work harder to reverse. Changing a session format, for example, deserves review before the agent also rewrites every consumer. A small initial diff can expose a bad assumption early.
The brief should name a stop condition for missing information. If the current provider configuration is inaccessible, the agent should report that limit rather than invent a replacement configuration and build around it. Persistence is useful only while the task remains well defined.
Open full-size diagram Keep the brief available during execution
Long tasks produce a lot of intermediate information. Plans change, commands fail, and some context may be summarized. Important constraints should live in a durable task record that can be checked again, not only in the first message of a long conversation.
We would keep the acceptance criteria close to the repository or issue and ask for the final verification to refer back to them. "Tests passed" is too broad. Which tests establish that old sessions still work? Which check rejects a redirect to an unapproved domain? What was not tested?
Permissions should match the brief as well. A task to change application code does not require production administrator access. Keeping the worker's access narrow makes an ambiguous instruction less dangerous and clarifies when a human decision is needed.
There is a cost to writing a better brief, and it should be proportional to the change. A text correction does not need a design document. A cross-service migration probably needs more than a sentence. The aim is to remove expensive ambiguity, not to create paperwork for every edit.
As agents take on longer tasks, we expect more engineering effort to move into specifying behavior and inspecting evidence. The brief becomes part of the implementation system. If it is unclear, the agent can work very hard and still deliver the wrong thing.