A Practical Guide to LLM Coding Agents: From Code Debugging to Workflows

1. First, Clarify the Concepts: From Code Completion to Agents

Over the past two years, AI-assisted programming tools have gone through three stages: single-line or single-function completion, conversational Q&A, and the current agent form. The first two stages are essentially “human-driven”: the model only provides suggestions. The key difference of the agent form is that it has a closed loop of perception, planning, action, and verification. It can read repository files, execute restricted commands, self-correct based on errors, and maintain consistent goals across multi-step tasks.

This leads to two direct consequences. First, the main constraint shifts from “whether the model is smart enough” to “whether the context is right.” Second, the risk model changes: the tool may actually read and write your codebase and execute commands, so permission design and safety boundaries must be built in from the start rather than added afterward.

2. Core Methodology: Context Engineering Sets the Upper Limit

At every step, the agent reassembles the task description, codebase information, constraints, and history of previous actions into context. If the context is poor, even a strong model can only produce generic suggestions. A practical approach is to build three layers of context.

1) Project-level convention file (persistent context)

Store the tech stack, directory conventions, coding standards, and verification commands in a file committed to the repository. This allows the agent to read it automatically in every session and avoids repeatedly explaining the same information.

# Project Context (for agent consumption)
## Goals and boundaries
- Goal: improve the stability and testability of the order settlement service
- Explicitly out of scope: do not modify the payment channel integration layer; do not introduce new runtime dependencies
## Tech stack and versions
- Runtime: Python 3.11
- Testing: pytest; static checks and builds are run through Makefile targets
## Directory conventions
- src/ for business code, tests/ for unit and integration tests, scripts/ for operational scripts
## Coding standards
- Keep functions under 50 lines; handle exceptions explicitly; do not use bare except clauses
- New dependencies must be justified in the change description, including alternatives
## Verification commands (must all pass before completion)
- Unit tests: make test
- Static checks: make lint
- Build: make build

2) Retrieval-based context (loaded on demand)

A large repository cannot be fully loaded into context. A practical approach is to let the agent first search by keywords to locate relevant files, then read only the relevant snippets. For very large codebases, code indexes or call graphs can be used as supplements. In practice, enforce the order of “locate first, modify later” to prevent the agent from rewriting files based on guesses when information is insufficient.

3) Task-level context (current-turn input)

This includes reproduction steps, expected behavior, possibilities that have already been ruled out, and the acceptable scope of changes. Scope limitation is especially important because it directly determines whether the change is a surgical fix or a large-scale rewrite.

3. Scenario 1: Code Debugging and Failure Diagnosis

Debugging offers one of the highest returns among agent use cases, but it should not be reduced to “paste the error and let the model guess.” A reliable workflow is a five-step loop:

1. Collect evidence: complete stack traces, relevant log snippets, reproduction steps, and environment differences.
2. Read-only analysis: ask the agent to output a ranked list of root-cause hypotheses, the verification method for each hypothesis, and the additional information required. Code modification is not allowed at this stage.
3. Human adjudication: the developer selects the most likely hypothesis to prevent the agent from making continuous changes in the wrong direction.
4. Constrained modification: explicitly specify the files, functions, and acceptable impact scope.
5. Mandatory verification: define “done” by whether tests and static checks pass.

# Step 2: read-only root cause analysis; no file changes
analyze "Based on logs/app.log, stacktrace.txt, and related implementations under src/, provide three root-cause hypotheses ranked by likelihood, along with verification commands for each hypothesis. This step must not modify any files."
# Step 4: scoped fix
fix "Modify only the amount rounding logic in src/order/settlement.py to fix floating-point accumulation errors, and add unit tests covering boundary values. Do not change interface signatures or caller code."
# Step 5: use verification results as the only definition of done
verify "Run make test and make lint in sequence. If either fails, continue fixing and do not claim the task is complete."

Two common anti-patterns should be avoided. One is pasting the error without the relevant code, which forces the model to give only generic advice. The other is allowing the agent to expand the scope of changes on its own, which can turn a debugging task into a large refactor that is difficult to review.

4. Scenario 2: Project Scaffolding and Code Refactoring

For project scaffolding, agents are good at generating structural skeletons, configuration files, and sample tests. However, architectural decisions should still be made by humans. A practical division of labor is for humans to determine the layering and dependency direction, while the agent fills in implementations and boilerplate code.

Refactoring should strictly follow the principle of small, verifiable steps: every change should be able to pass tests independently and be committed independently. It is useful to ask the agent to first produce a change list and impact analysis, then execute only after human confirmation. This way, even if the direction is wrong midway, the rollback cost remains low.

One important limitation is that agents have limited ability to identify implicit cross-module dependencies. Any change involving shared components, serialization formats, or database schemas must be reviewed manually for compatibility.

5. Scenario 3: Script Writing and Automation Tasks

Script-writing tasks have clear boundaries and are easy to verify, making them one of the areas where agents can provide value most easily. Common examples include log analysis, data cleaning, batch migration, scheduled inspection, and report generation.

