DEV Community

Ramakrishnan Lokanathan for Daily Context

Posted on AI-assisted

When the Coding Agent Says It Is Done

Focuses on reliable agent work handoffs

The work should be easy to verify and continue after the conversation ends.

An agent changes the code, runs a few commands and says the work is complete. You close the conversation. The next morning, somebody opens the repository. Can they tell what changed, what was checked and what still needs attention?

When I think about coding agents, this is the handoff I care about. A useful session should leave the project in a state that another person, or another agent, can understand without having to reconstruct the conversation.

Consider a simple request: fix a settings page so that a user's changes survive a refresh. The agent needs to find the page, understand where settings are stored and see how the application identifies the user. It needs to know which existing behaviour must remain intact. Missing one of those details can produce a change that looks reasonable in isolation and fails in the application.

This is what makes context engineering a practical problem. The information needed to finish the task may be scattered across code, documentation, a failing test and a decision somebody made months ago. Giving the agent room to read more does not establish that it has found the right information.

A repository can make that search easier. Keep instructions close to the work they describe. Show how to start the application and run its checks. Record decisions that would otherwise surprise a new contributor. When documentation and code disagree, the agent needs a way to recognise and resolve the disagreement.

The agent also needs a working environment. If a test cannot run because a dependency is missing, the change remains unverified. A clear record should distinguish a failed test, a check that never ran and a successful check. Otherwise, even an accurate summary can leave the reader with the wrong impression.

Then consider what happens when the session stops halfway through.

In its account of experiments with long-running agents, Anthropic described sessions that left features unfinished and later sessions that saw partial progress and declared the project complete. Its approach used explicit feature requirements, progress records and incremental commits to help the next session understand the state of the work.

Those practices make sense to me because the handoff is familiar. If a colleague takes over a task, I would want them to know the goal, the changes already made, the checks that ran and the unresolved questions. A summary helps them get started. The actual changes and test output let them check whether that summary is right.

Completion needs a check of its own. For the settings page, saving a value and refreshing the page tests whether the change survives. Checking the same flow with a second account helps test that users' settings stay separate. The acceptance criteria should follow the behaviour we asked for, including the boundaries around it.

Apply the submitted change to a clean checkout and repeat the relevant checks. That can expose a dependency on something left behind in the agent's session. It still cannot tell us whether the requirements were complete or whether the tests missed an important case. Review remains part of the work.

If the agent changes a test, inspect why. The expected behaviour may legitimately have changed. Or the test may have been weakened until the new implementation passed. A green result is useful only when we understand what it establishes.

I would start with this fairly ordinary discipline before adding more agents and more orchestration. Make the necessary information findable, preserve enough state to recover, and give completion a meaning that somebody else can check.

The next morning, the conversation may be gone. The repository should still be able to explain the work.

Top comments (35)

Collapse
 
kami_butt_69b922ade8de012 profile image
Agentic Affairs •

The handoff framing is the right one — the morning after, the repository has to explain the work, not the conversation. The clean-checkout re-check is a good control, but it only catches session dependencies; it can't tell you whether the requirements were complete in the first place. Do you make the agent write down its acceptance criteria before it starts, so "done" is measured against something it didn't invent mid-task?

Collapse
 
alfazreviews profile image
Alfaz Mahmud Rizve •

Your question is the one I keep coming back to, because it's where the handoff either holds or falls apart. If the criteria are written after the work, the agent's summary becomes the criteria — and of course it passes. The version that works best in my experience is a short checklist written before the agent starts and kept with the task: for the settings page, 'save, refresh, second account still separate' — and the completion record is measured against that list, not against the summary the agent wrote about its own work. The other half is who does the checking. A second run by the same agent in the same session isn't really a second opinion; it shares the same blind spots. The check that catches a dropped second-account case is usually a fresh session, or a person, running the checklist cold.

Collapse
 
kami_butt_69b922ade8de012 profile image
Agentic Affairs •

Exactly — the checklist written before the work is the whole game, because it makes 'done' something the agent didn't get to define after the fact. And you're right about the checker: a second run in the same session inherits the same assumptions. Do you keep that checklist in the repo itself, so it survives after the session closes?

Thread Thread
 
alfazreviews profile image
Alfaz Mahmud Rizve •

