Lesson 1 of 5 in Claude Code Configuration & Workflows

2.1 · Claude Code architecture

Claude Code is a terminal-based agentic coding tool. This lesson covers what it actually is, how it assembles context every turn, where its configuration lives, and when to use plan mode versus direct execution. Understanding the architecture makes the rest of the domain fall into place.

What Claude Code actually is

Claude Code is a terminal-based agentic coding tool. It reads your codebase, edits files, runs commands via a shell tool, and uses tools defined by you, by MCP servers, and by built-ins. Sessions maintain context within a project directory.

How context is assembled

Every turn, Claude Code loads: applicable CLAUDE.md files (user, project, subdirectory), files matched by your recent references, MCP server tool definitions, and the running message history. Files matched by .claudeignore are excluded from all reads.

Configuration lives in the filesystem

The configuration philosophy is 'text files in the repo, checked into git.' Your CLAUDE.md, .claudeignore, custom commands, skills, subagent definitions, and hooks all live as files. This makes team distribution trivial: it's just a git commit.

Plan mode vs act mode

Plan mode lets Claude propose a plan before executing anything destructive. Useful for large changes where you want to inspect the plan before letting it run. Act mode executes as it decides. Plan mode is the safer default for critical repos, multi-file migrations, or architectural decisions. Reach for act mode on clear single-file tasks where the intent is obvious.

Takeaways

  • Terminal-based, codebase-aware, tool-using agent
  • Configuration is filesystem-based and git-friendly
  • Context is assembled every turn from many sources
  • Plan mode gates destructive work

Exam traps

Vague or marketing-style tool descriptions
'A powerful tool for data' tells Claude nothing. Descriptions should say what the tool does, when to use it, when NOT to use it, and what it returns.
Free-form strings where enums would work
Constraining 'status' to a string when it should be enum ['open','closed','pending'] invites drift. Use enums whenever the value set is known.
Building a custom MCP server before checking community servers
Community MCP servers exist for most common integrations. Build custom only when the community options genuinely don't fit the workflow.

Practice scenario

A team ships a tool called 'process_data' with description 'processes data'. Claude calls it for everything from formatting strings to running SQL queries. What is the correct first intervention?

Next →