How AI Coding Tools Actually Work

Cursor, Claude Code, Windsurf, Copilot. If you have used any of them, you know the two feelings: the one where it reads your mind, and the one where it confidently edits the wrong file.

Both feelings come from the same machinery. This article opens the box. Once you see the mechanism, the magic and the mistakes both stop being mysterious, and you get better at steering the tool.

They are agents pointed at your repo

An AI coding tool is an agent: an LLM in a loop with tools. The only thing special about it is which tools it has. Instead of “search the web” or “send an email,” the tools are things like:

read_file(path), read a file in your project
edit_file(path, changes), change one
search(query), find code across the repo
run_command(cmd), run a shell command or the tests

Give a model those tools and a goal (“add rate limiting to the login endpoint”), and it does what any agent does: reads what it needs, makes changes, runs things to check, and repeats until the task looks done.

The loop inside a coding tool

Here is the plan-act-observe loop wearing coding-tool clothes:

flowchart LR
    GOAL([Your request]) --> READ[Read relevant<br/>files]
    READ --> PLAN[Propose an edit<br/>or command]
    PLAN --> RUN{Apply or run?}
    RUN -->|edit| EDIT[Change the file]
    RUN -->|command| CMD[Run tests, build]
    EDIT --> OBS[Observe result]
    CMD --> OBS
    OBS --> PLAN
    PLAN -->|done| DONE([Diff ready<br/>for review])

Ask for a change and the tool reads the files it thinks are relevant, proposes an edit, applies it, maybe runs the tests, reads the output, and adjusts. The loop ends when it believes the goal is met and hands you a diff.

The important word is believes. The tool stops when the model decides it is done, which is not always when it is actually done. That gap is why review is your job, not the tool’s.

Where context comes from, and why it matters most

A model only knows what is in its context window. A coding tool cannot fit your whole repo in there, so before it does anything, it has to choose which slices of your codebase to load.

That selection is the single biggest driver of output quality. Feed it the right files and it writes code that fits your conventions. Feed it the wrong ones, or too many, and it guesses.

Tools gather context a few ways:

Automatically, by searching the repo for code related to your request.
From what you point at, files you open or mention explicitly.
From project rules, a config file that tells the tool about your stack and conventions.

Why does it sometimes edit the wrong file or ignore my conventions?

Because the right file, or your conventions, were not in the context window when the model made its decision.

The model is not looking at your repo. It is looking at whatever text the tool loaded for this step. If the tool’s search missed the file that actually defines your auth logic, the model works from what it did load and produces something plausible but wrong.

This is why pointing the tool at the right files, and writing a rules file, matters so much. You are not “helping” a tool that could have figured it out on its own. You are supplying information it literally did not have.

Two modes: autocomplete and agent

The tools blur together, but they run in two very different modes, and confusing them leads to bad expectations.

	Autocomplete	Agent mode
What it does	Suggests the next few lines as you type	Takes a goal and edits across files
Calls to the model	One, per suggestion	Many, in a loop
You stay	In the driver’s seat, typing	The reviewer of a finished change
Good for	Filling in the obvious next line	Multi-step tasks, features, refactors

Autocomplete (the Copilot-style tab suggestion) is a single model call: here is my cursor, guess what comes next. Agent mode (Cursor’s Composer, Claude Code, Windsurf’s agent) is the full loop above. Same underlying models, completely different interaction.

What this means for how you work

If the tool is an agent that writes code, your role shifts. You spend less time typing and more time doing three things:

Framing the task clearly enough that the model can plan it.
Supplying context, the right files and a rules file, so it works from facts.
Reviewing the diff, because the tool stops when it thinks it is done, not when it is correct.

The engineers who get the most out of these tools are not the ones who trust them most. They are the ones who scope tasks well, feed context deliberately, and read every line before accepting it.

Common beginner mistakes

Treating agent mode like autocomplete. Firing a one-line request at a tool that will edit ten files, then being surprised by the blast radius.
Not supplying context. Expecting the tool to know a file it never loaded. Point it at the relevant code.
Skipping the rules file. Every session starts from zero on your conventions unless you write them down once.
Accepting diffs unread. The tool stops when it thinks it is done. Only you know if it is right.
Huge vague tasks. “Refactor the app” gives the model no path. Scope it down.

Questions you will face in production

“Is it safe to point this at my production codebase?” The editing is safe; the accepting is where risk lives. Work on a branch, let the tool make changes, and treat its diff exactly like a pull request from a fast but junior engineer: reviewed, tested, and never merged unread.

“Why does the same prompt give great results in one repo and bad ones in another?” Context. A repo with clear structure and a good rules file gives the model facts to work from. A sprawling one without conventions leaves it guessing. The tool is only as good as what it can load.

“Can I give it access to our internal tools and APIs?” Yes, through custom tools. The standard way to expose your own systems to a coding tool is MCP, which lets you add tools the agent can call without the tool’s vendor building the integration.

What to remember

AI coding tools are agents whose tools read, edit, search, and run code
They run the same plan, act, observe loop as any agent
Output quality is driven mostly by context: which files the model can see
Autocomplete is one model call; agent mode is the full loop
The tool stops when it thinks it is done, so reviewing the diff is your job
Your value shifts from typing to scoping, context, and review

What to study next

The rest of this curriculum is about doing each of those three jobs well: choosing a tool, setting up context and rules, prompting the agent, and reviewing what it writes.

If the “agent” framing was new, the clearest foundation is what an AI agent actually is; everything a coding tool does is that loop with file-editing tools.