Your AI Coding Agent Is LYING When It Says "Done

<h2> TL;DR </h2> <p>When an AI agent changes few files, runs few tests, and says "Done", is it really done? Not always. Things may still break in unexpected places.</p> <p>I prefer to define a strict definition of "Done", which I call the <strong>Task Completion Protocol</strong>. It usually lives in <code>AGENTS.md</code> and, in its simplest form, looks like this:</p> <ul> <li>Run the repository's real lint and test commands.</li> <li>Fix failures and rerun the checks.</li> <li>Report the exact evidence before claiming completion.</li> </ul> <p>This does not replace CI or code review. It moves a basic verification gate earlier, before a broken state reaches the next agent session, the pull request, or you.</p> <h2> Video Walkthrough </h2> <p>If you prefer a visual walkthrough, this video shows the concept in action. I run the same task twice: without a completion protocol and with it - this demonstrates how explicit definition of "done" helps. I also show few tricks and techniques for making agents follow the protocol.</p> <p> <iframe src="https://www.youtube.com/embed/UxwJj6wo8J8"> </iframe> </p> <h2> The Agent Says "Done." The Repository Disagrees. </h2> <p>You have probably seen some version of this:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight plaintext"><code>Agent: Done. Implemented the fix and updated the tests. Terminal: $ make test ... FAIL </code></pre> </div> <p>The implementation might even look correct. Perhaps the agent ran one focused test, inspected the diff, and produced a tidy summary. Then you run the repository's normal checks and find a lint error, a failing test in a different place, or any other error that was not caught by the agent.</p> <p>This gets worse as AI-assisted workflows grow to involve multiple agents. In an interactive session, you may spot the failure and fix it yourself. In a multi-step workflow, one worker reports success and the next starts from a broken state. These problems accumulate quickly, and the final state may be badly broken.</p> <h2> The Repository Needs to Define What "Done" Means </h2> <p>Yes, this is obvious for humans: make some changes, run tests and lint, fix issues, maybe check few other things, and only then say "Done". Agents need it written down, and <code>AGENTS.md</code> is the perfect place for it. I call this section the <strong>Task Completion Protocol</strong>.</p> <p>Here is a compact version you can adapt to your repository:<br> </p> <div class="highlight js-code-highlight"> <pre class="highlight markdown"><code><span class="gu">## Task Completion Protocol</span> Before reporting completion, classify the task as coding or non-coding. For coding tasks: <span class="p">1.</span> Run lint: <span class="sb">`your command to run lint`</span>. <span class="p">2.</span> Run tests: <span class="sb">`your command to run tests`</span>. <span class="p">3.</span> Check whether commands, workflows, or architecture changed. If so, update AGENTS.md. <span class="p">4.</span> Report the commands run, their results, test coverage, and whether AGENTS.md changed. <span class="p">5.</span> Do not report the task as complete while a required check is failing. For non-coding tasks: <span class="p">1.</span> Summarize the findings or actions taken. <span class="p">2.</span> Confirm that the requested deliverable was produced. <span class="p">3.</span> Do not run unrelated lint or test commands unless requested. </code></pre> </div> <p>My <a href="https://github.com/gemyago/golang-backend-boilerplate/blob/main/AGENTS.md#task-completion-protocol" rel="noopener noreferrer">Go backend template has a real version of this protocol</a>. It uses <code>make lint</code> and <code>make test</code>. Your protocol should name the exact commands and any specific checks that matter.</p> <p>Don't just say "Run the tests". This still leaves the agent guessing. It is best to name the exact commands the ag