Back to series
· 17 min read

Coding Agent: How Do Agents Write and Modify Code?


1. What Is a Coding Agent?

A Coding Agent is an AI agent that can understand software development tasks and autonomously complete coding work by accessing code repositories, invoking development tools, and executing programs.

Traditional code completion tools mainly predict the next lines of code based on the current code context; the developer still has to decide which files to modify, how to structure the code, and how to verify the results.

A Coding Agent, by contrast, can work toward a complete development goal.

For example, a user might ask:

Add a user registration endpoint to the existing project that supports email and password sign-up, including parameter validation, password hashing, database persistence, and unit tests.

The Coding Agent needs to:

  1. Understand the user's requirements.
  2. Analyze the project's directory structure.
  3. Identify the programming language and frameworks in use.
  4. Locate the existing user module and API conventions.
  5. Understand the database models and business logic.
  6. Draft a plan for the code changes.
  7. Create or modify the relevant files.
  8. Install or invoke the necessary dependencies.
  9. Run code checks and tests.
  10. Fix the code based on error messages.
  11. Review the final changes.
  12. Report the changes and test results to the user.

It does more than generate a snippet of code — it can take part in the entire software development process.

1. How Coding Agents Differ from AI Code Completion

Aspect AI code completion Coding Agent
Core goal Predict and generate code Complete development tasks
Scope of work Current file or local context The entire code repository
File operations Usually performed by the developer Can read and modify files autonomously
Task planning Limited Can break down complex tasks
Tool invocation Limited Can invoke terminals, tests, Git, and other tools
Error handling Developer-driven Can analyze errors and attempt fixes
Test verification Usually performed by the developer Can run tests autonomously
Task state Mainly the current editing context Can maintain multi-step execution state

AI code completion mainly addresses the efficiency of writing code, whereas a Coding Agent goes further and addresses the execution of software development tasks.

2. How Coding Agents Differ from Ordinary Chatbots

An ordinary chatbot typically offers code suggestions through conversation, while a Coding Agent can operate directly on a code repository in an authorized environment.

Aspect Ordinary chatbot Coding Agent
Code understanding Based on context supplied by the user Can read project files on its own initiative
Code generation Returns code snippets Can modify files directly
Project analysis Relies on the user's description Can analyze directories and dependencies
Command execution Usually cannot execute directly Can invoke terminal tools
Test verification Provides testing suggestions Can actually run tests
Error fixing User copies the error message Can read errors and iterate on fixes
Result delivery Returns text Can deliver code changes and test results

The key capability of a Coding Agent is forming an executable, observable, and verifiable development loop.

2. The Overall Architecture of a Coding Agent

A Coding Agent typically consists of a task planner, a code understanding module, a context retrieval module, file operation tools, a code execution environment, a test verification module, and a state management module.

1. Core Architecture

flowchart TD
    A["User development requirements"] --> B["Agent Controller"]
    B --> C["Task understanding and planning"]
    C --> D["Codebase analysis"]
    D --> E["Context retrieval"]
    E --> F["Code generation and modification"]
    F --> G["File operation tools"]
    G --> H["Code repository"]
    F --> I["Terminal execution tools"]
    I --> J["Compilation and testing"]
    J --> K["Result analysis"]
    K --> L{"Are requirements met?"}
    L -->|"No"| M["Locate issues and create a fix plan"]
    M --> F
    L -->|"Yes"| N["Code review and change summary"]
    N --> O["Deliver development results"]

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#EAF3EC,stroke:#83A995,color:#315D49
    style C fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style D fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style F fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style G fill:#EAF3EC,stroke:#83A995,color:#315D49
    style H fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style I fill:#EAF3EC,stroke:#83A995,color:#315D49
    style J fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style K fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style L fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style M fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style N fill:#EAF3EC,stroke:#83A995,color:#315D49
    style O fill:#DCEFE5,stroke:#4F8B70,color:#24563F

Responsibilities of each module are as follows:

