Architecting a Coding Assistant

Coding is the "Golden Use Case" for agents because code is Structured, Deterministic, and Verifiable. An agent that writes a React component can immediately "Test" that component to see if it works. This creates an internally closed loop of self-improvement.

In this lesson, we will learn how to transition from a "Chatbot that writes snippets" to a Coding Agent that manages repo-wide refactors.

---

1. Beyond the Snippet: Repo-Level Context

A simple LLM sees only the code you paste into the chat. A Coding Agent sees the Tree.

The Mapping Pattern:

1. Tool: list_files_recursive.
2. Step 1: Agent scans the src/ folder to understand the architecture.
3. Step 2: Agent reads package.json to see which libraries are available.
4. Step 3: Agent reads the specific file you want to edit AND its Dependencies (Imports).

Without reading dependencies, the agent will hallucinate function names and variable types.

---

2. Tools for the Coder Agent

To be effective, your agent needs "Hands" in the file system.

• Read Tool: read_file(path)
• Search Tool: grep_search(query) (Essential for finding where a function is defined).
• Edit Tool: replace_content(path, pattern, replacement) (Safer than overwriting the whole file).
• Execution Tool: run_shell_command(cmd) (To run npm start, tests, or linters).

---

3. The "Edit Control" Protocol

Giving an agent write_file permission is dangerous. It might delete your main.py by accident.

The "Diff" Pattern:

1. Agent proposes a Diff (Before vs. After).
2. The UI (Module 9.2) displays the diff to the user.
3. The user clicks "Apply."
4. The background tool performs the atomic replacement.

---

4. Multi-Step Refactoring Workflow

Refactoring a feature usually involves multiple files (e.g., updating a Backend API and the Frontend Component).

• Node 1 (Planner): "I need to change the user_id type in the DB, the API route, and the Profile page."
• Node 2 (Worker): Executes changes to File A. Runs tests.
• Node 3 (Worker): Executes changes to File B. Runs tests.
• Node 4 (Reviewer): Verifies that the whole app still builds.

---

5. Handling Large Context in Code

A codebase can be millions of lines. You can't fit it in a prompt. Strategy: Skeleton Indexing.

• You give the agent a "Skeleton" of the app: just the folder structure and the function signatures (without the logic).
• The agent "Requests" the full body of a function only when it believes it needs to edit it.

---

6. Security: The "Isolated Sandbox" (Again)

As discussed in Module 7, a Coding Agent MUST run in an isolated container. Why? If the agent tries to run npm install, it could download a malicious package. If it runs a Python script, it could execute rm -rf. Isolated Coder: The agent works in a "Disposable" Git clone. Once it's done, it provides a "Pull Request," not a direct edit to your production server.

---

Summary and Mental Model

Think of a Coding Agent like a Senior Software Engineer.

• They don't just write code; they Read the whole codebase first.
• They Plan their changes.
• They Test their work before submitting it to you.

Your job is to provide the "IDE" and the "Sandbox" for them to work in.

---

Exercise: Coding Agent Design

1. Hierarchy: You want an agent to "Convert this project from Javascript to Typescript."
   • Break this into 3 specialized sub-graphs.
2. Context: Why is grep_search a better tool for an agent than a simple read_all_files?
3. Safety: Draft a "Pre-execution" check for the run_shell_command tool.
   • Which 5 strings (regex) would you Blacklist to prevent system damage? Ready to give your agent a terminal? Next lesson: File System and Execution Tools.