Case Study: Design a Coding Agent
"Design an AI coding agent — something like Claude Code — that a developer runs in a repository and asks to fix a bug or add a feature" is becoming a signature AI Engineer design question, because it exercises every part of the discipline at once: an agentic loop, tool design, a permission model, context management under a hard token limit, memory, cost control, security against untrusted content, and evaluation of a system whose output is actions, not text.
This subject is a model answer. It is deliberately Claude Code-shaped: the Claude Code Mastery track teaches how to use the real product — its tools, permission modes, CLAUDE.md, hooks, MCP and subagents — and this subject explains how you would design one, so the two reinforce each other. Where a design decision has a concrete instance in that track, it is called out. Numbers are illustrative assumptions.
Step 1 — Requirements, Users and Threat Model
Questions to ask
- Where does it run — a developer's terminal on their machine, a CI job, a hosted sandbox? Assume local terminal first, with a headless mode for CI later.
- What can it touch — the current repository, the whole filesystem, the network, package registries, git remotes? Assume the repo and its toolchain, with anything wider gated.
- Who is in the loop — an interactive developer, or nobody (autonomous)? Assume interactive by default, autonomous as an opt-in mode.
- What does "done" mean — a diff, passing tests, a commit, a PR? Assume a verified change (tests/lint pass) the developer reviews.
- Constraints — the model's context window (assume 200 k tokens), latency tolerance (seconds per step are fine), cost sensitivity (per task and per month), enterprise policy (no data leaves the machine except to the model API).
Assumptions to state
| Quantity | Assumption |
|---|---|
| Typical task | "Fix failing test", "add endpoint", "refactor module" — 10–60 tool calls |
| Repository | 50 k–500 k lines; far larger than the context window |
| Context window | 200 k tokens; a good session should rarely exceed 60–80 k in use |
| Cost target | cents to a few dollars per task; visible to the user |
| Success | change compiles, tests pass, developer accepts the diff |
| Threat model | untrusted content in files, docs, web pages and tool outputs; secrets on disk; destructive commands |
Non-goals: not an IDE; not an autocomplete; does not silently push to remote or run privileged commands.
The facts that shape the design: the repo does not fit in the window, the agent executes real commands, and everything it reads is untrusted input.