AI Coding Agent Architecture and Engineering Practices

1. From Code Completion to Agents: Three Levels of R&D Assistance

Over the past few years, AI-assisted development has evolved through three clear capability levels. Understanding their boundaries is a prerequisite for engineering deployment.

Level 1: Inline completion. The model predicts the next code snippet based on the current file and local context. The interaction pattern is “press key to accept.” It solves a typing-speed problem. It does not take responsibility for decisions, so it needs almost no permission governance.

Level 2: Conversational Q&A. Developers paste code, error messages, and logs, and the model returns explanations, fix suggestions, or refactoring options. The value is reducing the time spent searching for information and understanding unfamiliar code. However, the path from suggestion to implementation is still completed entirely by the developer. The human is the only executor.

Level 3: Agents. This is the real focus of current technical discussions. An agent no longer only outputs text. Given a goal, it can autonomously complete a closed loop: understand the requirement → search the codebase → plan changes → read and write files → execute commands → run tests → correct itself based on failure information → output a reviewable change set.

The fundamental difference among the three levels is not model capability, but autonomy boundary and feedback loop. The first two levels have no closed loop: the model cannot see the consequences of its output. The third level feeds execution results back to the model, forming a “perceive—act—observe” loop. It is precisely because execution authority is introduced at this level that the agent must answer a question that the first two levels do not need to answer: if it can modify files and run commands by itself, how can we prevent it from doing harm?

Therefore, the focus of engineering is not simply “choosing a stronger model,” but building a reliable runtime around the model. This runtime is usually called an AI coding agent. It consists of five parts: context engineering, tool layer, permissions and sandbox, orchestration layer, and observability.

2. Runtime Skeleton: How a Task Is Completed Step by Step

Any agent can be abstracted into the same main loop. If we strip away product-specific UI differences, the core structure is as follows (illustrative pseudocode):

while not done and budget remains:
    context  = assemble(task, repo_index, history)   # assemble the context for this turn
    plan     = model.decide(context)                 # the model decides the next action
    action   = parse_action(plan)                    # read file / retrieve / execute / write file
    if requires_approval(action):
        wait_for_human(action)                       # high-risk actions require human approval
    result   = sandbox.run(action)                   # isolated execution with unified truncation and redaction
    memory   = compress(context, result)             # compress history to control context growth
    if is_stuck(memory):                             # repeated actions, error loops, or no progress
        replan(task, memory)
    done     = verify(task, result)                  # compile, test, and static checks

In this skeleton, success is determined by four engineering details rather than the model itself:

1. Action parsing must be strict. Model output is essentially structured text with natural-language tendencies. The parser must tolerate minor imperfections, such as extra explanations or code-block wrapping, but it must never perform “guessed execution.” If parsing fails, the system should return a clear error message to the model so that the model can correct itself, instead of silently discarding the output.

2. There must be explicit termination conditions. These include maximum steps, maximum duration, maximum cost budget, and “no-progress detection.” Without this layer, the most likely failure mode of an agent is not that it does the wrong thing, but that it never stops.

3. Verification must be automatically executable. If task completion can only be judged manually at the end, the feedback loop is broken. Machine-verifiable signals, such as compilation, unit tests, static checks, and formatting checks, are the only basis for agent self-correction.

4. Observed results must be truncated. Compilation output may contain tens of thousands of lines. Feeding the entire output back will quickly flood the context. The engineering approach is tiered truncation: keep error summaries and key line numbers, save the full output to files, and allow the model to retrieve details on demand.

3. Context Engineering: The Hidden Infrastructure That Determines the Upper Limit of Capability

A counterintuitive conclusion in practice is: differences in agent effectiveness are often not caused by the model itself, but by context quality. The same model can perform noticeably better or worse depending on how context is organized, and this difference is often larger than the difference caused by switching models.

It is recommended to divide context into five layers and assemble them selectively instead of stacking everything together:

Layer	Content	Assembly principle
L1 Role and rules	Identity, output conventions, coding standards, prohibited actions	Short and stable, cacheable
L2 Repository map	Directory structure, module responsibilities, dependencies, build methods	Structured summary, updated with repository changes
L3 Task context	Requirement description, acceptance criteria, relevant files and symbols	Retrieve on demand, prefer precision over quantity
L4 Execution trace	Completed actions, observed results, excluded options	Rolling compression, keep conclusions and remove noise
L5 External knowledge	Team documentation, historical defects, interface specifications	Reference-based injection with source labels

Several practical lessons are worth emphasizing:

• Symbol-level retrieval is better than full-repository vector recall. The value of code lies in call relationships, not semantic similarity. Building symbol indexes, such as functions, classes, and constant definitions, together with call graphs, allows the agent to navigate precisely along “definition—reference” chains. This is more reliable than slicing the repository and performing similarity matching.

