How it works and the extension map
Claude Code's agentic loop, models, tools, context loading, execution environments, extensions, and five-minute/one-hour caching.
This guide combines the official Overview, How Claude Code works and Extend Claude Code guides into a practical map. Understand the client before choosing CLAUDE.md, a skill, subagent, MCP, hook or plugin.
Claude Code is an agent harness around the Claude model. It loads project context, exposes tools, executes commands, manages permissions, saves sessions and feeds results back to the model for the next decision.
#Agentic loop
Three stages repeat and overlap throughout a real task:
| Stage | What Claude does | Your contribution |
|---|---|---|
| Gather context | Reads files, searches symbols, checks Git, loads CLAUDE.md, rules, skills and MCP information | Supply the goal, paths, logs, screenshots and boundaries |
| Take action | Edits files, runs commands, calls MCP, dispatches subagents, writes plans or generates artifacts | Set permissions and interrupt an incorrect direction |
| Verify results | Runs tests, lint and builds, checks diffs, verifies in a browser or GUI | Provide acceptance commands and failure evidence |
This is not a fixed script. The model chooses the next step from previous tool results: inspect code, edit, test, then revisit a failed implementation.
#Models, tools and the harness
| Part | Role | Typical configuration |
|---|---|---|
| Model | Understands code, breaks down work, chooses actions and explains results | /model, --model, /effort, fast mode, fallback model |
| Tools | Read files, edit code, run commands, access pages and external systems | Permissions, MCP, hooks, tool search, sandbox |
| Harness | Sessions, context, permissions, calls, checkpoints, transcripts, status line and UI | Settings, CLAUDE_CONFIG_DIR, ~/.claude/projects |
Model and effort settings participate in cache matching. Repeated /model or /effort changes prevent reuse across those configurations, regardless of five-minute or one-hour TTL.
#Built-in capability map
| Category | Capabilities | Local guide |
|---|---|---|
| Files | Read, Edit, Write, MultiEdit, diff inspection | Tool reference |
| Search | Glob, Grep, code exploration and history search | Large repositories |
| Execution | Bash, tests, builds, Git, background Bash, Monitor | Interactive terminal |
| Web/browser | WebFetch, WebSearch, Chrome, Computer Use | Chrome and Computer Use |
| External systems | MCP, Channels, GitHub, Slack, databases, tickets | MCP |
| Automation | Headless, routines, /loop, CI, code review | Headless automation |
#Execution surfaces
| Surface | Execution location | Provider/cache boundary |
|---|---|---|
| Terminal CLI | Local working directory | Straightforward Passion8 setup with controlled local configuration |
| VS Code / JetBrains | IDE-managed Claude Code process | Check inherited Base URL, token, proxy and certificates |
| Desktop | Desktop-managed local or organization environment | Depends on login and organization policy |
| Web / Slack / cloud review | Anthropic cloud | Usually does not inherit local Passion8 variables or caches |
| Agent SDK | Your service starts a claude subprocess | Plan state, isolation and caching for each worker/session |
Moving from the local CLI to web/cloud review does not imply shared caches. These are usually different sessions, providers and execution environments.
#Context loading
Earlier, stable context is more likely to become a reusable cache prefix.
| Source | When loaded | Cache effect |
|---|---|---|
| System prompt and tool definitions | Session start and capability changes | Critical cache prefix |
CLAUDE.md | Current/parent directories at startup; child directories on demand | Changes usually require a new session and change the prefix |
.claude/rules/ | Session start or matching files | Path-specific rules reduce unrelated context |
| Skill descriptions | At startup so the model can choose skills | More descriptions increase fixed input |
| Skill body | Invocation or a matching need | Appended as a message, usually preserving earlier prefixes |
| MCP names and schemas | Server startup or deferred tool search | Upfront schemas are more likely to cause misses |
| Hook output | When the hook returns context | Longer output increases subsequent input |
| Subagent findings | When the subagent reports | Intermediate work does not occupy main-session context |
Keep CLAUDE.md short, stable and relevant to every session. Put occasional references in skills, connect external systems through MCP, and enforce mandatory rules through hooks or permissions.
#Choose an extension
| Problem | Use | Reason |
|---|---|---|
| Claude forgets build commands or path conventions | CLAUDE.md | Needed in every session |
| A workflow repeats but is not always needed | Skill | Load on demand; invoke with /skill-name |
| A rule applies to certain paths or file types | .claude/rules/ | Reduces root-file noise |
| Access Jira, Slack, databases, browsers or internal APIs | MCP | Server manages connection and authentication |
| Automatic formatting, command blocking or notifications | Hook | Deterministic lifecycle behavior |
| Broad investigation whose intermediate work is unnecessary in the main session | Subagent | Isolates context and returns findings |
| Several Claude sessions must cooperate | Agent Teams | Session communication and shared tasks |
| Share skills/hooks/MCP across projects | Plugin | Versioning and distribution |
#Common distinctions
| Comparison | Guidance |
|---|---|
CLAUDE.md vs skill | Always-on vs on-demand; split a root file over about 200 lines into skills/rules |
| Skill vs subagent | Knowledge/workflow vs independent worker; skills add main context while subagents isolate it |
| MCP vs skill | Tool/data connections vs instructions on using them; commonly combined |
| Hook vs skill | Event-triggered enforcement vs reasoning-based workflow |
| Subagent vs Agent Team | Reports to a parent vs multiple complete sessions cooperating |
#Cache and cost perspective
| Action | Five-minute/one-hour effect |
|---|---|
| Continue the same conversation | Cache hits refresh TTL; five minutes suits frequent work |
| Return after 10–45 minutes | Five-minute entries are often cold; one-hour entries may remain |
Edit CLAUDE.md and restart | New prefix requires a cache write |
| Add/remove MCP servers | Tool definitions change; tool search can help |
| Invoke a skill | Appends its body while usually preserving earlier prefixes |
| Large hook output | May preserve the prefix but increases future input |
| Broad subagent exploration | Subagent incurs tokens; main session receives a compact report |
| Plugin containing MCP | May change descriptions and tool definitions; inspect cache creation after reload |
See command cache effects and prompt caching for TTL and usage fields.
#Recommended extension order
- Run
/initand record core project conventions inCLAUDE.md. - Add sensitive paths to permission deny rules rather than relying only on prose.
- Turn repeated prompts into skills or custom commands.
- Add hooks for required formatting, auditing and notifications.
- Connect external systems with MCP when needed and check tool search.
- Introduce subagents, worktrees, Agent Teams or the SDK for larger tasks.
- Package reusable cross-project configuration as a plugin or internal marketplace.
#Official references
Support
Need help?
For setup, billing, or model issues, email us. Check the status page for uptime.
WeChat / QQ support is available at the bottom right.
