B
Basil AI
1 / 16
Interactive Guide · 16 Slides

How Claude Code
Actually Works

What happens between your prompt and the code change —
and why the harness matters more than the model

Navigate with ← → arrow keys, click the arrows, or swipe

Weekly insights on AI coding and agent architecture. No spam.

Slide 2 · The Big Misconception

Most people think Claude Code = Claude Opus with a terminal.

✗ Myth

Just use Claude Opus and give it a terminal. Same thing.

✓ Reality

Claude Code = Opus + an agentic harness that gives it tools, memory, and a feedback loop.

Without the harness

You paste code into the chat, Claude responds with text suggestions, you manually copy the changes, paste them back, run the tests yourself, then paste failures back in — forever.

With the harness

Claude reads your files directly, edits them in place, runs your tests, sees the failures, fixes them — and only tells you when it's done. You never copy-paste anything.

Slide 3 · The Architecture

The System Prompt — The Blueprint

Before Claude writes a single line of code, the harness assembles a layered context that tells it what it can do, what it knows, and how to behave.

Your Prompt
The task you give Claude — lands on top of all these layers
Claude sees everything below when it reads your request
MCP Servers
External service connections: databases, Slack, Jira, browsers
Each server adds tool definitions to the context
Skills (on-demand)
Descriptions of available skills loaded at start
Full skill content only loaded when relevant — saves context  ·  Your custom workflows: /deploy, /review, /release
CLAUDE.md + Rules
Your project-specific instructions, loaded every session
Build commands, code style, testing conventions, 'never do X' rules  ·  .claude/rules/ files load conditionally based on file paths
Tool Definitions
Every tool Claude can use, with exact schemas
Read · Edit · Bash · Glob · Grep · Agent · LSP · WebFetch  ·  The model sees these as callable functions — it decides when to use each one
System Instructions
Core identity: you are Claude Code, an agentic coding assistant
Safety rules, ethical guidelines, response formatting
⬆ built from bottom to top — foundation → your message
💡

This is why CLAUDE.md matters so much — it's injected into every single API call. The model sees it before your message. It's not a config file you set once; it's part of every conversation.

🔄

The harness doesn't just pass your message to the model. It assembles this entire context, sends it as one API call, receives the model's response (which might include tool calls), executes those tools, then sends the results back — in a loop.

Slide 4 · Core Concept

The Agentic Loop

Three phases that blend together — Claude decides what each step requires based on what it learned from the last one.

Phase 1
🔍
Gather Context
Read files, search code,
understand the codebase
→
Phase 2
⚡
Take Action
Edit files, run commands,
make changes
→
Phase 3
✅
Verify Results
Run tests, check output,
fix failures
↩ Loops back — each iteration informed by the last
Slide 5 · The Tool Layer

What makes it "agentic"

Without tools, Claude can only respond with text. With tools, Claude can ACT. The harness gives Claude five categories of action:

📁
File Operations
Read, edit, create, and delete files directly in your project
🔎
Search
Find files by name, grep for patterns, jump to symbol definitions
⚙️
Execution
Run shell commands, test suites, build scripts, and git operations
🌐
Web
Search docs, fetch references, look up API specs on demand
🧠
Code Intelligence
Type errors, jump to definitions, language server integration
Slide 6 · Real Example

"Fix the failing tests" — step by step

1
Runs the test suite → sees what's failing
exec: npm test
2
Reads the error output → understands the problem
parse: stderr + stack trace
3
Searches for the relevant source files
search: grep "UserService" --include="*.ts"
4
Reads those files → understands the full context
read: src/services/UserService.ts
5
Edits the file → implements the fix
edit: src/services/UserService.ts (lines 42-58)
6
Runs tests again → verifies it works
exec: npm test → ✓ 47 passed, 0 failed

Each tool call gives Claude new information that informs the next step.

Slide 7 · Architecture

The Harness is the Body

The model provides intelligence. The harness provides the senses, hands, and memory to act on it.

🧠
Model
Claude Opus
Reasoning & generation
+
🤖
Harness
Claude Code
Tools, memory, execution loop
=
🚀
Result
Coding Agent
Reads → edits → verifies

Claude Code serves as the agentic harness: it provides the tools, context management, and execution environment that turn a language model into a capable coding agent.

Slide 8 · The Biggest Constraint

Context Window — the limiting factor

LLM performance degrades as the context window fills up. The harness manages this so you don't have to.

Context window usage 200K tokens
Fresh session
Mid-session (files + outputs)
Deep debugging session
💬Conversation history
📄File contents
🖥️Command outputs
📋CLAUDE.md
⚙️System instructions
🔧Tool definitions

The harness auto-compacts, clears stale tool outputs, and summarizes history when the window fills.

Slide 9 · Persistent Memory

CLAUDE.md — how Claude remembers your project

The model forgets everything between sessions. CLAUDE.md is what the harness loads at the start of every conversation — your project's persistent memory.

# CLAUDE.md — loaded every session automatically

## Build Commands
npm run dev # start dev server
npm test # run test suite

## Code Style
# Use functional components. No classes. Prefer async/await.
# All API calls go through src/api/client.ts — never fetch() directly.

## Key Decisions
# We moved off Redux in Jan 2025. State is Zustand + React Query only.
# UserService is the source of truth for auth. Do not duplicate logic.

Without it: every session starts from zero. With it: Claude knows your project from the first message.

Slide 10 · Advanced Harness Features

Skills & Subagents

The harness is an orchestrator, not just a wrapper. It can load knowledge on demand and spawn fresh instances for complex work.

📦
Skills
load-on-demand knowledge

Structured knowledge packets loaded only when relevant. A "git workflow" skill, a "testing conventions" skill — each injected into context only when needed. Saves precious context space for everything else.

🤖
Subagents
independent context windows

Spawn a fresh Claude instance with its own context window for a subtask. Their work doesn't bloat your main session. They return a summary when done. Perfect for parallel work or long sub-tasks.

Why this matters: A subagent writing tests for 10 files uses its own 200K context — not yours. You get the results back as a tidy summary. The harness handles the orchestration automatically.

Slide 11 · Safety & Control

Permission & Safety Layer

The harness controls what Claude can and can't do. Autonomy comes with guardrails built in.

🙋
Default Mode

Asks before every file edit and shell command. You approve each action. Maximum control, slower workflow.

⚡
Auto-Accept

File edits happen freely. Still asks before running shell commands. Good balance of speed and safety.

📋
Plan Mode

Read-only. Claude explores your codebase and produces a complete plan for you to review before any changes.

Checkpoints

Every file edit is checkpointed. You can rewind to any previous state — like a git undo for the entire session.

Allowlists

Define which shell commands are always allowed, which always need approval, and which are blocked entirely.

Slide 12 · The Comparison

Claude Opus is a brain in a jar.
Claude Code gives it a body.

Capability Just Opus Claude Code
Codebase access You paste code manually Reads your entire codebase
File edits You copy output back Edits files directly
Workflow One-shot Q&A Multi-step autonomous work
Memory Gone between messages CLAUDE.md + auto-compact
Verification You check everything Runs tests, self-corrects
Context Single shared context Subagents with independent contexts
Slide 13 · Build Your Own

Build Your Own Mini Claude Code

Now that you understand the pattern, you can build domain-specific agents for your use case. Here's the recipe:

1
Pick your model
Any LLM with tool use — Claude, GPT, Gemini, or a local model. The pattern is model-agnostic.
2
Define your tools
What actions does your agent need? Read files, call APIs, query databases, run scripts — define each as a function with a schema.
3
Build the loop
prompt → tool call → result → next decision → repeat until the task is done or a stop condition is reached.
4
Add memory
A CLAUDE.md equivalent — persistent instructions your agent loads every session. Project context, rules, decisions.
5
Add guardrails
Permission checks, checkpoints, and human-in-the-loop for dangerous or irreversible actions.
DevOps AgentReads logs, diagnoses issues, applies fixes, verifies health checks
Data Pipeline AgentReads schemas, writes queries, validates output, generates reports
Content AgentReads brand guidelines, drafts content, checks tone, publishes — literally what we built at Basil AI
QA AgentReads tickets, writes test cases, runs tests, files bugs

Claude Code isn't magic. It's a well-designed harness. You can build the same pattern for any domain.

Slide 14 · The Code

The Entire Pattern in ~30 Lines

This is the skeleton of every agentic harness. Claude Code, Cursor, Copilot — they all follow this loop.

// 1. Assemble the context
const systemPrompt = buildContext({
  identity: "You are an agent that can read files, run commands, and edit code.",
  tools: [readFile, editFile, runCommand, search, webFetch],
  memory: loadProjectRules("CLAUDE.md"),
  skills: discoverSkills("./skills/"),
  guardrails: { askBefore: ["delete", "deploy", "push"] }
});

// 2. The agentic loop
let messages = [{ role: "user", content: userPrompt }];

while (true) {
  // Send everything to the model
  const response = await model.chat({ systemPrompt, messages });

  // If no tool calls, we're done
  if (!response.toolCalls) break;

  // Execute each tool, collect results
  for (const call of response.toolCalls) {
    if (needsApproval(call)) await askUser(call); // guardrails
    const result = await executeTool(call);
    messages.push({ role: "tool", result });
  }

  // Loop back — model sees tool results, decides next step
}
← That's it. The rest is implementation details.
Swap model.chat for any LLM with tool use.
Slide 15 · The Takeaway

The model is the engine.
The harness is the car.

You wouldn't judge a car by its engine alone. The transmission, steering, brakes, and suspension matter just as much.

The harness pattern — tools + loop + memory + guardrails — is the blueprint for every useful AI agent, not just coding ones.

🔧 Tools
🔄 Agentic Loop
🧠 Memory
🛡️ Guardrails

Same engine. Radically different cars.

Stay up to date on AI development tools and agent architecture

Weekly insights on AI coding, agent design, and building in public.
No spam. Unsubscribe any time.

From Basil AI · Privacy Policy