• The file system is the best long-term memory. Long tasks should not rely only on conversation history. Plans, progress, and conclusions should be written into structured files inside the workspace, such as task plans and decision records. After context compression, the agent can restore its state by reading those files. This also allows humans to review its reasoning.

• Actively prevent context pollution. If an early incorrect assumption remains in history, later turns may repeatedly reference and amplify it. A useful approach is to explicitly distinguish “confirmed facts” from “hypotheses to be verified” in the context, and to invalidate hypotheses when verification fails.

• Avoid putting large logs, dependency lock files, and generated artifacts into the context. These sources have low information density and high noise. They are among the most common causes of wasted context budget. Use ignore lists to filter them out during context assembly.

4. Tool Design: The Agent’s “Hands” Determine What It Can Do

A model can only do what its tools allow it to do. Therefore, tool-set design directly defines the capability boundary. A practical minimal tool set usually includes:

• Read operations: read files, list directories by pattern, keyword or symbol search, and view diffs.
• Write operations: create or modify files, apply patches, and create branches or working copies.
• Execution operations: build, test, static check, format, and run controlled scripts.
• Delegation operations: hand independent subtasks to isolated sub-agents.

Four principles for tool design:

1. Return structured results. Tools should return a unified shape such as {status, summary, details, truncated}, with clear error codes and actionable fix suggestions, rather than passing raw output directly to the model.

2. Make write operations atomic. Prefer generating a complete patch and applying it once, rather than rewriting lines randomly. This makes rollback and human review easier.

3. Validate before execution. Execution tools should first check whether the workspace is clean and whether dependencies are available, avoiding failures caused by dirty states that are hard to attribute.

4. Keep the number of tools restrained. The more tools there are, the higher the chance that the model chooses the wrong one. Prefer a small, orthogonal tool set over multiple overlapping tools with similar functions.

5. Permissions, Sandboxing, and Controllability: Let the Agent Act Without Breaking Things

This is the dividing line for enterprise adoption. Personal trials can follow a “run it first” approach, but team usage must define boundaries first. The core principle is least privilege: grant only the minimum read/write scope and command set required to complete the task.

workspace:
  root: ./sandbox/repo
  writable_paths: [ "src/", "tests/" ]
  read_only_paths: [ "config/production/", "secrets/" ]
commands:
  allow: [ "build", "unit-test", "lint", "format" ]
  deny:  [ "deploy", "push", "publish" ]
  require_approval: [ "install-dependency", "schema-migration", "delete-path" ]
network:
  egress: allowlist      # only necessary dependency sources are allowed; default deny
credentials:
  inject: none           # credentials do not enter model context; injected by execution environment on demand

Four supporting safeguards:

• Isolated execution. Agent commands should run inside containerized temporary workspaces that are physically isolated from developers’ real environments, production credentials, and internal resources. The environment should be destroyed when the task ends.

• Reversible changes. All write operations should be placed on separate branches or copies, with snapshots taken before changes. No single result should be difficult to undo.

• Approval points before high-risk actions. Human-AI approval should be reserved for a small number of high-value nodes: writing external dependencies, changing database schemas, deleting paths, committing and pushing code, and external publishing. The approval interface must present “diff + impact scope + verification result,” rather than forcing reviewers to guess what changed.

• Sensitive information governance. Keys, tokens, and customer data must not enter the context. Logs and traces should be redacted before being written to disk. This is relevant to both security and compliance auditability.

6. Multi-Agent Orchestration: When to Split and When to Stay Monolithic

Multi-agent architecture is not automatically better. Splitting can provide context isolation and parallel benefits, but it also introduces coordination overhead, result inconsistency, and shared-write conflicts.

Stay monolithic when: the task is a single-file change, a clearly scoped defect fix, or a short and tightly coupled task chain. Splitting such tasks only increases information loss.

Split when:

• Broad investigation is needed. When many modules must be scanned to locate relevant code, multiple sub-agents can search in parallel and return only conclusions and file paths.
• Independent parallel implementations are needed. Changes in different directories that do not depend on each other can proceed in parallel, but each must write to its own independent workspace. An upper-level orchestrator should merge the results later to avoid concurrent writes to the same directory.
• A long pipeline is needed. Requirement clarification → implementation → test supplementation → code review have different focuses and different context needs. Sequencing them by stage and isolating context for each stage is often more stable than using one giant context.

Two points are especially important in orchestration implementation: first, sub-agent results must be structured and evidence-based, including file paths, line numbers, and verification command outputs; otherwise, the upper layer cannot judge their reliability. Second, define the failure propagation strategy clearly: when one subtask fails, should the entire workflow roll back, or should it continue in a degraded manner? This must be decided during design.

7. Integration Into the Development Workflow: From Individual Technique to Team Infrastructure

An agent only becomes team capacity when it is embedded into existing development workflows. Common integration points include:

1. Local development. Use the agent as a controlled coding assistant that works on separate branches. Changes must be reviewed and merged by humans.

2. Code hosting events. Trigger automatic analysis when a merge request is created or a review is requested. The agent can produce impact analysis, risk points, and a list of missing tests.

3. Continuous integration pipelines. Use the agent for well-bounded automation tasks, such as generating fix suggestions from failed test cases, adding unit tests for new functions, or performing standardized code quality fixes. These tasks have clear boundaries and clear verification, offering strong return on investment.

4. Knowledge accumulation. Turn historical defects, review comments, and incident postmortems into searchable team knowledge, which can then feed back into the context layer.

At the platform level, a unified access gateway is useful. It exposes stable interfaces for task submission, status queries, and artifact retrieval, while abstracting underlying models, tools, and execution environments. The benefits are threefold: models can be replaced without changing business code; permission and audit policies can be enforced centrally; and costs can be aggregated by team, project, or task.

Cloud platforms can usually support this architecture by combining general-purpose capabilities. Container platforms can provide isolated sandboxes and elastic compute. Object storage can archive execution traces, change sets, and reports. Message queues can handle asynchronous task distribution and peak smoothing for long-running tasks. Logging and monitoring services can provide end-to-end observability. Key management services can manage credentials. Private networking and access control can ensure that code and data remain within required boundaries. For example, on Baidu AI Cloud, these capabilities are generally provided as reusable product categories, allowing enterprises to compose them according to their own compliance requirements without building infrastructure from scratch.

8. Evaluation and Measurement: No Measurement, No Improvement

Tuning an agent system depends heavily on quantifiable feedback. It is recommended to establish two layers of evaluation early.

Offline evaluation set. Collect 30–100 tasks from real repositories, each with clear acceptance criteria, to form a repeatable regression set. Whenever prompts, tools, or models change, rerun the set and observe whether key metrics regress.

Core metrics:

• Task completion rate, measured by the proportion of tasks that pass automated verification
• First-pass rate, measured by the proportion of tasks that do not require human rework
• Average interaction steps and average duration
• Cost per task, measured by token consumption and execution time
• Human intervention rate and distribution of intervention reasons
• Change rollback rate and classification of review rejection reasons

Online canary rollout. Enable a new version for a small number of teams or a small fraction of tasks first, compare key metrics, and then expand the scope. The value of this mechanism is turning “it feels better” into “the metrics actually improved.”

9. Typical Failure Modes and Countermeasures

Failure mode	Symptom	Countermeasure
Infinite loop	Repeatedly reading the same file or retrying the same command	Action fingerprint deduplication, no-progress detection, forced replanning
Out-of-scope refactoring	Modifying unrelated modules and expanding the impact scope	Limit writable paths, validate change scope, require a plan before implementation
Interface fabrication	Calling nonexistent parameters or methods	Force retrieval of real definitions first, rely on compile-time verification as a fallback
Context bloat	More steps but lower quality	Layered assembly, rolling compression, external memory on disk
False completion	Claiming a fix without verification	Completion judgment must be driven by automated verification results
Cost runaway	Abnormal consumption per task	Triple budget for steps, duration, and cost, with circuit breaking

10. Rollout Roadmap and the Boundary of Human-Agent Collaboration

A four-stage rollout is recommended. Each stage should have a clear capability boundary and exit criteria.

1. Pilot stage: read-only. Allow only Q&A and code retrieval. Do not grant write permissions. The goal is to validate the integration path, the evaluation set, and team acceptance.

2. Controlled write stage. Work in a single repository, on independent branches, with restricted writable paths and command allowlists. The goal is to accumulate real task samples under rollback-safe conditions.

3. Workflow integration stage. Integrate with merge request review and continuous integration, and include the agent in existing quality gates. This enables automated handling of regular tasks.

4. Platform governance stage. Multiple teams share a unified access gateway, with unified permissions, auditing, cost control, and evaluation. Team-level context and knowledge bases are accumulated at this stage.

Finally, the boundary of human-agent collaboration should be explicit. Agents are good at tasks with clear boundaries, verifiable outcomes, and rollback safety, such as locating defects, adding tests, performing bulk refactoring, writing boilerplate code, and organizing documentation. They are not suitable for independently handling ambiguous architectural decisions, production-impacting changes, or tradeoffs that require business context.

The right division of labor is not “the model does everything and humans only sign off.” Instead, the model should take on the high-frequency parts of exploration and execution, while engineers focus on requirement definition, solution design, risk assessment, and final verification. Mature improvements in engineering productivity come from turning this division of labor into processes and tools, not from a single impressive demonstration.