Acceptance Checklist for AI Coding Assistant Refactoring Tasks

    When an AI coding assistant handles a large cross-module change, success is not a confident claim of completion. This guide explains how to verify that the code was changed as planned, that the build and tests pass, and that failures are explained clearly enough to stop bad follow-on edits.

    When an AI coding assistant takes on a large cross-module change, its value is not in quickly declaring the work done. It is in changing the code according to the plan, passing the build and tests, and explaining failures clearly. If acceptance criteria are vague, the assistant can misread a compile error as an environment problem, keep editing broken code, and grow the diff until it is hard to roll back.

    Break the task into verifiable steps

    A complex change should start with an execution plan, but the plan itself is not proof of completion. Each major step should state which modules will change, how the expected behavior will change, which command or check confirms the step, and where to stop if it fails. Keep each step inside a closed loop of change, build, test, and compare against the expected result, rather than listing only to-dos.

    The plan should define three gates:

    • Build gate: the code must complete one clean build. Do not leave a failure for the next step.
    • Behavior gate: critical paths have automated tests or a minimal manual case.
    • Diff gate: changes stay within the planned scope and avoid unrelated rewrites.

    The same plan can be given to different assistants, but compare result quality: whether it passes on the first attempt, whether ambiguity is clarified proactively, and whether a failure can be traced to specific code. Do not compare who replies faster or sounds more confident.

    Check the code before blaming the environment

    The most common real causes of a build failure are type mismatches, interface signature changes that were not updated everywhere, inconsistent dependency versions, or stale test fixtures. Caches, incremental compilation, and old artifacts can distort the diagnosis, but they are only one line of investigation, not the default conclusion.

    A sound order is: read the full error output and locate the first real compile error; run a clean build to rule out stale artifacts; if it still fails, return to the latest diff and check interfaces, imports, and test expectations against the plan. If the assistant only cleans the workspace, does not rebuild, and moves to the next step, treat that as a broken process, not as proof that an environment issue is fixed.

    A sample acceptance constraint can be written as:

    1. Step completion conditions:
    2. 1. Clean build succeeds
    3. 2. All agreed tests pass
    4. 3. The change note lists modified files and reasons
    5. If any condition fails: stop later steps and first report the failure location and the smallest fix

    Correction instructions to the assistant should be specific: “The current failure comes from the code, not the cache. Do not continue to the next step until the build and tests pass.” Avoid a vague “try again.”

    Recognize scattered edits

    When an assistant cannot form a causal judgment, scattered edits often appear: one or two lines changed in many unrelated places in the hope that compilation will happen to pass. Signs include a huge diff in a short time, the same error rewritten repeatedly, no explanation of how each edit maps to the error, and a claim that “most of it is handled” while tests still fail.

    Stop automatic continuation immediately, restore the latest buildable version, and keep only in-plan changes. Restart with a smaller scope: change one module at a time, submit a minimal patch, and drive the fix with a single failing case. Without regression protection, a broad automatic rewrite often costs more than taking the work over manually.

    Check common sense in interactive and visual tasks

    An interactive demo that looks complete is not necessarily logically correct. Common distortions include object spacing that does not match the gameplay, so a legal action cannot be completed; layers, colliders, and clickable areas that do not line up; explanatory text that promises a visual style the screen does not implement; and a training display that shows convergence while the agent action layer and terrain layer use inconsistent coordinates, so the result cannot actually be played.

    Write common-sense checks as inspectable conditions. For path or collision scenes, check object size, gaps, boundaries, and whether one move lands on the same grid. For learning scenes, check that state, action, and reward use the same coordinate system, and that the policy is reproducible from several fixed initial states. Visual style is only an extra item. It cannot replace playability or numerical correctness.

    Set working boundaries for the assistant

    Work that fits an assistant has a clear boundary, can be rolled back, and can be verified automatically: adding tests, local refactors against an existing interface, and generating comparison cases. Work that should not be left unattended includes cross-layer protocol changes, legacy code without tests, and interaction logic that needs domain common sense to judge that something looks runnable but cannot actually be played.

    A practical approach is to treat the assistant as the executor: people own the plan, the gates, and failure decisions; the assistant changes code step by step and reports evidence. Accept only three items for each step: the build log, the test result, and the diff summary. If any item is missing, the step is not complete. This keeps the efficiency of automation without treating wrong attribution and endless trial and error as progress.