Module Main responsibilities
Agent Controller Manage task execution and tool invocation
Task planner Break down requirements into development steps
Codebase analysis Understand directory structure, tech stack, and project conventions
Context retrieval Find relevant code, interfaces, and dependencies
Code generation module Write new code and modify existing code
File operation tools Read, create, modify, and delete files
Terminal execution tools Run commands, scripts, and development tools
Test validation module Execute tests, compilation, and static checks
State management module Save execution progress, historical results, and exceptions
Code review module Check change scope, quality, and risks

2. Four-Layer Structure of a Coding Agent

From an engineering design perspective, a Coding Agent can be divided into four layers.

Intelligent decision layer

Responsible for understanding requirements, analyzing tasks, formulating plans, selecting tools, and judging execution results.

Code understanding layer

Responsible for analyzing code repositories, retrieving relevant files, understanding function call relationships, data structures, and module dependencies.

Development execution layer

Responsible for reading and modifying files, running terminal commands, and executing compilation and tests.

Quality assurance layer

Responsible for code review, test validation, permission checks, exception handling, and result delivery.

flowchart TB
    A["Intelligent Decision Layer"]
    A1["Requirement Understanding"]
    A2["Task Planning"]
    A3["Tool Selection"]
    A4["Result Evaluation"]

    B["Code Understanding Layer"]
    B1["Project Structure Analysis"]
    B2["Code Retrieval"]
    B3["Dependency Analysis"]
    B4["Call Chain Understanding"]

    C["Development Execution Layer"]
    C1["File Reading"]
    C2["Code Generation"]
    C3["File Modification"]
    C4["Terminal Execution"]

    D["Quality Assurance Layer"]
    D1["Unit Testing"]
    D2["Integration Testing"]
    D3["Static Checking"]
    D4["Code Review"]

    A --> B
    B --> C
    C --> D

    A1 --> A
    A2 --> A
    A3 --> A
    A4 --> A

    B1 --> B
    B2 --> B
    B3 --> B
    B4 --> B

    C1 --> C
    C2 --> C
    C3 --> C
    C4 --> C

    D1 --> D
    D2 --> D
    D3 --> D
    D4 --> D

    style A fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style A1 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style A2 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style A3 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style A4 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style B1 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style B2 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style B3 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style B4 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style C fill:#EAF3EC,stroke:#83A995,color:#315D49
    style C1 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style C2 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style C3 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style C4 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style D fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style D1 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style D2 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style D3 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A
    style D4 fill:#F5F8F4,stroke:#B5CBBB,color:#40594A

The four layers are not a simple one-off pipeline. Code understanding results affect task planning, test failures trigger code modifications, and code review may also require re-retrieving context.

III. Codebase Understanding: How Does the Agent Understand the Entire Project?

The Coding Agent must first understand the project, rather than immediately start writing code.

Without understanding the project structure, tech stack, existing modules, and coding conventions, generated code can easily become disconnected from the existing system.

1. Project Directory Scanning

Suppose a Python web project has the following structure:

project/
├── app/
│   ├── api/
│   │   ├── user.py
│   │   └── auth.py
│   ├── models/
│   │   └── user.py
│   ├── services/
│   │   └── user_service.py
│   ├── schemas/
│   │   └── user.py
│   └── main.py
├── tests/
│   ├── test_user.py
│   └── test_auth.py
├── requirements.txt
├── pyproject.toml
└── README.md

The Agent can identify the following through directory scanning:

  • The language used by the project.
  • The application entry point.
  • Where API routes are located.
  • Data model definitions.
  • Modules containing business logic.
  • The location of test files.
  • The dependency management approach.
  • Project documentation and development conventions.

The directory structure can provide initial clues, but module responsibilities cannot be determined from file names alone; specific files still need to be read.

2. Project File Reading

The Coding Agent can read code through file tools.

For example:

from pathlib import Path


def read_project_files(root: str):
    root_path = Path(root)

    for path in root_path.rglob("*.py"):
        if any(
            part in {
                ".git",
                ".venv",
                "__pycache__"
            }
            for part in path.parts
        ):
            continue

        print(path)
        print(path.read_text(
            encoding="utf-8"
        ))

A real system should not read the entire project unconditionally.

