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:
- Understand the user's requirements.
- Analyze the project's directory structure.
- Identify the programming language and frameworks in use.
- Locate the existing user module and API conventions.
- Understand the database models and business logic.
- Draft a plan for the code changes.
- Create or modify the relevant files.
- Install or invoke the necessary dependencies.
- Run code checks and tests.
- Fix the code based on error messages.
- Review the final changes.
- 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:
- Analyze the existing user module.
- Check the user model and database constraints.
- Check the existing password handling logic.
- Define the registration request and response structures.
- Implement the registration business logic.
- Add the API route.
- Write unit tests.
- Run the tests and fix errors.
- 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:
- Read the failing test.
- Locate the corresponding business code.
- Analyze the expected result versus the actual result.
- Find the root cause.
- Modify the code.
- Re-run the relevant tests.
- 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: