Autonomous Coding Agents: Practices for Debugging Issues and Passing Tests

    This article describes how a coding agent handles a full software issue in a real repository. The agent reads the codebase, reproduces the problem, identifies the root cause, changes the code, runs tests, and produces a change that engineers can review. It covers the working process, how to keep fixes minimal, layered test verification, the trade-off between reasoning effort and cost, pre-submission review, and the engineering controls that make agent-generated changes auditable.

    In real software development, a coding agent is valuable only if it can do more than generate a few lines of code from a description. It needs to enter a real repository, understand the project structure, reproduce the problem, locate the root cause, modify the implementation, run tests, and finally produce a code change that a human can review. This process involves several consecutive steps. A wrong judgment at any step can produce an ineffective fix, leave tests incomplete, or introduce new regressions.

    For this reason, an intelligent coding system should not be judged only by how often a single code generation is correct. It also needs to keep context consistent over a long task chain, check its own conclusions, and keep the required compute and human intervention low. This article walks through the full process and explains how to design and use a system that investigates issues, fixes code, and submits changes that pass tests.

    1. From Generating Code to Completing Tasks

    Traditional code completion usually handles only local context. For example, it fills in a function body from the function signature, or writes an implementation from a comment. This works for simple tasks with clear boundaries, but it cannot cover the complex problems found in real projects.

    A complete issue-fixing task usually includes the following steps:

    1. Read the issue description and identify explicit requirements and implicit constraints.
    2. Browse the directory structure and determine which module contains the feature.
    3. Read the relevant code, configuration files, and test cases.
    4. Analyze the call chain to find the actual source of the abnormal behavior.
    5. Design a fix and assess its possible side effects.
    6. Edit one or more files.
    7. Run targeted tests.
    8. Continue correcting the code based on failure information.
    9. Run broader regression tests.
    10. Review the diff and write a change description.
    11. Produce a submission that people can review.

    This means the agent needs an observe, reason, execute, and verify loop. It must know how to write code, but it also needs to know when to read a file, when to run tests, how to interpret error messages, and when to avoid modifying code too early because the evidence is insufficient.

    2. Basic Workflow for Working in a Real Repository

    1. Build an Understanding of the Repository

    When a task starts, the agent should not modify code right away. It should first build a basic understanding of the project. Usually it needs to confirm:

    • The main programming language and build method;
    • How source code, test code, and configuration files are distributed;
    • The entry modules and core dependencies;
    • The test commands and static check commands;
    • Whether the working tree has uncommitted changes;
    • Whether the modules named in the issue have dedicated documentation.

    The goal of this step is not to read the whole repository. The goal is to narrow the search scope quickly. A sound approach is to review the top-level directories and project documentation first, then search for functions, classes, error messages, or configuration keys related to the issue, and finally follow the call chain into the relevant files.

    If the agent skips the environment check, it can run into several common problems. It may use the wrong test command, overwrite changes the developer has already made, mistake generated files for source code, or make large refactors without understanding the module boundaries.

    2. Turn the Natural-Language Issue into Testable Hypotheses

    An issue description is often not the same as its root cause. For example, “an API returns an error when given empty input” describes a symptom. The cause could be any of the following:

    • Input validation logic rejects empty values;
    • Default values are not injected correctly;
    • A downstream function cannot handle empty collections;
    • Serialization drops a field;
    • The test environment and production environment have different configurations.

    The agent should therefore turn the issue into several testable hypotheses and look for evidence for each one. A reliable analysis table can include the following:

    Analysis item Question to answer
    Symptom Under what input and on which path does the error occur?
    Expected behavior What should the correct behavior be?
    Entry point Which API, command, or task triggers the problem?
    Path Which functions and modules does the data pass through?
    Root cause Which condition or implementation causes the abnormal behavior?
    Fix Can a minimal change remove the problem?
    Verification Which tests can prove that the fix works?

    With this approach, the agent does not patch the surface error message. It tries to build a complete causal chain from input to output.

    3. Reproduce First, Then Modify

    Reproducing the problem reliably is key to a good fix. The agent should run existing tests when possible, or build a minimal reproduction from the issue description. Reproduction helps confirm that:

    • The problem actually exists;
    • The failure matches the description;
    • The trigger conditions are wider or narrower than expected;
    • The current branch already contains part of the fix;
    • The same steps can verify the result after the change.

    If the agent cannot reproduce the problem, it should not conclude that the problem does not exist. Possible causes include different dependency versions, missing environment variables, incomplete test data, or a problem that occurs only under specific boundary conditions. In that case, the agent should record its observations and continue checking the configuration, fixtures, mocks, and historical tests.

    3. Keeping Fixes Minimal and Reliable

    1. Avoid Unrelated Refactoring

    One of the main risks of automated coding is that a fix for a local problem can touch a large amount of unrelated code. Large changes may pass tests for now, but they make review harder and increase regression risk.

    A safer set of principles is:

    • Modify only the files directly related to the problem;
    • Reuse existing abstractions and error-handling patterns first;
    • Avoid changing public interfaces;
    • Do not upgrade dependencies as a side task in a bug fix;
    • Do not delete logic that looks redundant but may serve a compatibility purpose;
    • Keep the existing code style and directory structure.

    If a refactor is really needed, describe its reason, scope of impact, and verification results separately. Do not mix several goals in one change.

    2. Cover Both Normal and Boundary Paths

    A high-quality fix does more than turn a failing test green. It also makes sure that existing normal flows are not affected. For example, when fixing an empty-input problem, the agent should verify:

    • Empty input;
    • Input with a single element;
    • Input with multiple elements;
    • Invalid input;
    • Very large input;
    • Missing fields;
    • Repeated calls;
    • Resource release after an exception.

    The agent should add boundary tests based on the business logic rather than relying entirely on existing tests. This matters most when the original problem had no test coverage. A new regression test can be more important than the code change alone, because it helps prevent the same kind of problem from returning.

    4. Running Tests in Layers

    Tests should not run only once. A sensible order runs from near to far and from fast to slow.

    Layer 1: Targeted Tests

    First, run the tests directly related to the modified files or features. This quickly shows whether the core fix works. Feedback is fast at this stage, which suits frequent iteration.

    Layer 2: Module Tests

    Next, run the tests for the whole module or subsystem. This confirms that interface contracts, error handling, and internal collaboration have not been broken.

    Layer 3: Static Checks and Build Validation

    Depending on the project, run formatting checks, type checks, static analysis, and the build process. These checks can catch problems that runtime tests may not cover, such as unused variables, type mismatches, circular dependencies, or build configuration errors.

    Layer 4: Full Regression Tests

    Finally, run the project-level test suite to see whether the fix affects other modules. Full test runs can take a long time, but they are especially necessary for shared components, data models, permission logic, and infrastructure code.

    After each test failure, the agent should identify the failure type instead of simply running the test again:

    • Assertion failure: the implementation logic may be incorrect;
    • Compilation failure: the problem may be with syntax, types, or dependencies;
    • Environment failure: a service, variable, or permission may not be ready;
    • Timeout: the cause may be an infinite loop, performance regression, or an unstable test;
    • Unrelated failure: the repository may already have a problem.

    Only after the failure cause is clear can later fixes avoid blind trial and error.

    5. Balancing Reasoning Effort and Cost

    In long, multi-step coding tasks, reasoning effort affects how deeply the agent analyzes a problem, how many tool calls it makes, and the total cost of the run. A simple formatting change or a local variable adjustment usually does not need much reasoning. Tasks that involve calls across several modules, concurrency control, data consistency, or complex test failures need more thorough analysis.

    A tiered strategy can work:

    • Simple tasks: locate the problem quickly and limit the search and modification scope;
    • Medium tasks: require a root cause hypothesis before making changes;
    • Complex tasks: require reproduction, comparison of fix options, layered testing, and diff review;
    • High-risk tasks: allow only a proposed patch and test plan, and write the changes to disk only after human confirmation.

    Reasoning effort does not replace engineering constraints. Even when a model analyzes well, its work still needs permission isolation, limits on change scope, test gates, and human review. For operations involving data deletion, permission changes, production configuration, and security policies, human confirmation should be the default.

    6. Reviewing Changes Before Submission

    Passing tests does not guarantee that a change is acceptable. Before producing the final submission, the agent should run an independent diff review. The review should focus on:

    1. Whether only the necessary files were modified;
    2. Whether debug output, temporary files, or local configuration were included;
    3. Whether unrelated formatting was changed;
    4. Whether new tests were added and cover the real problem;
    5. Whether hard-coded paths, credentials, or environment information are present;
    6. Whether error messages are clear and follow project conventions;
    7. Whether new exception-swallowing logic was introduced;
    8. Whether the change description accurately explains the cause and the verification method.

    A submission message should include three parts: the cause of the problem, the fix, and the verification results. For example:

    1. Fix: handle the empty-input branch
    2. Cause:
    3. Empty collections after input validation did not enter the default handling logic, which caused an exception in downstream calls.
    4. Change:
    5. Added empty-collection handling while keeping the public interface unchanged, and added a matching regression test.
    6. Verification:
    7. Passed targeted tests, module tests, and static checks.

    This structure helps reviewers understand the change quickly without reading the full context again.

    7. Building an Auditable Engineering Loop

    To bring autonomous coding into a team’s workflow, the team also needs supporting engineering controls:

    • Give the agent read-only access by default, with write access granted only as needed;
    • Limit code changes to a designated workspace;
    • Keep records of tool calls, test results, and retry attempts;
    • Require human confirmation for high-risk operations;
    • Use automated checks to block changes that have not passed tests from reaching the main branch;
    • Require each patch to link to the issue description and verification evidence;
    • Set stop conditions for repeated failures to avoid endless loops;
    • Run security scans and sensitive-information detection on generated results.

    Under these controls, the agent is no longer just a code generator. It becomes an automated executor within the development process. It gathers evidence, proposes hypotheses, makes limited changes, and submits verified results. Developers focus on confirming goals, judging risk, and making the final review.

    Conclusion

    Autonomously investigating and fixing an issue, then submitting a change that passes tests, represents a shift for coding agents from local assistance to complete task execution. The core capability is not just generating correct code. It is staying aligned with the goal across a real repository, locating root causes from evidence, verifying results through layered tests, and delivering changes that are minimal, clear, and auditable.

    For development teams, the best practice is not to remove humans from the process. It is to place the agent where automation fits well: let it handle repetitive searching, reproduction, editing, and verification, while permissions, tests, and review protect engineering quality. Only when understanding the issue, carrying out actions, verifying results, and explaining changes form a stable loop can intelligent coding become a sustainable gain in development efficiency.