[The agent fieldbook](https://www.agentlist.io/learn/guides) # Ship a small change with a coding agent Take one real issue from reproduction to a reviewed change. Preserve the project, test the behavior, and distinguish a passing build from a shipped result. Chapter 04 of 1015 min readIntermediate [Jump to the exercise](#try-it) Code with confidence, one useful step at a time. Keep this chapter open alongside your next real task. ## What you’ll be able to do - Give a coding agent a bounded issue with a reproducible result. - Review implementation and verification evidence separately. - Confirm the change in the environment where users will experience it. ## 1\. Choose a change with a visible finish line Start with a defect or improvement that fits within one coherent behavior. A filter that fails to reset, an unclear validation message, or a missing keyboard interaction gives you something specific to reproduce and verify. A request to ‘clean up the whole app’ makes it difficult to separate essential work from an attractive detour. Describe the user-visible result before naming an implementation. Record the starting behavior with exact steps and an example input. Include the affected environment, such as a browser route or app version. State the expected result and any behavior that must remain intact. If you do not yet know the cause, say so. Ask the agent to investigate before editing. An early guess can send the work toward a patch that hides the symptom while preserving the underlying defect. Worked example ### Illustrative issue On the catalog page, choose a category, enter a search term, then select Reset. The category clears but the search term remains. Reset should restore both controls and the full result set. Preserve the current URL-sharing behavior and keyboard focus. ## 2\. Establish the project state before editing Have the agent inspect the repository instructions, current branch, and existing changes. Uncommitted work may belong to someone else or to an unfinished task. Agree on where the new change will live, using a branch or isolated checkout when appropriate. Do not let a setup problem become a reason to discard unrelated files. The initial state is part of the evidence you need when reviewing the final diff. Confirm how the project installs dependencies, starts locally, and runs relevant checks. Prefer the documented commands and existing conventions. If the baseline already fails, record the failure before making changes. A later report should distinguish that baseline problem from a failure introduced by the task. Give the agent access to the necessary environment without adding production credentials that the change does not require. ### Build knowledge belongs with the project Keep useful setup and validation instructions in the repository's established instruction files. Verify them against the actual scripts. An old command copied into a prompt can waste as much time as a missing command. Try it yourself ## Would you ship this change? Review a small coding scenario. Decide which evidence is enough and which missing checks would change your decision. Practice case: an agent returns a login-test fix. Read the evidence, then decide what to do. #### Reproduce The login test fails because the session fixture still uses an expired timestamp. Before: login.test.ts → 1 failed, 8 passed What is the next review action? Accept because the tests passRemove the unrelated change and verify the scoped patchAsk for more features before reviewing ## 3\. Trace the cause and review the proposed scope Ask the agent to connect the reproduction to the relevant code path. For the reset example, it should identify where each filter value is stored, how Reset updates those values, and how the results and URL derive from them. The useful explanation is a causal account you can check against the source. A list of file names alone does not explain why the failure occurs. Once the cause is clear, let the agent make the smallest coherent change that fixes it. Small does not always mean one line. The correct repair may update state handling and its regression check together. Be cautious when the diff grows into dependency updates, broad formatting, or unrelated component rewrites. Ask how each addition contributes to the acceptance criteria, then keep or remove it on that basis. 1. ### Reproduce Run the reported sequence and confirm the actual result before changing the code. 2. ### Trace Find the state, data, or control flow responsible for the result and explain the failure mechanism. 3. ### Repair Change the responsible behavior and add or update a meaningful regression check when the change warrants one. ## 4\. Match each claim to the right check Use the project's relevant automated checks, then exercise the behavior that motivated the task. A type check can find a category of code errors. A build can establish that the project compiles or packages. Neither proves that the reset button clears every control in the browser. Ask for the command, outcome, and any limitations behind each verification claim. Test the ordinary path and the nearby edge that the fix could disturb. In the example, verify Reset after selecting only a category, only a search term, and both. Check that sharing the URL still restores the intended filters. For interface changes, include keyboard use and a narrow viewport when relevant. Choose checks because they could catch a real regression, not because a long test list looks reassuring. Worked example ### Illustrative evidence report The targeted state test passes. The production build completes. In the local browser, Reset clears both controls and restores all results. A shared filtered URL still restores the selected state. Deployment has not run, so production behavior remains unverified. ## 5\. Review the change as a maintainer Read the diff with the original issue beside it. Check whether the implementation follows existing patterns, preserves public interfaces, and handles failure states. Review test assertions as carefully as the code. A test can pass while checking only that a function was called, leaving the user's actual result untested. Ask whether the check would have failed before the fix. Review the scope of changed files and generated artifacts. Confirm that secrets, debug output, unrelated edits, and accidental dependency changes are absent. If another agent reviews the work, treat its findings as leads to investigate. The author and reviewer can share a mistaken assumption. Resolve important findings against the code and observed behavior, and keep a human owner for the decision to merge or release. ## 6\. Confirm the result after the handoff When the change meets the agreed checks, follow the project's review and release process. State exactly what was completed: a local change, a commit, a pull request, a merge, or a deployment. These are different states. A merged change may still be waiting for deployment. A successful deployment job may still require a quick check of the affected route or installed application. After release, repeat the shortest meaningful reproduction in the target environment and record the result. Confirm that the environment contains the expected revision. If the behavior differs from local testing, investigate configuration, cached assets, data, and build differences before adding another code patch. Keep the rollback path available until the result is established. Save a brief handoff with what changed, how it was checked, and any remaining limitation. ## When things go wrong Start with the failure you can observe. The agent keeps patching new symptoms. Return to one reproducible failure and trace the data or control flow. Ask for evidence of the cause before accepting another edit. All tests pass, but the interface still fails. Check whether the tests exercise the same environment and user action. Reproduce in the actual interface and add a check for the missing behavior. The deployed app behaves differently from local. Verify the deployed revision and compare configuration, data, and cached assets. Fix the environment mismatch before assuming the implementation needs another patch. ## Put it into practice 0 / 5 Use this checklist on your next real task. I reproduced the issue and recorded the expected behavior.The starting branch and unrelated changes are preserved.The fix addresses the traced cause within the agreed scope.The checks cover the user-visible behavior and a relevant edge case.The final report distinguishes code, review, deployment, and live verification. Your checklist is saved in this browser. Exercise inputs are not saved. ## Sources & further reading Primary references for the ideas in this chapter. Product behavior can change; check the documentation for the version you use. - [GitHub: Best practices for agent tasks](https://docs.github.com/en/copilot/tutorials/cloud-agent/get-the-best-results) Supports bounded coding tasks, repository instructions, validation, and reviewing changes before a pull request. The reset-button workflow is an original example. - [Anthropic: Building effective agents](https://www.anthropic.com/engineering/building-effective-agents) Supports feedback from tool results and tests, clear stopping conditions, and human review of coding outcomes. Edited October 7, 2026 · Examples are illustrative unless attributed. --- Source: [Ship a small change with a coding agent | agentlist.io](https://www.agentlist.io/learn/guides/ship-with-a-coding-agent). This is the public page rendered as Markdown; interactive controls require the website.