Design a Coding Agent
A coding agent reads and patches a repo through tools, runs tests in a jail, and ships a PR for a human. Dumping the whole codebase into context is not a design; it's a bill and a leak.
Explain like I'm new to AI
Humans don't memorize the company monorepo to fix a bug. Neither should the model. Explore → edit → verify → review.
Tests (or typecheck) in a sandbox. The verifier is code, not another model's vibes. Loop cap.
Job: produce a change that passes checks for this task. SLO: tests green, limited steps, no secret exfil, p95 that a developer will wait (or overnight batch).
Shape: agent (the path through the repo is unknown) with a hard cap and a verifier.
Mental model
A contractor with a badge to the repo, a laptop that can't see ~/.aws, and a rule: nothing merges without CI + a person.
How it works
- Tools:
list,grep/search,read,apply_patch,run_tests. Not unrestricted shell if you can avoid it. - Context: retrieve/grep first (code RAG). Pack only the files that matter (context engineering).
- Verify: unit tests, typecheck, linters — code as judge (evaluation / GRPO-style when you train; at serve time it's just CI).
- Sandbox: no home directory, egress allow-list, no Docker socket (secrets-sandboxing).
- HITL: the pull request. Show the diff. The model cannot click merge.
- Eval: held-out tasks (issue → failing test → patch). Trajectory eval, not BLEU on the chat.
- Loop cap and $ cap (unbounded consumption).
Real-world example
Agent "fixes" auth by printing a key it found in .env into the reply. Jail + don't index secrets + output filters. Tests wouldn't catch the leak — security eval would.
Technical explanation
Long-context models still lose the middle of a 400-file dump. Tools beat paste.
MCP for repo tools is fine; treat the server like installable software (MCP security).
Multi-agent "writer vs reviewer" can help if the reviewer is tests + linter, not another ungrounded LLM arguing.
Common mistakes
Pasting the repository into the prompt because the window is "a million tokens."
execon the developer machine.- No tests, only "looks like good code."
When to use it
- Well-tested repos, scoped tasks, humans who will read PRs.
When NOT to use it
- Don't unleash write tools on prod. Don't skip sandbox "because it's local."
- Greenfield "build me an app" with no tests is a generator, not this design.
Alternatives
- Completions in the editor (chatbot). Workflow: generate patch from a fixed template. Human pair-programming.
Quick quiz
Related concepts
- Secrets Management and Sandboxing — Keep keys out of prompts, run untrusted work in a jail with an egress allow-list, and cap loops and spend so agents cannot become a denial-of-wallet.
- Human-in-the-Loop — Human-in-the-loop inserts a person's approval before risky or irreversible agent actions, combining autonomy with safety and accountability.
- Planning & Reflection — Planning breaks a goal into sub-tasks before acting, and reflection lets the agent critique and fix its own work — together they make agents far more reliable.
Last reviewed: 2026-09-04 · Written by ByHeart AI · Reviewed by ByHeart AI