How Claude Code Works

Story: The Architecture Behind the Magic

Daniel was a senior backend engineer who'd been using Claude Code for a week with mixed results. Some prompts gave him astonishing outputs -- perfectly structured code that matched his project's patterns. Other prompts produced generic, almost useless suggestions. The difference was maddening.

One afternoon, his teammate Priya watched him struggle. "You're asking it to fix the auth middleware, but you're not giving it any context about which auth middleware," she said.

"It should figure that out," Daniel replied. "It can see the whole codebase."

Priya shook her head. "It can see the whole codebase, but it doesn't automatically read every file. It has to decide what to read, and your prompt is too vague for it to know where to start. Watch."

She sat down and typed: "The JWT validation in our Express auth middleware at src/middleware/auth.ts is not checking token expiration. Fix it and add a test."

Claude Code immediately read the specific file, understood the JWT library being used, found the missing expiration check, wrote the fix, then read the existing test file to match the testing pattern before generating a new test case. Clean, precise, effective.

"The difference," Priya explained, "is that I understood how Claude Code thinks -- what it can see, how it decides what to do, and what information helps it make better decisions. Once you understand the architecture, you stop fighting the tool and start working with it."

That conversation changed Daniel's entire approach. And it's exactly what this lesson will do for you.

Concept: The Architecture of Claude Code

System Overview

Claude Code is not a single monolithic program. It's a carefully orchestrated system with several distinct components working together. Understanding these components will transform you from a casual user to a power user.

+---------------------------------------------+
|              YOUR TERMINAL                   |
|  +---------------------------------------+   |
|  |         Claude Code CLI               |   |
|  |  +---------+  +------------------+    |   |
|  |  | Input   |  |  Tool System     |    |   |
|  |  | Parser  |  |  +------------+  |    |   |
|  |  |         |  |  | Read       |  |    |   |
|  |  +---------+  |  | Write      |  |    |   |
|  |       |       |  | Bash       |  |    |   |
|  |       v       |  | Grep/Glob  |  |    |   |
|  |  +---------+  |  | Edit       |  |    |   |
|  |  | Context |  |  +------------+  |    |   |
|  |  | Manager |  |                  |    |   |
|  |  +---------+  +------------------+    |   |
|  |       |                               |   |
|  +-------+-------------------------------+   |
|          |                                   |
|          v                                   |
|  +---------------+                           |
|  | Anthropic API | (Claude model)            |
|  +---------------+                           |
+---------------------------------------------+

Let's break down each component.

Component 1: The CLI Interface

When you type claude in your terminal, you're launching the CLI (Command Line Interface). This is your primary interaction point. It handles:

• Input parsing: Taking your natural language prompts and formatting them for the model
• Output rendering: Displaying Claude's responses, including formatted code blocks, diffs, and progress indicators
• Permission prompts: Asking you to approve file writes and command executions
• Session management: Maintaining conversation history within a session

The CLI is intentionally minimal. There's no GUI, no web interface, no complex configuration wizard. You type, Claude responds, you approve actions. This simplicity is a feature -- it means Claude Code works everywhere your terminal works: local machines, SSH sessions, CI/CD pipelines, Docker containers.

Component 2: The Tool System

This is the heart of what makes Claude Code agentic rather than just a chatbot. The tool system gives Claude a set of capabilities it can invoke autonomously:

Read Tool

Purpose: Read the contents of any file in the project
Input: File path
Output: File contents
Example: Claude reads src/utils/auth.ts to understand your auth implementation

The Read tool is Claude's eyes. When it needs to understand something about your project, it reads files. A single task might involve reading 10-20 files as Claude traces code paths, reads configurations, and examines test patterns.

Write Tool

Purpose: Create a new file or completely replace file contents
Input: File path + new contents
Output: Confirmation of write
Permission: Always requires your approval

The Write tool creates new files or replaces existing ones. Every write operation shows you the proposed content and waits for your approval before executing.

Edit Tool

Purpose: Make targeted changes to specific parts of a file
Input: File path + edit instructions (search/replace)
Output: The modified file
Permission: Always requires your approval

The Edit tool is for surgical changes -- modifying a function, adding an import, changing a configuration value. Rather than rewriting an entire file, it finds the relevant section and makes the targeted change.

Bash Tool

Purpose: Execute terminal commands
Input: Command string
Output: stdout and stderr
Permission: Requires approval (with some exceptions)

The Bash tool lets Claude run any terminal command: npm test, git status, curl, ls, cat -- anything you could type into your terminal. This is what lets Claude verify its own work by running tests, check the current state of things, and interact with external tools.

Search Tools (Grep/Glob)

