An AI coding agent is a large language model (LLM) given controlled access to your codebase and a few tools, wrapped in some scaffolding for planning, indexing, and safety. Most of the “smarts” live in the model; the agent layer mostly handles what the model can see and do. This guide demystifies how they work under the hood.
To see these principles in action and truly understand how the pieces fit together, join us for a free workshop this Monday. Isaac and Eleanor will be building a simple AI coding agent from scratch, live with participants. It is a fantastic, hands-on opportunity to learn how these agents really work.
The Core Idea
Despite the hype from many agentic coding vendors, the architecture of a modern AI coding agent is surprisingly straightforward. At its heart, an agent does three simple things:
Connects a model to your files (read, search, write) and to a shell (run commands, tests).
Lets the model call tools through structured function calls.
Loops: think → choose a tool → run it → read the results → decide the next step.
That’s the fundamental pattern. The subtle differences between agents are largely in how they handle context, safety, and user experience — not in a completely different kind of intelligence.
The Core Loop (Agentic Mode)
A minimal coding agent repeats this cycle to accomplish a task:
Perceive: Load the current task description and a slice of repository context (relevant files, file tree, search hits).
Plan: Propose the next logical step (e.g., “search for all usages of FooService”).
Act: Call a specific tool (search, read_file, write_patch, run_tests).
Observe: Capture the tool’s output (grep results, a diff, test failures).
Decide: Based on the new information, continue the loop or stop and produce a final result, like a pull request or a patch file.
Two common planning styles guide this loop:
Reactive (ReAct): The agent decides one small step at a time based on immediate observations. This is great for simple, iterative tasks.
Plan-and-Execute: The agent drafts a multi-step plan up front, then executes each item, revising the plan as needed. This is better for complex features that touch many files.
The Standard Toolbelt
Most agents expose a similar set of built-in tools to the LLM. The exact names may vary, but the capabilities are standard:
Search / grep: Find symbols, function calls, or text snippets across the repository.
Read file / list files: Fetch the exact contents of one or more files. Good agents can read specific line ranges to save context space.
Write / patch file: Apply minimal diffs (.patch files or simple string substitution) rather than rewriting entire files. This is safer and avoids overwriting unrelated changes.
Run command: Execute shell commands like formatters, linters, build scripts, and any other command-line tools that may be useful in the process.
Version-control helpers: Create a new branch, craft a commit message and pull request, or summarize file diffs.
Web fetch / search: Pull in documentation, API examples, or information from Stack Overflow.
Scaffolding That Makes Agents Feel “Smart”
In addition, agents often optimise the operation of the core loop with scaffolding - the surrounding infrastructure that makes the loop efficient and reliable.
Code Indexing & Retrieval
To find the right context, some agents build a searchable index of the repository. This is often a combination of symbol-based search (using ctags or language servers), Abstract Syntax Tree (AST) analysis, and embeddings for semantic search (e.g., “find the auth middleware in our monorepo”).
Planning & Orchestration
Some agents switch between planning styles. They might use a plan-and-execute strategy for a broad feature request but switch to a reactive mode to fix a series of linting errors.
Guardrails & Sandboxing
Safety is paramount. Many agents have the ability to execute commands in isolated environments (like Docker containers or OS-level jails) with restricted capabilities. They use allow-lists to define which folders, commands, and network addresses are permitted and require human approval for potentially risky actions.
Human-in-the-Loop UX
Most coding agents don’t run completely autonomously. They provide a transparent user experience by showing their plan, logging all actions, and ultimately generating pull requests for human review instead of committing directly to a main branch.
⚡ ProfessionalAI-powered Software Development is not about what tools you use, but about how you use them. It requires a more deliberate approach, and some new techniques, but is an important addition to the toolbox of developers and engineering and product leads moving to an AI-native Software Development Lifecycle.
