How Claude Code Works

Claude Code is not a simple chat wrapper with shell access. It is an autonomous agent harness engineered around a closed-loop observation engine, sandboxed execution primitives, precision file rewrites, and instant rollback checkpoints.

1. The 3-Stage Agentic Loop

Every prompt submitted to Claude Code triggers a disciplined feedback cycle that mirrors an elite software engineer's workflow:

1. Gather Context: Before modifying a single character, Claude inspects the environment. It parses your CLAUDE.md project manual, runs ripgrep to find symbol definitions, queries language servers (LSP), and reads the specific lines of relevant files. It avoids context bloat by loading only bounded segments into context.
2. Take Action: Claude selects an appropriate tool. When editing code, it performs contiguous string replacements using exact text matching. When executing terminal commands, it uses the Bash tool within your permission boundary. If a subtask requires broad codebase exploration, it spawns an isolated subagent so raw search output does not contaminate your main session.
3. Verify Results: Claude does not guess if its change worked. It executes your test suite, compiler checks, or linter. If the exit code is non-zero, it reads the compiler error output, adjusts its plan, and applies a fix before concluding the turn.

2. The 5 Tool Categories

Claude Code exposes a tightly audited suite of native tools to the model:

3. Rollback Checkpoints & Rewinds

One of Claude Code's most powerful safety mechanisms is automatic turn-based checkpointing. Before modifying any file on disk, Claude Code records an internal snapshot of the modified paths.

If Claude makes a change you do not like, or if you want to explore a different implementation approach:

• Press Esc twice on an empty prompt to open the checkpoint menu.
• Type /rewind to select an exact earlier turn to restore.
• Both file changes on disk and the conversation context roll back seamlessly.

4. Permission Modes: From Strict to Autonomous

Claude Code balances developer safety with autonomous velocity across 5 distinct permission levels:

5. The .claude Directory Structure

Claude Code separates project-level configurations (committed to source control) from local user preferences and global machine settings:

my-project/ ├── .claude/ │   ├── settings.json       # Project-wide settings, hooks, and deny rules (committed) │   ├── settings.local.json # Developer-specific overrides (gitignored) │   ├── rules/              # Scoped instructions with path-matching frontmatter │   │   ├── api.md          # Applied only when editing src/api/**/*.ts │   │   └── frontend.md     # Applied only when editing src/components/**/*.tsx │   ├── skills/             # On-demand procedures (SKILL.md) │   │   └── release/ │   │       └── SKILL.md    # Triggered via /release │   └── agents/             # Custom subagent definitions │       └── reviewer.md     # Subagent with restricted tools (Read, Grep, Glob) └── CLAUDE.md               # Project-level single source of truth guidelines (<200 lines)

6. Extensibility: Choosing the Right Abstraction

Claude Code provides six distinct mechanisms for customization. Choosing the correct layer prevents context bloat:

• CLAUDE.md: For persistent repo-wide facts Claude cannot discover from code (test commands, architecture gotchas). Always loaded.
• Path-Scoped Rules (.claude/rules/): For rules that only apply to specific subdirectories (e.g. database schema migrations).
• Skills (SKILL.md): For multi-step procedures (e.g. cutting a release, running a migration) that should only load when called.
• Subagents (.claude/agents/): For parallel tasks or independent code reviews where you want a fresh context and restricted tools.
• Lifecycle Hooks: For deterministic enforcement (e.g. blocking .env reads, auto-running Prettier, verifying tests before turn completion).
• Model Context Protocol (MCP): For connecting external services (Notion, GitHub, BigQuery, Postgres) to Claude.