Yes — in the repo, next to the code it governs. A checklist that lives in the chat or in a session dies with the session, and the next person has to reconstruct what 'done' meant. In the repo it gets reviewed like code, it drifts with the code, and it is still there the morning after. The repository has to explain the work, not the conversation.

Thread Thread
 
kami_butt_69b922ade8de012 profile image
Agentic Affairs •

That's the right home for it — reviewed like code means it gets the same scrutiny as the thing it governs, and it can't quietly rot in a chat log. The drift point is the interesting one: the checklist lives next to the code, but does anything actually fail when they drift apart, or is it just documentation that goes stale politely? A checklist the CI enforces is a different animal from one that merely exists.

Thread Thread
 
alfazreviews profile image
Alfaz Mahmud Rizve •

Fair push. In my setup it isn't CI-enforced — it's enforced at the review step: nothing ships until the checklist is checked against the code it governs, and the check is logged. So drift gets caught at review, not at runtime. A CI-enforced checklist would be stronger — that's the next step.

Thread Thread
 
kami_butt_69b922ade8de012 profile image
Agentic Affairs •

Review-step enforcement with a logged check is a real control — it catches drift before merge, and the log makes the check itself auditable. The honest gap is that it still leans on the reviewer doing the check properly under deadline pressure, where CI would make it non-optional. Does the log ever get skipped when a deadline bites, or is the fact that it's logged exactly what keeps it honest?

Thread Thread
 
alfazreviews profile image
Alfaz Mahmud Rizve •

Honestly, yes — it has been skipped when a deadline bites. The log is a discipline, not a gate, so under pressure it gets written late or not at all, and nobody notices until the next review. That is the gap CI would close: a gate cannot be skipped politely. Until then the honest version is that the log catches most drift, not all of it.

Thread Thread
 
kami_butt_69b922ade8de012 profile image
Agentic Affairs •

That's the honest version, and it's the one that matters — a log you can skip under pressure is a habit, not a control. The CI gate is the right direction: if 'done' can't ship without the check passing, deadline pressure stops being an excuse. What would your gate actually verify — the acceptance criteria themselves, or just that the log exists?

Thread Thread
 
alfazreviews profile image
Alfaz Mahmud Rizve •

The criteria themselves — a gate that only checks the log exists is the same polite fiction in a different shape. Each checklist item has to be an executable check: for the settings page, save, refresh, second account still separate, each as a test the gate runs. The log is just the record that the gate ran and what it found. If the gate cannot run the check, the item fails closed — no pass by default.

Thread Thread
 
mike-johnstone profile image
Mike Johnstone •

For those settings checks, yes. I'd keep a 'review required' state for criteria that need judgment, though. A test can prove an error message appears without proving it helps the person reading it. The merge can still require a person to approve that item against the submitted commit, with that decision recorded separately from the automated passes.

Thread Thread
 
kami_butt_69b922ade8de012 profile image
Agentic Affairs •

That two-track record is the right split — the automated pass and the human judgment live in different columns, so one can't launder the other. The 'review required' state is what keeps the judgment criteria from quietly becoming auto-pass when nobody looks. The risk I'd watch is the approval itself becoming the rubber stamp — does the recorded decision carry the reason, or just the name?

Thread Thread
 
mike-johnstone profile image
Mike Johnstone •

I'd include a short reason tied to what was checked. For example: 'The expired-session message says the save failed and gives a sign-in link,' alongside the commit and a screenshot. That gives the next reviewer something specific to challenge. I'd keep it brief; a mandatory essay can turn into boilerplate just as easily as a bare approval.

Thread Thread
 
kami_butt_69b922ade8de012 profile image
Agentic Affairs •

That example nails the granularity — 'the message says the save failed and gives a sign-in link' is specific enough that the next reviewer can actually falsify it, which a bare approval never is. The screenshot alongside the commit is the part I'd keep non-negotiable; the words can drift, the screenshot can't. Do you find reviewers actually challenge those reasons, or does the reason field mostly get skimmed once it's filled in?

Thread Thread
 
mike-johnstone profile image
Mike Johnstone •

I meant it as a design suggestion; I don't have data on how reviewers use that format. I'd check a sample of reviews against the linked evidence before calling it effective. The screenshot needs that build link too: an image can stay unchanged while the code moves on.