The key engineering quality is turning “generated scripts” into “maintainable scripts”:

• Require idempotence: repeated execution should not produce side effects.
• Require rollbackability: perform validation or backup before write operations, and provide a dry-run mode.
• Require parameterization: do not hardcode paths, credentials, or environment identifiers in scripts.
• Require structured output: make it easy for downstream pipelines to consume the result instead of printing only for human readers.

Also constrain the agent not to write credentials into scripts or logs. Credentials should always be read from environment variables or a secret management service.

6. Scenario 4: Designing Custom Workflows

When a task cannot be completed in a single run, the process should be explicitly orchestrated as a multi-stage pipeline, with human confirmation inserted at key nodes.

workflow: feature_delivery
stages:
  - name: plan          # Output change list, impact analysis, and risks; wait for manual approval
    gate: manual_approve
  - name: implement     # Make small, incremental changes according to the list; do not exceed the approved scope
  - name: verify        # All of make test / make lint / make build must pass
    retry: 3
  - name: review        # Generate change description, test coverage notes, and residual risks
  - name: notify        # Send a change summary to the team communication tool

Custom tool integration should follow the principle of least privilege. Read-only capabilities, such as querying metrics, retrieving logs, and reading configuration, can be granted more broadly. Write capabilities, such as modifying files, executing commands, and calling production APIs, must be approved each time and executed in a sandbox or pre-production environment.

Tool definitions should use a consistent structured description to support auditing and permission control:

{
  "name": "query_service_metrics",
  "description": "Query aggregated metrics for a specified service within a time window; read-only and does not access production write APIs",
  "parameters": {
    "type": "object",
    "properties": {
      "service": { "type": "string" },
      "window_minutes": { "type": "integer", "minimum": 1, "maximum": 1440 }
    },
    "required": ["service"]
  }
}

In terms of deployment, agent services of this kind are usually hosted on container platforms. Code and build artifacts are stored in object storage or code hosting services, runtime logs are sent to logging services, and task success rate, latency, and call volume are observed through monitoring and alerting systems. General-purpose cloud capabilities, such as those offered by Baidu AI Cloud, including container platforms, object storage, logging services, and monitoring/alerting, can be used to build an observable and auditable runtime foundation.

7. Safety Boundaries: Four Defenses That Must Be Designed Explicitly

1. Least privilege: default to read-only access, authorize write operations by directory allowlist, and prohibit access to production databases and secrets.
2. Prompt injection protection: code comments, dependency documentation, and web content may contain injected instructions. Treat external content as data rather than instructions, and clearly distinguish the two within the system.
3. Supply chain risk control: new dependencies require human approval, versions should be locked, sources should be verified, and packages with names similar to well-known libraries should be treated with suspicion.
4. Audit and traceability: record the input, output, and operator for each tool invocation, bind changes to version-control records, and make actions traceable and reversible.

8. Evaluation and Measurement: Use Data to Determine Whether Efficiency Actually Improves

Avoid evaluating based on intuition alone. It is recommended to build a regression evaluation set: select 30 to 50 tasks from real historical work items, keep the inputs fixed, and run the same metrics periodically.

Metric	Meaning	Optimization direction
Task first-pass rate	Proportion of tasks completed without manual rework	Improve context quality and constraint clarity
Average interaction rounds	Number of back-and-forth exchanges required to complete a task	Reduce requirement ambiguity and improve task descriptions
Manual rework rate	Proportion of changes that need to be rewritten	Tighten change scope and acceptance criteria
Cost per task	Context length × number of calls	Trim context and use retrieval on demand
Number of introduced defects	Regression issues found after release	Strengthen the verification loop and review

9. Cross-Role Practices: Product and QA Teams Can Apply Them Too

This method is not limited to coding. On the requirements side, an agent can decompose a raw request into user stories, acceptance criteria, non-functional constraints, and boundary or exception scenarios. It can also review requirements in reverse to identify ambiguity and omissions. On the testing side, an agent can generate test case skeletons, boundary values, and exception branches based on interface definitions, while test engineers add business judgment.

For product teams, the most useful takeaway is that context quality determines output quality. Teams that clearly specify background, goals, constraints, and acceptance criteria tend to get more stable results, regardless of which model they use.

10. Common Anti-Patterns

• Giving the agent one oversized task without stage division or confirmation points.
• Not writing verification commands and relying on human inspection to decide whether a change is correct.
• Allowing the agent to read and write the entire repository without limits or to execute arbitrary commands.
• Pasting secrets, customer data, or internal addresses into the conversation.
• Generating only once without building an evaluation set, making long-term benefits difficult to judge.

Conclusion

The value of coding agents is not to “write code for humans,” but to compress repetitive retrieval, boilerplate generation, and verification work so that people can focus on architecture decisions and business judgment. The practical path can be summarized in three steps: first, solidify context and verification commands; second, tighten permission boundaries; and third, continuously measure results with an evaluation set. With these three practices in place, the cost of switching tools is low, and the methodology itself can be reused over the long term.