It needs to filter out:

  • Virtual environments.
  • Build artifacts.
  • Dependency directories.
  • Large binary files.
  • Auto-generated files.
  • Secret and environment variable files.
  • Files unrelated to the current task.

A code repository may contain a large number of files; reading all of them wastes context and increases model input costs.

3. Identifying Project Conventions

The Agent also needs to identify development conventions in the project.

Common convention files include:

File Purpose
README.md Project description and how to run it
CONTRIBUTING.md Contribution and development conventions
AGENTS.md Agent development guidelines
pyproject.toml Python project configuration
package.json Node.js project configuration
tsconfig.json TypeScript configuration
.editorconfig Editor formatting conventions
.gitignore Git ignore rules
Dockerfile Container build configuration

Among these, AGENTS.md can be used to describe the code directory structure, test commands, code style, and project constraints.

The Agent should read the convention files relevant to the current task and use them as constraints during development.

4. Code Structure and Dependency Analysis

Understanding a project requires more than looking at its directory structure; it also requires understanding the relationships between code.

For example:

# app/api/user.py

from app.services.user_service import (
    create_user
)


def register_user(data):
    return create_user(data)
# app/services/user_service.py

from app.models.user import User


def create_user(data):
    user = User(
        email=data.email
    )

    return user

From this, we can see:

  • The API layer is responsible for receiving requests.
  • The Service layer is responsible for business processing.
  • The Model layer is responsible for data models.

The Agent needs to understand these call relationships to avoid incorrectly writing business logic into the API layer or duplicating functionality that already exists.

5. Code Retrieval and Context Construction

For large projects, it is impossible to feed all code into the model at once.

Relevant code usually needs to be retrieved according to the task.

Common methods include:

Keyword search

Find code by function names, class names, API names, and business keywords.

grep -R "create_user" app/

Symbol search

Find relevant code by the definition locations of functions, classes, variables, and methods.

Abstract syntax tree analysis

Use AST (Abstract Syntax Tree) to analyze code structure and identify functions, classes, import relationships, and call expressions.

Semantic search

Retrieve semantically similar code snippets through code embeddings.

Call chain analysis

Analyze call relationships between functions to find the upstream and downstream modules involved in the target change.

These methods can be used in combination.

For example, if the user asks to modify the user registration API, the Agent can first search for register_user, then find the Service, Model, Schema, and test files it calls.

6. Code Context Construction Process

flowchart TD
    A["Receive development task"] --> B["Identify modules involved in the task"]
    B --> C["Scan project directory"]
    C --> D["Read project conventions"]
    D --> E["Retrieve relevant code"]
    E --> F["Analyze functions and classes"]
    F --> G["Build dependency relationships"]
    G --> H["Extract necessary context"]
    H --> I["Check whether context is sufficient"]
    I --> J{"Is the scope of changes understood?"}
    J -->|"No"| K["Retrieve additional relevant files"]
    K --> E
    J -->|"Yes"| L["Generate task implementation plan"]

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style D fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style E fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style F fill:#EAF3EC,stroke:#83A995,color:#315D49
    style G fill:#EAF3EC,stroke:#83A995,color:#315D49
    style H fill:#EAF3EC,stroke:#83A995,color:#315D49
    style I fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style J fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style K fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style L fill:#DCEFE5,stroke:#4F8B70,color:#24563F

IV. Task Planning: How Does an Agent Break Down a Development Request?

Development requests raised by users are usually in natural language, whereas code changes require explicit files, functions, and operational steps.

A Coding Agent needs to convert a high-level request into an executable development plan.

1. Understanding the Request

For example:

Add a user registration feature to the existing system, supporting registration with email and password, validating the email format, storing passwords using secure hashing, and adding tests.

The Agent needs to identify:

Request Technical task
User registration Add a registration endpoint
Email validation Add input validation
Secure password storage Use a password hashing algorithm
Save the user Call the database for persistence
Handle duplicate emails Add a uniqueness check
Testing Write tests for success and failure scenarios

2. Task Decomposition

