The Anatomy Of An AI Coding Agent, Part 1

The Brain: Models, Prompts, Reasoning, And Planning

AI coding agents are often described by what they do: write code, run tests, inspect errors, open pull requests, and review changes. But the more useful way to understand them is by looking at how they decide what to do next.

At the center of every agent is a language model. The model supplies language understanding, pattern recognition, and reasoning ability. But an agent like Cursor, Claude Code, or Codex CLI is not just "a model with a text box." It is a system wrapped around the model: prompts, tools, context, permissions, planning loops, and feedback.

A chat model can answer, "How would I add retry logic to this API client?" An agent can inspect the actual client, find the tests, edit the code, run the test suite, read the failure, revise the patch, and summarize the result.

That distinction matters. The model is the engine, but the agent is the vehicle.

The Model Is Not The Whole Agent

When people compare AI coding tools, they often start with the model: which vendor, which benchmark score, which context window, which coding leaderboard. Model quality matters, but it is only one part of agent quality.

Two products can use similar frontier models and still feel very different. One may be better at gathering context. Another may be better at file edits. Another may be more cautious with terminal commands. Another may produce clearer plans and summaries.

The model gives the agent raw capability. The surrounding system determines how that capability is applied.

A useful coding agent needs to know when to inspect, when to ask, when to edit, when to test, and when to stop. Those behaviors come from the agent architecture around the model.

Prompts Are Operating Instructions

Prompts are also part of the brain. In an agent, prompts are not just what the user types. There are usually several instruction layers:

- System instructions from the tool provider.

- Product and safety rules.

- Workspace or organization policies.

- Repository-specific guidance.

- Tool instructions and schemas.

- The current user request.

Together, these define how the agent behaves.

Good prompts make the agent more like a careful engineer. They say things like: inspect before editing, prefer existing project patterns, avoid unrelated changes, run tests after substantive edits, and ask before risky actions. These instructions do not make the model perfect, but they shape its judgment.

For example, a user might ask:

```text

Fix the failing auth test.

```

A basic assistant may jump straight into editing. A well-instructed coding agent should first inspect the failing test, understand the auth flow, avoid unrelated changes, preserve existing behavior, and run the relevant test afterward.

For teams, this means agent behavior is partly configurable. Contribution guides, repository rules, coding conventions, and security policies all become part of the agent's effective brain.

Reasoning Shows Up As A Loop

When people talk about agent reasoning, they sometimes imagine something mysterious. In practice, what matters is the observable loop:

1. Understand the goal.

2. Gather context.

3. Form a hypothesis.

4. Take an action.

5. Observe the result.

6. Adjust.

That loop is what separates useful coding agents from autocomplete.

If you ask an agent to fix a bug where archived projects appear in an active project picker, a weak agent may simply add a check like `!project.archived` in the nearest component. A stronger agent asks better questions. Where is "active project" defined? Is archived state a boolean, enum, or timestamp? Is there already a shared filter? Are there tests for this behavior?

The agent's reasoning shows up in the order of operations. It searches for the component, reads related helpers, checks tests, makes the smallest change, and verifies the result.

This is also where agents fail. They may overfit to a nearby variable name, miss a backend constraint, patch a symptom instead of a cause, or assume a convention that does not apply. Good agent systems reduce these failures by making context gathering and feedback cheap.

Planning Turns Intent Into Work

Planning is the bridge between a human request and a sequence of engineering actions.

For small tasks, the plan may be implicit: read the file, make the edit, run the test. For larger tasks, explicit planning matters.

Consider this request:

```text

Add support for SCIM group deprovisioning.

```

That is not a single edit. A reasonable plan might include understanding existing SCIM user deprovisioning, identifying group lifecycle models, inspecting API handlers, updating persistence behavior, adding tests, and documenting the new behavior.

A useful plan is not ceremony. It is a risk reducer. It helps the agent avoid wandering, and it gives the human a chance to correct the approach before code changes begin.

The best agents plan adaptively. Too little planning leads to scattered edits. Too much planning creates false confidence and slows down obvious work. The useful middle ground is simple: inspect enough to avoid guessing, then make the smallest safe change.

Context Is Part Of The Brain

The model can only reason over what it can see. That makes context management one of the most important parts of the brain.

Good context includes the user's request, relevant files and symbols, recent errors, test output, project conventions, and prior decisions in the conversation. Bad context includes stale assumptions, noisy generated files, unrelated code, or large dumps of material that bury the important signal.

More context is not automatically better. The right context is better.

If an agent is asked to update a form validation rule, it likely needs the form component, validation schema, tests, and maybe the API contract. It probably does not need the entire repository. Agents that search intelligently and read selectively often outperform agents that simply stuff huge amounts of code into the prompt.

What To Look For

When evaluating AI coding agents, do not only ask, "Can it write code?" Ask:

- Does it inspect before editing?

- Does it follow local conventions?

- Does it explain its plan at the right moments?

- Does it recover when tests fail?

- Does it keep changes scoped?

- Does it know when to ask for clarification?

- Does it preserve security and correctness constraints?

The brain of an agent is not just model intelligence. It is model intelligence shaped by instructions, grounded in context, organized by planning, and tested through feedback.

Conclusion

AI coding agents are easiest to use well when we understand their anatomy.

The brain combines a language model, layered prompts, context selection, reasoning loops, and planning behavior. When those pieces work together, the agent feels less like a code generator and more like a collaborator that can navigate a codebase, make scoped changes, and learn from feedback.

That does not remove the need for engineering judgment. It changes where that judgment is applied: in framing the task, reviewing the plan, setting constraints, and validating the result.