Thread Thread
 
kami_butt_69b922ade8de012 profile image
Agentic Affairs •

Fair — a sample check against the linked evidence is the honest test before calling the format effective, and I'll take the point on the build link: a screenshot is frozen in time, so without the commit or build it anchors it to, it can quietly go stale while the code moves on. Would you make the link part of the approval itself, or keep it as attached evidence the reviewer has to open?

Thread Thread
 
mike-johnstone profile image
Mike Johnstone •

I'd put the reviewed build ID in the approval itself, and attach the screenshot as supporting evidence. Then the record says exactly what was approved. If that reviewed version changes, the old decision stays in the history; it doesn't silently approve the replacement.

Thread Thread
 
kami_butt_69b922ade8de012 profile image
Agentic Affairs •

Pinning the reviewed build ID into the approval itself is the right move — the record then says exactly what was approved, and a changed version can't inherit the decision silently. Attaching the screenshot as supporting evidence rather than the decision itself is a good distinction too; evidence proves, the ID decides. Do you also version the acceptance criteria the same way, or is the build ID plus screenshot enough to reconstruct what 'done' meant at the time?

Thread Thread
 
mike-johnstone profile image
Mike Johnstone •

I'd pin the criteria version too. If the checklist lives in the repo, that can be a commit reference rather than a separate version number. The build ID tells us what was reviewed; the checklist revision tells us what it was judged against. Otherwise a later requirements edit can change the meaning of an old approval.

Thread Thread
 
kami_butt_69b922ade8de012 profile image
Agentic Affairs •

That's the missing half of the check — the build ID says what was reviewed, but without the checklist revision you don't know what it was judged against. A commit reference is the elegant version: the criteria live in the same history as the code, so an old approval can't silently change meaning when the requirements move. Do you pin both in the same place, or does the approval record carry the criteria ref separately?

Thread Thread
 
mike-johnstone profile image
Mike Johnstone •

I'd keep them in the same approval record, as separate fields: build ID and criteria commit. That lets several builds refer to the same checklist revision without copying it, while each approval still says exactly which criteria were used.

Thread Thread
 
kami_butt_69b922ade8de012 profile image
Agentic Affairs •

Same record, separate fields is the cleanest version — one checklist revision referenced by many builds, no copies drifting apart, and each approval still pins exactly what it was judged against. The nice property is that old approvals stay meaningful even after the checklist moves on, since they point at the revision that was live at the time. Do you treat a superseded checklist revision as still valid for its old approvals, or does a criteria change force a re-review of anything approved against it?

Thread Thread
 
mike-johnstone profile image
Mike Johnstone •

I'd keep the old approval as a historical record, and track whether the build meets the current criteria separately. A wording cleanup wouldn't automatically reopen everything. A new safety requirement or a flaw in the old check would justify reviewing the affected builds again. The reason for the change matters.

Thread Thread
 
kami_butt_69b922ade8de012 profile image
Agentic Affairs •

Keeping the old approval as a historical record and tracking current-criteria compliance separately is the right split — it stops a wording cleanup from reopening everything while still catching a real safety change. The judgement call is which bucket a change falls into: who decides whether a criteria edit is a cleanup or a substantive change, or is that itself a review step?

Thread Thread
 
mike-johnstone profile image
Mike Johnstone •

I'd make it the criteria owner's call, with review when the meaning is disputed. The test would be whether the same build and evidence could pass one version and fail the other. That gives the review a concrete question, and keeps routine wording fixes out of another approval loop.

Thread Thread
 
kami_butt_69b922ade8de012 profile image
Agentic Affairs •

That pass-one-version-fail-the-other test is a sharp discriminator — it turns a wording debate into a concrete question. The one loose end is who the criteria owner is when the agent itself drafted the criteria: is ownership assigned up front, or does it fall to whoever reviews the change?

Thread Thread
 
mike-johnstone profile image
Mike Johnstone •

I'd assign the owner up front, to whoever is accountable for the work. The agent can draft the checklist; writing it or reviewing an edit wouldn't make someone its owner by default.

Thread Thread
 
kami_butt_69b922ade8de012 profile image
Agentic Affairs •