The development task can be split into multiple subtasks:

  1. Analyze the existing user module.
  2. Check the user model and database constraints.
  3. Check the existing password handling logic.
  4. Define the registration request and response structures.
  5. Implement the registration business logic.
  6. Add the API route.
  7. Write unit tests.
  8. Run the tests and fix errors.
  9. Review the final code changes.

Task decomposition should take dependencies into account rather than simply following the textual order.

3. Task Dependency Graph

```mermaid flowchart TD A["Analyze existing project"] --> B["Inspect user model"] A --> C["Inspect auth module"] B --> D["Design registration data structure"] C --> D D --> E["Implement registration Service"] E --> F["Implement registration API"] F --> G["Write unit tests"] G --> H["Run tests"] H --> I{"Do tests pass"} I -->|"No"| J["Analyze and fix errors"] J --> H I -->|"Yes"| K["Code review"] K --> L["Deliver development result"] style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976 style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976 style D fill:#EAE8FA,stroke:#A49BD5,color:#51477D style E fill:#EAF3EC,stroke:#83A995,color:#315D49 style F fill:#EAF3EC,stroke:#83A995,color:#315D49 style G fill:#EAF3EC,stroke:#83A995,color:#315D49 style H fill:#E0F0FE,stroke:#93BCE8,color:#1E4976 style I fill:#F7F4E8,stroke:#C7B77A,color:#675A2D style J fill:#F7EAE7,stroke:#C98D7C,color:#754438 style K fill:#EAE8FA,stroke:#A49BD5,color:#51477D style L fill:#DCEFE5,stroke:#4F8B70,color:#24563F ```

4. The data structure of a task plan

An Agent can save the development plan as structured data.

```json { "task": "Implement the user registration feature", "steps": [ { "id": "step_1", "description": "Analyze the existing user module", "status": "completed" }, { "id": "step_2", "description": "Implement the registration business logic", "status": "pending" }, { "id": "step_3", "description": "Add the registration endpoint", "status": "pending" }, { "id": "step_4", "description": "Write and run tests", "status": "pending" } ] } ```

This structure helps the Agent:

  • Track task progress.
  • Identify steps that are not yet complete.
  • Determine task dependencies.
  • Avoid duplicate execution.
  • Resume the task after an exception.

5. Task planning is not fixed once and for all

During development, it may turn out that the existing module already provides registration capability, or that the database model does not support the expected fields.

Therefore, the plan needs to be adjusted dynamically based on actual execution results.

For example:

  • Discovering an existing password encryption utility and canceling the duplicate implementation.
  • Discovering that the API specification requires a unified response format and adjusting the API.
  • Discovering that database fields are missing and adding a migration task.
  • Discovering that tests fail and adding a fix step.

A Coding Agent should treat the plan as an execution state that can be updated, not as an immutable static checklist.

V. Code Generation: How Does an Agent Write Code?

Only after understanding the project and completing task planning does the Coding Agent begin to write code.

1. The basic principle of code generation

A large model predicts subsequent Tokens based on the input context, generating code content step by step.

But in a Coding Agent, the model's context is not just the user requirement; it also includes:

  • The project's existing code.
  • The contents of relevant files.
  • Code conventions.
  • Dependencies and interface definitions.
  • The task implementation plan.
  • Tool execution results.
  • Historical modification records.

Together, this information determines the direction of the generated code.

2. Generating based on existing code

Suppose the project has already defined a user model:

```python class User: def __init__( self, email: str, password_hash: str ): self.email = email self.password_hash = password_hash ```

When implementing the registration feature, the Agent should reuse the existing model first, rather than creating a new set of user data structures.

For example:

def create_user(
    email: str,
    password_hash: str
):
    user = User(
        email=email,
        password_hash=password_hash
    )

    return user

A real project also needs to complete persistence by combining database Session, transactions, uniqueness constraints, and exception handling.

3. Constraints for Code Generation

When generating code, a Coding Agent should follow these constraints:

Language constraints

Use the programming language and version already used in the project.

Framework constraints

Follow the frameworks and components already used in the project.

Interface constraints

Maintain compatibility with existing APIs, function signatures, and data structures.

Style constraints

Follow naming, formatting, commenting, and directory organization conventions.

Security constraints

