Claude Code Everything You Need To Know

Claude Code: Everything You Need to Know

A practical guide to Claude Code — from your first prompt to multi-agent automation, hooks, MCP, and team workflows. Built around clear mental models and real examples, not marketing.

npm install -g @anthropic-ai/claude-code

Who this is for: Developers using (or about to use) Claude Code. Beginners get a guided path; power users get depth on Skills, Hooks, MCP, and Agent Teams.

---

🧭 Choose your path

| You are… | Start here | Time | |---|---|---| | 🚀 New to Claude Code | [Setup](#claude-code-setup) → [Prompt Engineering](#prompt-engineering-deep-dive) → [Your First Skill](#claude-skills) | ~15 min | | ⚡ Already using it, want depth | [Skills](#claude-skills) · [Hooks](#hooks) · [MCP](#model-context-protocol-mcp) | ~30 min each | | 🧠 Building teams or automation | [Agent Teams](#agent-teams-experimental---2026) · [Super Claude](#super-claude-framework) · [BMAD](#the-bmad-method--ai-agent-framework) | varies |

---

🧠 When to use what

The four extension points in Claude Code, side by side:

| Tool | Use when… | Skip if… | Lives in | |---|---|---|---| | [Skills](#claude-skills) (slash commands) | You repeat the same prompt or workflow ≥3 times | One-off task | .claude/commands/*.md | | [Hooks](#hooks) | You want code to run automatically on tool use, session start, etc. | You only want manual triggers | .claude/settings.json | | [Subagents](#ai-agents) | A subtask is big enough to need its own isolated context | The task fits in your main session | .claude/agents/*.md | | [MCP servers](#model-context-protocol-mcp) | You need Claude to use external tools (browsers, DBs, APIs) | All your data is in local files | Configured per project |

> 💡 These four compose. Most polished workflows combine 2–3.

---

📚 What's inside

Fundamentals — [What is Claude Code?](#what-is-claude-code) · [Setup](#claude-code-setup) · [Prompt Engineering](#prompt-engineering-deep-dive)

Workflow extensions — [Slash Commands](#claude-commands) · [Skills](#claude-skills) · [Hooks](#hooks)

Multi-agent & integration — [Subagents](#ai-agents) · [Agent Teams](#agent-teams-experimental---2026) · [MCP](#model-context-protocol-mcp)

Productivity & frameworks — [Effort levels](#effort-levels) · [Fast Mode](#fast-mode-) · [Super Claude](#super-claude-framework) · [BMAD Method](#the-bmad-method--ai-agent-framework)

Reference — [Slash Command Cheatsheet](#built-in-slash-commands) · [Effort Levels](docs/reference/effort-levels.md) · [FAQ](#faq) · [Updates & Deprecations](#updates--deprecations) · [Further Reading](#references)

What is Claude Code?

Claude Code is Anthropic's official CLI for working with Claude from your terminal. You point it at a project; it reads the code, plans, edits files, runs commands, and commits — all from the prompt line.

Three things it does that a chat UI can't:

• Reads your actual repo — not pasted snippets. Claude sees your file tree, runs grep, follows imports, and grounds answers in real context.
• Edits in place and runs your tests — diff-aware edits, then pytest/vitest/go test on the spot to verify the change.
• Composes with the rest of your stack — slash commands, hooks, sub-agents, MCP servers, and your normal git/shell workflow.

If you've used Copilot or Cursor, think of Claude Code as their "agent in your terminal" peer — same idea, different surface, no editor lock-in.

claude          # start a session in the current repo
> explain what this codebase does
> fix the failing test in src/api.test.ts
> open a PR with the changes

---

Claude Opus 4.7: The Latest Flagship

Claude Opus 4.7 is the current flagship in the Claude 4 family (May 2026) — sharper adaptive thinking, better long-context grounding, more reliable tool calling than Opus 4.6, at the same price. 200K context (1M beta via API), 128K max output.

Choosing a model — quick guide:

| Model | Reach for it when… | |---|---| | Opus 4.7 | Complex reasoning, large refactors, multi-file analysis, production-critical code | | Sonnet 4.6 | Balanced everyday work — most coding tasks live here | | Haiku 4.5 | Fast, lightweight tasks — quick questions, doc updates | | Opus 4.6 (legacy) | Pin a specific build; also the model behind Fast Mode (/fast) |

> [→ Full specs, capabilities, and pricing in docs/reference/models.md](docs/reference/models.md)

---

Claude Code Setup

> ⏱️ 5-minute setup. Get from zero to your first AI-assisted commit.

1. Install

npm install -g @anthropic-ai/claude-code

> Requires Node.js 18+. For other install methods (Homebrew, curl, native binary), see the official install guide.

2. Authenticate

claude

On first run, Claude Code opens a browser to sign in with your Anthropic account (Pro, Max, or API key all work). After that, you can re-authenticate any time with /auth login from inside Claude.

3. Run your first prompt

From any project directory:

cd ~/your-project
claude

Once Claude Code is running, try one of these:

• explain what this codebase does — Claude reads your repo and summarizes.
• add a README section about installation — generates content based on your project.
• find and fix the failing test in src/api.test.ts — diagnoses and edits in place.

4. (Optional) Generate a CLAUDE.md

/init

Creates a project-level instruction file that Claude reads on every session — your project's "house rules." More on this in [Prompt Engineering Deep Dive](#prompt-engineering-deep-dive).

5. (Bonus) See a real Claude Code project setup

This repo's own [.claude/](.claude/) directory is a working example of a fully-configured Claude Code project. Browse it as a reference for what a polished setup looks like:

| Path | What it does | |---|---| | [.claude/settings.json](.claude/settings.json) | Project-level Claude Code settings — permissions, hooks, MCP integrations | | [.claude/agents/](.claude/agents) | 5 specialized subagents (frontend, tech lead, PM, UX designer, code reviewer) | | [.claude/commands/](.claude/commands) | 8 custom skills — /pr, /review, /tdd, /test, /five, /ux, /todo, /mermaid. See [Skills](#claude-skills) for the full guide. | | [.claude/hooks/](.claude/hooks) | Python hook scripts (pre_tool_use.py, post_tool_use.py, notification.py, stop.py, subagent_stop.py) — see [Hooks](#hooks) |

> 💡 Next: Once you're comfortable with the basics, jump to [Claude Skills](#claude-skills) to build reusable slash commands in 3 minutes.

---

Prompt Engineering Deep Dive

> 📖 Claude Initialization > Run the /init command to automatically generate a CLAUDE.md file. > Your CLAUDE.md files become part of Claude's prompts, so they should be refined like any frequently used prompt. A common mistake is adding extensive content without iterating on its effectiveness. Take time to experiment and determine what produces the best instruction following from the model.

1. Explore → Plan → Code → Commit

> Versatile workflow for complex problems.

• Explore: Read relevant files/images/URLs; use subagents for verification. Do not code yet.
• Plan: Ask Claude to make a plan. Use "think", "think hard", "think harder", or "ultrathink" to nudge depth in the prompt — see [Effort levels](#effort-levels) for the full reasoning dial. Optionally save the plan for future reference.
• Code: Implement the solution; verify reasonableness as you go.
• Commit: Commit results, create pull requests, update READMEs/changelogs.
• Claude has two default modes: Plan Mode and Accept Edits Mode. You can toggle between them using the Shift + Tab keys.

> 💡 Pro Tip: Research & planning first significantly improves performance for complex tasks.

---

2. Test-Driven Workflow (Write Tests → Code → Commit)

> Ideal for changes verifiable with unit/integration tests.

• Write Tests: Create tests based on expected inputs/outputs; mark as TDD.
• Run & Fail Tests: Confirm they fail; no implementation yet.
• Commit Tests: Commit once satisfied.
• Write Code: Implement code to pass tests; iterate with verification via subagents.
• Commit Code: Final commit after all tests pass.

> 🔹 Clear targets (tests, mocks) improve iteration efficiency.

---

3. Visual Iteration (Code → Screenshot → Iterate → Commit)

• Provide screenshots or visual mocks.
• Implement code, take screenshots, iterate until outputs match mock.
• Commit once satisfied.

> 🔹 Iteration significantly improves output quality (2-3 rounds usually enough).

---

4. Effort levels — how hard Claude thinks

[→ Full guide in docs/reference/effort-levels.md](docs/reference/effort-levels.md)

> Mental model: Effort is a behavioural dial, not a token budget — it shifts thinking depth, tool-call appetite, response length, and how persistently Claude pushes through multi-step work. Higher ≠ smarter; context quality often matters more.

5 levels exist (most users assume 4):

| Level | Reach for it when… | |---|---| | low | Fast interactive queries you're steering — file renames, simple greps | | medium | General coding, small refactors, autonomous sessions where the plan is clear | | high | Multi-file refactors, complex debugging — Anthropic's recommended default for Sonnet 4.6 / Opus 4.6 | | xhigh (Opus 4.7 only) | Long autonomous agentic sessions — Anthropic's recommended default for Opus 4.7 | | max | Architecture, subtle bugs, security review — genuinely hard problems only |

Current defaults (May 2026): Opus 4.7 → xhigh; Opus 4.6 + Sonnet 4.6 → high on every plan. (The "Pro/Max users on a nerfed medium default" lore was true ~March → late April 2026 but is fixed in Claude Code v2.1.117. Check yours with /effort.)

Setting it, in order of persistence:

# This turn only — adds an in-context cue (does not change API effort)
> ultrathink — design the migration strategy

# This session — slider with no args, level name with arg
/effort xhigh
/effort auto                    # reset to model default

# All sessions, low/medium/high/xhigh — settings.json
echo '{ "effortLevel": "high" }' > .claude/settings.json

# All sessions, max — only the env var works
export CLAUDE_CODE_EFFORT_LEVEL=max

> ⚠️ Three gotchas worth knowing: > - Anthropic's own guidance for Opus 4.7 max: "shows diminishing returns and is more prone to overthinking" on routine work. Don't default to it. > - "effortLevel": "max" in settings.json silently downgrades — only CLAUDE_CODE_EFFORT_LEVEL=max env var persists max. > - Context quality often beats more effort. If you're reaching for max on a task that shouldn't need it, ~80% of the time the fix is upstream — sharper CLAUDE.md, atomic plan, named files. [Full breakdown →](docs/reference/effort-levels.md#effort--intelligence--the-context-quality-trap)

> 💡 Pattern: plan-with-Opus / execute-with-Sonnet. Plan in Opus xHigh or Max; hand the atomic, zero-ambiguity plan to Sonnet at lower effort to execute. Sonnet follows clear plans without drift, so the cheap execution is reliable when the plan is sharp.

---

Claude Commands

Claude Code ships ~30 built-in slash commands plus the ability to define your own as skills (markdown files in .claude/commands/). The two work together — built-ins for common operations, custom skills for your team's workflows.

Day-1 essentials

| Command | Purpose | |---|---| | /init | Generate a CLAUDE.md for your project — your "house rules" Claude reads every session | | /help | List all available commands | | /clear | Reset conversation history when you want a clean slate | | /cost | Track token usage in this session | | /model | Switch between Opus 4.7, Sonnet 4.6, Haiku 4.5 (4.6/4.5 still available) |

> [→ Full slash-command reference in docs/reference/commands.md](docs/reference/commands.md) (~30 commands including /auth, /fast, /hooks, /mcp, /teleport, …)

Custom slash commands

Define a frequently-used prompt once as a markdown file, invoke it forever with /skill-name:

mkdir -p .claude/commands
echo "Analyze this code for performance issues and suggest optimizations:" \
  > .claude/commands/optimize.md

> 💡 Next level: custom slash commands and Skills are the same thing. Head to [Claude Skills](#claude-skills) for the deep dive — built-in skills, the 7 custom skills in this repo, workflow recipes, and how to write your own.

---

Claude Skills

~3 min read · [Full guide in docs/skills.md →](docs/skills.md)

> Mental model: Skills package a workflow into a markdown file. Two flavors: > - Slash skills — .claude/commands/.md, you invoke them with / > - Agent Skills — .claude/skills//SKILL.md with YAML frontmatter; Claude auto-invokes when the description matches the task

> ⚠️ Security: Skills are executable instructions running with your shell permissions. Read every third-party skill before adding it — exactly like reviewing a shell script before sourcing it.

Your first skill in 3 minutes

mkdir -p .claude/commands

cat > .claude/commands/analyze.md 

---

### Hooks

> **Mental model:** Hooks are programmable checkpoints on Claude Code's lifecycle (before/after a tool call, session start, prompt submit, etc.). Your script inspects the proposed action and returns *allow* / *deny* / *modify*.

**Three cases that win most teams over:**

| Use case | What the hook does |
|---|---|
| Auto-format on save | Runs `prettier` / `ruff` / `gofmt` after every Edit so Claude's output matches your style |
| Block sensitive paths | Refuses changes to `.env`, `secrets/`, `infra/prod/` regardless of what Claude tries |
| Action audit log | Records every tool call to a file — paper trail of what Claude did and when |

If none of those resonate, skip ahead.

#### Setting up hooks

Hooks live in settings files at four scopes (later overrides earlier):

| Scope | Path |
|---|---|
| User-wide | `~/.claude/settings.json` |
| Project (committed) | `.claude/settings.json` |
| Project (local, gitignored) | `.claude/settings.local.json` |
| Enterprise managed policy | platform-specific |

**Quickest setup** — use the interactive menu added in 2026:

```bash
/hooks    # browse, enable, configure hooks without touching JSON

Manual setup — for the hook scripts in this repo:

1. Copy .claude/hooks/ into your project's .claude/ folder.
2. Delete the hook scripts you don't need; keep the rest.
3. Install uv (required to run the Python hook scripts).
4. Copy .claude/settings.json into your project's .claude/ folder.
5. In settings.json, replace any hardcoded uv path with the output of $(which uv).

project-root/
└── .claude/
    ├── hooks/
    │   ├── notification.py
    │   ├── post_tool_use.py
    │   └── ...
    └── settings.json

Hook Events

Hooks run in response to various events within Claude Code's lifecycle: examples

• PreToolUse: Runs after Claude creates tool parameters but before processing the tool call.
• PostToolUse: Runs immediately after a tool completes successfully.
• Notification: Runs when Claude Code sends notifications, such as when permission is needed to use a tool or when prompt input has been idle.
• UserPromptSubmit: Runs when the user submits a prompt, before Claude processes it.
• Stop: Runs when the main Claude Code agent has finished responding (does not run if stopped by user interrupt).
• SubagentStop: Runs when a Claude Code subagent (Task tool call)

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: wesammustafa
• Source: wesammustafa/Claude-Code-Everything-You-Need-to-Know
• License: MIT

Install and usage instructions live in the source repository linked above.