Build an AI Coding Assistant
The AI Projects series built a real code explainer — a single, one-shot read of one file. This part builds something genuinely different: an actual, multi-step agent that can search across an entire, real codebase and propose concrete changes, using this very site's own codebase as the real, working example.
The real, complete toolkit for a coding agent
tools = [
{
"name": "list_files",
"description": "List real files in a directory of this codebase",
"input_schema": {"type": "object", "properties": {"directory": {"type": "string"}}, "required": ["directory"]},
},
{
"name": "read_file",
"description": "Read the real, actual content of a specific file",
"input_schema": {"type": "object", "properties": {"filepath": {"type": "string"}}, "required": ["filepath"]},
},
{
"name": "search_codebase",
"description": "Search for a real, literal string across all files",
"input_schema": {"type": "object", "properties": {"query": {"type": "string"}}, "required": ["query"]},
},
]This directly reuses part 10's scoped file-system pattern — read_file uses the exact same real path-traversal protection covered there, since a coding agent reading arbitrary real files is exactly the kind of tool that genuinely needs that safety boundary.
The real, complete agent
SYSTEM_PROMPT = """You are a coding assistant for this site's own
Next.js and Python codebase. When asked about a real feature,
search and read the actual, relevant files before answering — never
guess at code you haven't actually read. When proposing a change,
show the real, exact diff, and explain your reasoning."""
def run_coding_agent(request: str) -> str:
messages = [{"role": "user", "content": request}]
for _ in range(10): # code exploration genuinely needs real depth
response = client.messages.create(
model="claude-sonnet-5", max_tokens=4096,
system=SYSTEM_PROMPT, tools=tools, messages=messages,
)
messages.append({"role": "assistant", "content": response.content})
if response.stop_reason != "tool_use":
return response.content[0].text
tool_call = next(b for b in response.content if b.type == "tool_use")
result = tool_functions[tool_call.name](**tool_call.input)
messages.append({
"role": "user",
"content": [{"type": "tool_result", "tool_use_id": tool_call.id, "content": str(result)}],
})
return "This needs human review — exceeded expected exploration depth."A real, concrete example run
print(run_coding_agent("How does the tutorial slug redirect logic work, and where is it implemented?"))Real, expected execution trace:
Iteration 1: search_codebase("redirect") → finds candidate real files
Iteration 2: read_file("app/tutorials/[...slug]/page.tsx") → reads
the actual, real redirect implementation
Iteration 3: has enough real information → generates a genuine,
accurate explanation citing the real, specific file and functionThe explicit "never guess at code you haven't actually read" instruction directly addresses the AI Fundamentals series' own hallucination concern, applied specifically here: a coding assistant confidently describing behavior it never actually verified by reading the real, current code is a genuinely dangerous, real failure mode — plausible-sounding but potentially describing outdated or entirely fabricated behavior.
Proposing real, concrete changes — not just explaining
CHANGE_PROMPT_ADDITION = """When asked to make a change, read the
real, current file first, then output the change as a unified diff
format, showing exactly what real lines change."""Real, expected output format:
--- app/tutorials/[...slug]/page.tsx
+++ app/tutorials/[...slug]/page.tsx
@@ -58,6 +58,9 @@
const tutorial = getTutorialBySlug(slug);
if (!tutorial) {
+ // real, proposed additionRequesting a real, standard diff format — rather than a full, rewritten file or vague prose description — makes the agent's proposed change genuinely reviewable at a glance, directly connecting to part 21's common-mistakes coverage of blindly trusting agent output without real, human review of the actual, specific change.
A real, deliberate limit: this agent proposes, it doesn't commit
This agent reads and proposes real changes — it does NOT
automatically write files or run git commands, directly following
the same real, deliberate caution the LLM & Advanced AI series
applied to consequential agent actions generallyA real, human developer reviews every proposed diff before it's actually applied — exactly the same "queue for review" pattern established for GreenDesk's email generator and cancel/refund workflow throughout this site's AI series, applied here to code changes specifically.
FAQ
Why 10 iterations here when part 6's inventory agent used 5? The right ceiling depends on the task, not a fixed rule — code exploration across multiple files genuinely needs more back-and-forth (list, then read, then search again) than a simpler lookup task does. The number should reflect what a successful run of that specific task actually takes, not be copied from another part.
Is read_file safe to point at any path the model requests?
Not without a boundary — the text notes this reuses part 10's path-traversal protection specifically because an unrestricted read_file would let the model read anything on the filesystem the process has access to, not just this codebase. That scoping is a required part of this tool, not optional hardening.
Why output a diff instead of having the agent just rewrite the whole file? A diff makes exactly what changed reviewable at a glance — a full rewritten file forces a human reviewer to compare it line-by-line against the original to find what's actually different, which is slower and more error-prone for catching an unintended change.
Next: giving your coding assistant real project context — indexing this site's codebase for faster, more accurate real navigation.