Avoid hard-coded secrets, plaintext password storage, and unsafe input handling.

Compatibility constraints

Avoid unauthorized modifications to other modules.

4. Creating New Files and Modifying Code

A Coding Agent may need to perform two different types of operations.

Creating a file

For example, adding:

app/api/register.py

Modifying an existing file

For example, modifying:

app/api/user.py

Both operations should record the file path and the changes made.

For files that already exist, localized modifications are usually preferred over rewriting the entire file.

This reduces the risk of accidentally deleting existing logic.

VI. Code Editing: How Does an Agent Safely Modify Files?

Code editing is one of the key differences between a Coding Agent and ordinary code generation tools.

An Agent not only needs to generate code but must also write it accurately into the target file and keep the scope of modifications controllable.

1. Full-File Overwrite

The simplest approach is to read the original file, generate a complete new file, and then overwrite the old file.

from pathlib import Path


def write_file(
    file_path: str,
    content: str
):
    path = Path(file_path)

    path.write_text(
        content,
        encoding="utf-8"
    )

This approach is suitable for:

  • Creating new files.
  • Modifying smaller configuration files.
  • Regenerating code files with simple structures.

However, for large files, full-file overwrite can easily introduce unnecessary changes.

2. Diff Patch Modification

A more common approach is to generate a code diff patch.

For example, original code:

def calculate_total(price, quantity):
    return price * quantity

After modification:

def calculate_total(
    price: float,
    quantity: int
) -> float:
    if price < 0:
        raise ValueError(
            "price cannot be negative"
        )

    if quantity < 0:
        raise ValueError(
            "quantity cannot be negative"
        )

    return price * quantity

The corresponding Diff:

-def calculate_total(price, quantity):
-    return price * quantity
+def calculate_total(
+    price: float,
+    quantity: int
+) -> float:
+    if price < 0:
+        raise ValueError(
+            "price cannot be negative"
+        )
+
+    if quantity < 0:
+        raise ValueError(
+            "quantity cannot be negative"
+        )
+
+    return price * quantity

A Diff can clearly express:

  • What code was deleted.
  • What code was added.
  • Which lines were modified.
  • Which files the changes involve.

This makes code modifications easier to review and roll back.

3. AST-Based Code Modification

AST (Abstract Syntax Tree) can be used not only for code analysis but also for code transformation.

For example, Python's AST can identify function definitions, parameters, return values, and expressions.

```python import ast source = """ def add(a, b): return a + b """ tree = ast.parse(source) for node in ast.walk(tree): if isinstance( node, ast.FunctionDef ): print(node.name) print(node.lineno) print(node.end_lineno) ```

AST modification suits code transformation tasks with clear structure.

For example:

  • Renaming functions in bulk.
  • Adding function parameters.
  • Replacing specific expressions.
  • Analyzing import dependencies.
  • Performing code structure migrations.

However, AST transformation requires extra attention to comments, formatting, decorators, and source code positions. Not every modification is suitable for manipulating the AST directly.

4. Comparison of Code Modification Approaches

Approach Advantages Drawbacks Use Cases
Full-file overwrite Simple to implement Prone to unrelated changes New files, small files
String replacement Direct operation Prone to false matches Well-defined, small-scope replacements
Diff Patch Clear changes Requires correct context matching Everyday code edits
AST transformation Structured, semantically explicit Complex to implement Bulk structural refactoring
IDE editing interface Can leverage editor context Depends on the specific environment Intelligent coding inside the IDE

5. Safety Checks Before and After File Modification

Before modifying a file, the Agent should check:

  • Whether the file exists.
  • Whether the file belongs to the current workspace.
  • Whether there are uncommitted user changes.
  • Whether the modification falls within the scope of the task.
  • Whether sensitive configuration is involved.
  • Whether user confirmation is required.

After the modification is complete, it should also check:

  • Whether the file was written successfully.
  • Whether the diff matches expectations.
  • Whether other code was deleted by mistake.
  • Whether formatting errors were introduced.
  • Whether unrelated files were modified.

6. The Complete File Modification Workflow