Purpose: Find files and search for patterns across the codebase
Input: Search pattern, file pattern
Output: Matching files/lines

These tools let Claude efficiently search your codebase without reading every file. Need to find all files that import a specific module? All places where a deprecated function is called? Search tools make this fast.

Component 3: The Context Manager

Context management is arguably the most important concept to understand as a Claude Code user. It directly determines the quality of outputs you get.

What is context? Context is everything Claude knows when it's generating a response. This includes:

1. Your conversation history -- all prompts and responses in the current session
2. File contents -- every file Claude has read during the session
3. Command outputs -- results from every bash command that was run
4. System prompt -- instructions that tell Claude how to behave
5. CLAUDE.md files -- project-specific instructions (we'll cover this in depth later)

The context window is finite. Claude has a maximum amount of information it can hold "in mind" at once. Think of it like working memory -- there's a limit to how much you can actively think about simultaneously.

This has practical implications:

• Early in a session, Claude has lots of available context space. It can read many files, consider lots of code, and reason about complex relationships.
• Late in a long session, context gets crowded. Claude may not be able to hold all the information from earlier in the conversation plus new information. It might "forget" details from files it read earlier.

Context management strategies:

Good: Start fresh sessions for unrelated tasks
Good: Be specific about file paths so Claude reads only what it needs
Good: Break complex tasks into focused sub-tasks

Bad: One mega-session for everything
Bad: Vague prompts that cause Claude to read many irrelevant files
Bad: Asking Claude to "remember" things from many sessions ago

Component 4: The Permission Model

Claude Code uses a tiered permission system that balances productivity with safety:

Always Allowed (no prompt):

• Reading files in your project
• Searching/grepping the codebase
• Reading environment variables
• Viewing git status and logs

Requires Approval:

• Writing or editing files
• Running bash commands (most of them)
• Making network requests

Can Be Pre-Approved:

• You can configure certain tools or commands to run without asking every time
• Example: npm test can be set to auto-approve since it's read-only

This permission model means Claude Code is safe to use in production codebases. It can't accidentally delete files, run destructive commands, or push to production without your explicit approval.

How a Request Gets Processed

Let's trace a real request through the entire system to see how all components work together.

Your prompt: "Add input validation to the signup form"

Step 1 -- Context Assembly The CLI packages your prompt with the current conversation history, any CLAUDE.md instructions, and sends it to the Claude model via the Anthropic API.

Step 2 -- Planning Claude analyzes the request and decides it needs to:

1. Find the signup form component
2. Understand the current form structure
3. Determine what validation library the project uses (if any)
4. Write the validation logic
5. Test it

Step 3 -- Information Gathering (Agentic Loop)

-> Glob: Find files matching *signup* or *sign-up*
<- Found: src/components/SignupForm.tsx, src/pages/signup.tsx

-> Read: src/components/SignupForm.tsx
<- [file contents returned - 89 lines]

-> Read: package.json (checking for validation libraries)
<- [sees zod in dependencies]

-> Grep: Search for "z.object" or "z.string" (find existing Zod patterns)
<- Found: src/schemas/user.ts uses Zod schemas

-> Read: src/schemas/user.ts
<- [sees existing validation patterns]

Step 4 -- Implementation Based on what it learned, Claude writes validation code that:

• Uses Zod (matching the project's existing pattern)
• Follows the same schema structure as other schemas in the project
• Integrates with the existing form component

Step 5 -- Presentation Claude shows you the proposed changes and explains its reasoning. You review and approve.

Step 6 -- Verification (Optional) If you ask, Claude can run the test suite to verify nothing broke.

This entire sequence -- from your prompt to the finished implementation -- typically takes 30-90 seconds, depending on the complexity.

Apply: Trace the Architecture

Reflect: Thinking Architecturally

What You've Learned

Understanding how Claude Code works under the hood is the single biggest factor in getting great results from it. Let's summarize the key architectural concepts:

Why Architecture Matters for Users

You might wonder why you need to understand the internals. Can't you just use it? You can -- but understanding the architecture lets you:

1. Write better prompts -- When you know Claude needs to find files before it can read them, you'll provide file paths to skip the search step
2. Manage context effectively -- When you know the context window is finite, you'll structure your sessions to avoid information overload
3. Debug poor outputs -- When Claude gives a subpar response, understanding the architecture helps you figure out why and adjust
4. Trust the tool appropriately -- When you know every action requires approval, you can confidently use Claude Code in production codebases

Looking Ahead

In the next lesson, we'll get hands-on: installing Claude Code, running it for the first time, and completing your first real task. Now that you understand the architecture, the installation and first-run experience will make much more sense -- you'll know exactly what's happening behind the terminal when you type that first prompt.