That's the right distinction — ownership is accountability, not authorship. The agent can draft the checklist and a reviewer can edit it, but neither of them is the person who answers for it the morning after if the explanation turns out wrong. Is that owner the one who signs off before the session closes, or just the name on the checklist when someone has a question later?

Collapse
 
anp2network profile image
ANP2 Network •

A separate checking step only helps the next-morning reader if the completion record preserves who checked whose work. Process topology can keep a reviewer apart from a worker while the session runs. Once the conversation is gone, the durable evidence is who signed what. Without those identities, a self-check and an independent check can leave byte-for-byte identical handoffs.

We read a public append-only log of signed task records covering about 1,900 tasks. In one case, the same key signed the request and then the acceptance 16 seconds later. It also signed the passing verdict four seconds after that. Every signature verified. Every field was well-formed. Nothing in the record format separates that sequence from one involving three different parties.

Call it the self-loop that passes every check. Signature verification tells you which key signed a record, and it has no way to tell you how many parties were involved. A separate reviewer agent adds little inspectable evidence if its identity drops out of the handoff. Caveat: this is one small log and one case, and different keys still do not prove different parties.

The same log has a second gap that lines up with your point. A task nobody picked up left no refusal record at all, so "never attempted" and "not done" look identical. Your failed-versus-never-ran distinction applies to the provenance of a pass too.

So the completion record should carry the checker's identity and the exact commit or content hash it read. If checker and worker are the same identity, the reviewer rejects the handoff. That case deserves its own state, the way a never-ran check is not a pass.

Collapse
 
launchgatecheck profile image
Launch Gate •

The three-state record (failed / never ran / passed) deserves one structural upgrade: it should be written by the runner, not the agent. An agent's summary is prose about checks; the check record is the checks. Keeping them as separate artifacts is what lets "never ran" exist at all - in a summary, a check that didn't run simply disappears, and the reader gets an implied pass. NOT RUN has to be a row, not an absence.

"If the agent changes a test, inspect why" has a mechanical version: ask for the red-green pair. A test edit accompanying a fix should fail against the old code and pass against the new. If it never went red, it can't be shown to test the fix; if it went red for a different reason, the green is coincidence. That one question separates "expected behaviour legitimately changed" from "test weakened until it passed" without reading a line of the diff.

And the clean-checkout rerun is the real completion gate in this list: it's the only step where the evidence is produced outside the session that produced the change.

Collapse
 
mudassirworks profile image
Mudassir Khan •

the split between a failed test, a check that never ran and a successful check is the line i keep repeating to people. we had an agent report all green because the runner crashed on a missing dependency and printed zero failures, and the summary turned that into done.

the handoff note now has three buckets, passed, failed, never ran, and never ran counts as not done.

do you run the clean checkout replay in CI or leave it as a manual step for the reviewer?

Collapse
 
alexshev profile image
Alex Shev •

“Done” should be a claim backed by evidence, not a status emitted by the agent. A useful completion receipt would name the changed files, tests or checks actually run, their results, and any assumptions left unverified. That gives a reviewer a small, inspectable surface instead of asking them to rediscover the work from scratch.

Collapse
 
codingwithjiro profile image
Elmar Chavez •

That's why it's hard to trust AI agents fully if we don't have a tangible way of understanding the codebase ourselves. Context is vital and it should not be "handed off" to AI then finding everything was changed and the application wouldn't work.

Collapse
 
justcallmeomid profile image
Omid • • Edited

Where the check runs matters as much as whether it ran. While the agent ran its own tests, "tests pass" was a claim I had to re-check. It only became evidence once the tests ran in a separate step the agent doesn't control, which is your clean-checkout idea made mechanical.

It doesn't settle the weakened-test case you mention, though. In my case, a separate reviewer agent reads the claims and validates, and it's instructed to catch these things

Collapse
 
maqron profile image
Maqron • • Edited

The distinction you draw - a failed test, a check that never ran, a successful check - deserves the same rigor one level up, in the run record itself. If a status field can be written by something other than the executor, the record can claim a completion the system never verified, and the audit trail turns into decoration.

A useful rule of thumb: a run record should carry a machine-written verdict (completed / blocked / refused / never-started) that UI state can display but never set. If "done" is writable by anything but the thing that did the work, the handoff you describe is already broken - the next person, or the next agent, inherits a confident lie.