flowchart TD
    A["Identify the target file"] --> B["Read the original content"]
    B --> C["Analyze the scope of modification"]
    C --> D["Generate a modification plan"]
    D --> E["Generate a Diff patch"]
    E --> F["Check the patch context"]
    F --> G{"Is the patch reasonable?"}
    G -->|"No"| H["Regenerate the patch"]
    H --> E
    G -->|"Yes"| I["Check file modification permissions"]
    I --> J["Apply the patch"]
    J --> K["Re-read the file"]
    K --> L["Verify the final content"]
    L --> M["Record the file change"]

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style D fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style E fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style F fill:#EAF3EC,stroke:#83A995,color:#315D49
    style G fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style H fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style I fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style J fill:#EAF3EC,stroke:#83A995,color:#315D49
    style K fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style L fill:#EAF3EC,stroke:#83A995,color:#315D49
    style M fill:#DCEFE5,stroke:#4F8B70,color:#24563F

VII. Tool Calling: How Does the Agent Operate the Development Environment?

The capabilities of a Coding Agent depend to a large extent on which development tools it can call.

The model itself is responsible for decision-making and generating parameters, while the tools are responsible for carrying out the concrete operations.

1. Common Development Tools

Tool category Typical tools Main purpose
File reading Read, Glob Find and read files
File editing Edit, Write Modify and create files
Terminal execution Bash, Shell Execute commands
Code search Grep, ripgrep Search code
Version control Git View and manage code changes
Test execution pytest, Jest Run tests
Code linting Ruff, ESLint Static checks and style validation
Build tools Maven, Gradle, npm Compile and build
Debugging tools Debugger Analyze runtime issues

2. The Basic Mechanism of Tool Calling

Suppose the model needs to run tests.

It does not execute commands directly inside the model; instead, it generates a tool call request.

For example:

{
  "tool": "run_command",
  "arguments": {
    "command": "pytest tests/"
  }
}

After the tool executes, it returns the result:

{
  "exit_code": 0,
  "stdout": "12 passed",
  "stderr": ""
}

The model then decides the next step based on the result.

Note that tool call parameters must be validated by the program; you cannot simply grant unlimited system execution permissions just because the model generated a command.

3. The Tool Calling Loop

flowchart TD
    A["Agent analyzes the development task"] --> B["Select development tools"]
    B --> C["Generate tool call parameters"]
    C --> D["Validate tool parameters"]
    D --> E{"Is execution allowed?"}
    E -->|"No"| F["Deny or request authorization"]
    E -->|"Yes"| G["Execute tool"]
    G --> H["Obtain execution result"]
    H --> I["Return result to Agent"]
    I --> J["Model analyzes result"]
    J --> K{"Is the task complete?"}
    K -->|"No"| B
    K -->|"Yes"| L["Compile the final result"]

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style C fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style D fill:#EAF3EC,stroke:#83A995,color:#315D49
    style E fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style F fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style G fill:#EAF3EC,stroke:#83A995,color:#315D49
    style H fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style I fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style J fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style K fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style L fill:#DCEFE5,stroke:#4F8B70,color:#24563F

4. Tool Permission Tiers

Not all tools should have the same permissions.

They can be classified by operational risk:

Permission level Tool capability Control policy
Read-only View files, search code Generally allowed
Restricted write Modify workspace files Limit to specific directories
Standard execution Run tests and formatting Sandboxed execution
High-risk execution Install dependencies, modify configuration Review and restriction
Privileged execution Delete files, access external resources Explicit authorization
Release operations Push code, deploy to production Separate approval

Pay particular attention to the following:

  • Model-generated commands should not be concatenated directly into a high-privilege shell.
  • File access outside the workspace should be restricted.
  • Network access and sensitive environment variables should be restricted.
  • Permissions should be set for dependency installation and script execution.
  • Command injection and path traversal should be prevented.

8. Code Execution and Test Verification

After a Coding Agent generates code, it cannot rely solely on the model's judgment that the code is correct.

Results must be verified through actual execution and testing.

1. Why is testing needed?

Code generated by a model may contain:

  • Syntax errors.
  • Type errors.
  • Undefined variables.
  • Missing dependencies.
  • Incompatible interfaces.
  • Missed boundary conditions.
  • Business logic errors.
  • Concurrency safety issues.
  • Security vulnerabilities.

