What Is a Coding Agent 🤖

Every week a new article promises that the coding agent “will write the code for you”. Then reality kicks in: you need context, you need constraints, you need someone to validate. Before using any tool — GitHub Copilot, Claude Code, Cursor, opencode, Codex, Gemini CLI — it pays off to understand what is under the hood.

A coding agent is a program that uses a language model to interpret instructions, read the codebase and modify files. It is not a magician: it is a fast colleague with an awful memory.

The agent architecture 🏗️

All coding agents share the same basic structure, in four pieces:

Context — the information the agent receives: open files, repository instructions, conversation history. This is what the model “sees”.
Model — the engine that interprets the context and decides the next action. Different models have different capabilities and costs.
Tools — the operative capabilities: read and write files, run commands, search the code. Without tools, the agent would be just a chat.
Loop — the cycle where the model observes, decides, executes and observes again, until the task is complete or it stops.

The loop is why an agent differs from an autocomplete assistant: it does not just suggest, it acts. And every action can have consequences on your files.

What it can run 🛠️

The operative capabilities boil down to three families:

Reading and writing files — creating, modifying, deleting repository files. This is the skill you use the most, and the source of the most concrete risks.
Running commands — build, test, lint, dependency installation. The agent can run whatever you would run from the terminal.
Searching — looking up symbols, references and patterns across the whole repository, much faster than you would by hand.

This is the good part. The part that is missing is the one that makes the difference.

What it cannot do 🚫

Three magic expectations to debunk right away:

It does not know your codebase. The agent learns the project from the context you provide on every request. If you show it nothing, it produces generic code that vaguely resembles what you want. A prompt without context is like handing a new hire an empty desk and asking them to maintain your service.
It does not validate its own work. “I checked that it works” spoken by the agent is worthless. The only proof of correctness is build, test and lint actually run. Text is not a test.
It has no architectural judgment. It knows common patterns, not the ones your team chose. Without explicit instructions, it will invent a new convention whenever convenient.

The mental model: the new hire 👨‍💻

The most honest way to think about an agent is a new hire: smart, fast, tireless, but with three problems — it does not know the project, it does not know the conventions, and it does not know when it is going wrong.

With a new hire you would not say “let’s fix the authentication” and leave them alone. You would give them:

context (where the code is, how it is organized);
rules (conventions, boundaries, build commands);
a small, verifiable goal;
supervision on every step.

The same applies with the agent. The difference is that the new hire asks questions; the agent, left alone, guesses — and guessing on a codebase is the fastest way to produce a disaster with an air of competence.

Security and permissions 🔐

That is why modern agents have a permission model:

Read-only during analysis and planning phases: it can explore, but modify nothing.
Approval before sensitive operations: file edits, command execution.
Configurable boundaries: files or directories it must not touch, commands it must not run.

Setting these boundaries is not bureaucracy: it is the control you would apply to any tool that can modify your work. Treat command execution capabilities like an access key: grant them wisely, revoke them when not needed.

When NOT to use the agent ⛔

The agent is not the answer to everything:

Tasks slower to delegate than to do: a couple of lines where you know exactly what to write.
Codebases without context and without tests: if you cannot validate the output, you are trusting the quality to a chat.
High-level architectural decisions: choosing between two designs should not be delegated to something that does not know the business constraints.
Security and sensitive data: when the rules are not yet clear, the agent should not have access to project secrets.

Final checklist ✅

Did I provide the minimum required context (files, instructions, path)?
Did I define goal, constraints and acceptance criteria?
Do constant rules live in the repository, not in the prompt?
Did I configure permissions and boundaries before starting?
Will I validate the output with deterministic tools (build, test, lint)?