Therefore, a quality verification mechanism needs to be established after code generation.

2. Types of testing

Test type Purpose Common tools
Syntax check Check whether the syntax is valid Python, compilers
Type check Check for type issues mypy, TypeScript
Static analysis Identify potential code issues Ruff, ESLint
Unit testing Verify individual functions or modules pytest, Jest
Integration testing Verify collaboration between modules pytest, Testcontainers
End-to-end testing Verify complete business processes Playwright
Security scanning Check for known security risks Semgrep, dependency scanning tools
Build verification Check whether the project can be built Maven, Gradle, npm

3. Test-driven code fixes

For example, the Agent modified a calculation function:

def calculate_discount(
    price: float,
    discount: float
) -> float:
    return price * (1 - discount)

Tests can be written:

def test_calculate_discount():
    assert calculate_discount(
        100,
        0.2
    ) == 80


def test_zero_discount():
    assert calculate_discount(
        100,
        0
    ) == 100

But these tests are not enough.

You also need to consider:

  • Price is negative.
  • Discount is greater than 1.
  • Discount is less than 0.
  • Input is not a number.
  • Floating-point precision issues.

The purpose of testing is to verify business constraints, not just to verify that the code runs.

4. Fix mechanism after test failure

When a test fails, the Agent needs to read the error message and analyze the cause of the failure.

For example:

FAILED tests/test_user.py::test_create_user

AssertionError:
Expected password_hash
but received plain_password

The Agent should:

  1. Read the failing test.
  2. Locate the corresponding business code.
  3. Analyze the expected result versus the actual result.
  4. Find the root cause.
  5. Modify the code.
  6. Re-run the relevant tests.
  7. Run the necessary regression tests.

It must not simply modify the test assertions to make the tests pass.

5. Test verification loop

flowchart TD
    A["Complete code changes"] --> B["Run syntax check"]
    B --> C["Run static analysis"]
    C --> D["Run unit tests"]
    D --> E["Run integration tests"]
    E --> F["Aggregate test results"]
    F --> G{"Do all requirements pass?"}
    G -->|"Yes"| H["Perform code review"]
    G -->|"No"| I["Analyze the cause of failure"]
    I --> J["Locate the problematic code"]
    J --> K["Draft a fix plan"]
    K --> L["Modify the code"]
    L --> B
    H --> M["Generate verification report"]

    style A fill:#DCEFE5,stroke:#4F8B70,color:#24563F
    style B fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style C fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style D fill:#EAF3EC,stroke:#83A995,color:#315D49
    style E fill:#EAF3EC,stroke:#83A995,color:#315D49
    style F fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style G fill:#F7F4E8,stroke:#C7B77A,color:#675A2D
    style H fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style I fill:#F7EAE7,stroke:#C98D7C,color:#754438
    style J fill:#E0F0FE,stroke:#93BCE8,color:#1E4976
    style K fill:#EAE8FA,stroke:#A49BD5,color:#51477D
    style L fill:#EAF3EC,stroke:#83A995,color:#315D49
    style M fill:#DCEFE5,stroke:#4F8B70,color:#24563F

6. Passing tests do not mean the code is necessarily correct

Tests can only verify scenarios that are already covered.

For example, all unit tests for an interface passing does not prove that:

  • All inputs are valid.
  • Database transactions are necessarily safe.
  • Concurrent requests will not produce duplicate data.
  • The interface has no permission vulnerabilities.
  • The code will definitely run correctly in the production environment.

Therefore, a Coding Agent also needs to combine static analysis, code review, integration testing, and necessary manual verification.

IX. Code Review: How Does an Agent Check Its Own Changes?

After code generation and tests pass, code review is still required.

The goal of code review is not only to find syntax errors, but more importantly to determine whether the changes meet the requirements, whether they affect the existing system, and whether they introduce security risks.

1. Git Diff Analysis

Git Diff can show the specific changes in a code repository.

For example:

git status --short

git diff --stat

git diff

An Agent can use the Diff to check: