Effective Claude Code Usage

From CLI to Cognitive Partner

Source code on GitHub

The orange Anthropic symbol stands in a terminal workshop with a mounted tool assembling linked software modules. Cyan code panels and green test badges illustrate a coding partner that builds and verifies software.

What you’ll learn

  • Agents vs chatbots — what Claude Code actually is
  • Tools and permissions — capabilities and safety boundaries
  • Skills & slash commands — use them, then write your own
  • Context window — what fills it and how to manage it
  • CLAUDE.md, memory, and hooks — durable context and enforcement
  • Subagents and workflows — parallel and orchestrated work
  • Planning mode — explore before you edit
  • Prompting — intent over instructions
  • Worktrees and claude -p — parallel sessions and automation

Goal · turn Claude Code from a smart autocomplete into a capable cognitive partner for complex engineering tasks.

Prerequisite · Claude Code installed; you can run claude in a terminal.

Checked against v2.1.325 · 15 November 2026. Check claude --version and /help on your install.

Sources: Release notes · Commands

What Is Claude Code?

“It’s not a chatbot in a terminal. It’s an agent that reads, writes, searches, and executes — and loops until the task is done.”

Claude Code is a CLI Agent

CLI-first · runs in your terminal, next to your shell, files, and Git history. Also available as desktop app, IDE extensions (VS Code, JetBrains), and web app.

Agentic · not one-shot Q&A — loops: perceive → plan → act → observe → repeat

Tool-using · reads files, writes code, runs bash, searches the web, spawns subagents, and can run workflows when enabled

Key insight · the model decides which tools to use, in what order, and how many times.

$ claude "add unit tests
  for src/auth.ts"

● Reading src/auth.ts
● Scanning test patterns
● Writing tests/auth.test.ts
● Running: npm test

✓ 12 tests passing

Agents vs. Everything Else

“The difference between a chatbot and an agent is the difference between giving advice and doing the work.”

Intelligence Spectrum

Three columns ordered by increasing autonomy. Tab completion predicts next tokens, sees the open file, and you write the code. A chatbot answers a prompt, sees what you paste, and you run the code. An agent such as Claude Code pursues a goal, reads the whole repository, and runs and checks its own work.

ReAct Agent Loop

ReAct agent loop: a task flows into think, act, and observe steps, then a done check. If not done, it loops back to think; if done, it returns a result.

Why it matters · the loop only ends well if Claude can tell when it is done. Give it a check to run — tests, a build, a screenshot — and it will iterate against that signal instead of stopping at “looks right”.

Tools & Capabilities

“A tool is a function the model can call. The model decides when — and how many times.”

Tool Categories

Category Tools Enables
File I/O Read · Write · Edit Read permitted files; create or surgically modify code
Search Bash (find, grep) Default on macOS/Linux/WSL; Glob/Grep on Windows
Shell Bash Run tests, git, npm, docker — any terminal command
Web WebFetch · WebSearch Fetch docs, read changelogs, search answers
Agents Agent · Workflow Spawn subagents, isolate context, orchestrate workflows
MCP Server-defined GitHub PRs, Jira tickets, Postgres, and more

Permissions + sandboxing · prompts depend on the active permission mode and rules. Sandboxed Bash runs inside OS-enforced boundaries but still prompts by default; turn on auto-allow to run it without asking. Explicit deny rules still apply. Configure both with /permissions and /sandbox.

Source: Tools reference and platform defaults

Choose a Permission Mode

Mode Runs without asking Best fit
Manual Reads only Getting started; sensitive work
Accept edits Reads, file edits, common filesystem commands Iterating on code you will review
Plan Reads and, when enabled, classifier-approved commands Explore before implementation
Auto Actions with background safety checks Default for terminal and VS Code since v2.1.283
Don’t ask Reads in working directories and pre-approved tools Locked-down CI and scripts
Bypass Everything Isolated containers or VMs only

Switch with Shift+Tab · it cycles manual → accept edits → plan, then enabled optional modes. Watch the status bar. Permission rules decide what Claude may attempt; the sandbox enforces filesystem and network boundaries for Bash. In auto mode a classifier reviews actions in your place — it cuts prompts but does not replace your review of sensitive work.

Sources: Permission modes · Sandboxing

Skills & Slash Commands

“The / menu is a launcher. The action type tells you how Claude will execute it.”

/ Actions — Know What You Are Running

The / menu combines built-in commands, bundled skills, workflows, plugin actions, and MCP prompts. Skills are reusable instructions that load on demand; many can activate from their description, but /verify runs only when you invoke it.

Action Kind · purpose
/code-review Skill · correctness review
/simplify Skill · apply cleanup fixes
/verify Skill · run and observe the change
/run Skill · launch and drive the app
Action Kind · purpose
/deep-research Workflow · cited research
/security-review Built-in · audit branch diff
/init Built-in · generate CLAUDE.md
/review Alias · /code-review; --fix applies findings

Install-dependent · availability varies by version, plan, platform, plugins, and MCP servers. Use /help for commands and /skills for loaded skills.

Source: Commands and action types

Write Your Own Skill

# .claude/skills/release-notes/SKILL.md
---
description: Draft release notes from merged
  PRs. Use when preparing a release.
disable-model-invocation: true
allowed-tools: Bash(gh pr list *) Read
---

1. List PRs merged since the last tag.
2. Group them: features, fixes, chores.
3. Write CHANGELOG.md in house style.

When to write one · you have pasted the same multi-step instructions into a prompt more than twice.

Where · .claude/skills/<name>/ for the team (commit it), ~/.claude/skills/<name>/ for you. The folder name becomes /name.

Who invokes it · Claude loads a skill when its description matches the task. Set disable-model-invocation: true for actions with side effects, so they run when explicitly invoked or permitted in your message.

Cheap until used · regular skills load descriptions first, then their body on invocation. User-only skill descriptions stay out of context. Existing .claude/commands/*.md files still work.

Source: Extend Claude with skills

Slash Commands — Session Control

Session & Context

Command Purpose
/clear Reset conversation history
/compact Compress history, keep summary
/context Inspect context usage and heavy inputs
/rewind Restore or summarise from a checkpoint
/goal Keep working until a condition holds
/usage Show usage and limit breakdown

Modes & Control

Command Purpose
/plan Enter planning mode
/permissions Manage allow, ask, and deny rules
/sandbox Configure OS-enforced Bash isolation
/model Switch Claude model
/help List all commands
/workflows Watch live workflow progress

Commands move fast · use /help as the source of truth for your install. /cost and /stats are current aliases for /usage.

Source: Commands

Context Window

“The context window is finite. What’s in it decides what Claude can reason about.”

What Fills the Context?

Two context-window bars. Mid-session: system prompt, CLAUDE.md plus memory, and the skill and MCP index are loaded at startup; prompts and replies, file reads, and tool output grow every turn, leaving little free space. After /compact: the startup items remain, history is replaced by a short summary, and most of the window is free.

Fills fast · full-file reads and verbose logs dominate. As the window fills, earlier instructions get less attention.

Fix · /clear between unrelated tasks; /compact focus on X to steer the summary; send broad searches to a subagent so only its findings come back.

Sources: Explore the context window · How Claude Code works

CLAUDE.md, Memory & Hooks

“CLAUDE.md is durable instruction context; auto memory is Claude’s local notebook; hooks run checks at configured lifecycle events.”

How CLAUDE.md Is Loaded

At launch, Claude Code concatenates instruction files from broadest to most specific: managed policy, ~/.claude/CLAUDE.md, ./CLAUDE.md with parent directories, then CLAUDE.local.md; @path imports expand inline up to four hops. On demand, subdirectory CLAUDE.md files load when Claude reads or edits files in that folder, and .claude/rules files with paths globs load when Claude touches matching files.

Scale without bloat · imports organise a long file but still load at launch. Move guidance that only matters for part of the repo into subdirectory files or path-scoped rules.

Source: How Claude remembers your project

Already Use AGENTS.md?

Project setup Default behaviour in v2.1.277+
AGENTS.md; no project or ancestor CLAUDE.md files Loads AGENTS.md directly
Also has CLAUDE.md, .claude/CLAUDE.md, or CLAUDE.local.md in that hierarchy Loads CLAUDE.md files instead
CLAUDE.md imports @AGENTS.md Loads the imported instructions

Choose deliberately · /config → Project instructions can load both formats. User-level and managed CLAUDE.md files do not suppress the default AGENTS.md fallback.

Compatibility · if native support is unavailable or disabled, keep the CLAUDE.md import. Native AGENTS.md support does not load skills from .agents/.

Source: AGENTS.md support and exceptions

CLAUDE.md Anatomy

# My Project CLAUDE.md

## Stack
TypeScript monorepo, Node 22, pnpm

## Conventions
- ESM only (no require())
- Tests: Vitest + @testing-library
- Branch: feat/<ticket>-description

## Commands
- Test:  pnpm test
- Build: pnpm build

## Never
- Push directly to main
- Commit .env files

Auto-generate

Run /init in any repo — Claude inspects the codebase and writes a CLAUDE.md for you. Edit it to add conventions and “never do” rules.

Keep it lean · aim for under 200 lines. Include only commands, conventions, decisions, and gotchas Claude cannot infer from the repo.

Test each line · would removing it cause a mistake? If not, cut it. When two rules contradict, Claude may follow either.

Memory Is Context, Not Enforcement

Dotted arrows from project instructions and remembered notes guide the orange Anthropic symbol towards a solid enforcement checkpoint. Guidance informs a decision, while a gate can require a check or block an action.

Keep context lean · put non-obvious commands, conventions, decisions, and gotchas in CLAUDE.md. Claude’s auto memory is local and per-repository; its index loads only the first 200 lines or 25 KB, with topic files loaded on demand.

Review and enforce · use /context to inspect loaded files and /memory to review notes; prune stale or conflicting facts. Use permission deny rules or hooks when an action must be blocked or a check must always run.

Source: Claude Code memory documentation

Hooks — Automated Validation

# .claude/settings.json
{
  "hooks": {
    "PostToolUse": [{
      "matcher": "Edit|Write",
      "hooks": [{
        "type": "command",
        "command": "pnpm lint"
      }]
    }]
  }
}

What hooks do · run shell commands automatically at lifecycle events — no per-prompt reminder needed.

Key events · PreToolUse · PostToolUse · Stop · UserPromptSubmit — and more

Use cases · lint after edits · run typecheck before stopping · block risky bash commands · log file writes

Enforcement needs configuration · this post-edit hook cannot undo a write. Policy hooks should deny explicitly or exit 2; use onFailure: "block" (v2.1.295+) to block on hook errors or timeouts.

Sources: Hooks reference · Hook coverage

Subagents & Workflows

“Subagents handle parallel work. Workflows are for the cases where simple fan-out is not enough.”

Subagent Orchestration

The main session, which holds the goal, delegates to three subagents that each get their own context window: Explore finds every auth call site and is read-only; general-purpose updates the API docs and can edit files; a custom code-reviewer reviews the diff with your chosen tools and model. Only their summaries return to the main context.

Custom subagents · a Markdown file in .claude/agents/ with name, description, and optional tools and model. Ask Claude to create or edit one; /agents now prints guidance, rather than opening a manager.

Sources: Subagents · Commands

Choose the Right Parallel Primitive

Four coordination patterns: subagents report back to one main session; background agents run as independent sessions; agent teams connect peers around a shared task board; workflows follow a scripted branching and joining path.

Keep context focused · use subagents when exploration or logs would clutter the main session; bring back a summary.

Hand off and revisit · dispatch and monitor background sessions with claude agents. Research preview.

Coordinate directly · use teams only when workers must communicate. Experimental and disabled by default.

Repeat control flow · use workflows for many agents, cross-checks, or resumability, once a few subagents are insufficient.

Default · start with one agent; request extra coordination only when it materially helps.

Source: Run agents in parallel

Workflows — Advanced Orchestration

Example workflow: a script runs phase 1, where bugs, security, and performance reviewers work in parallel, then phase 2, where each reviewer's findings are independently challenged, and only confirmed findings come out.

Orchestration as code · the control flow above lives in a readable JavaScript script that runs in the background. /workflows shows live progress; save a run that worked so the team can reuse it.

Source: Dynamic workflows

Workflow Patterns — Use Sparingly

Pattern Use when Simpler alternative
Adversarial verify A high-risk review needs independent challenge One subagent + manual review
Judge panel Several viable designs need comparison Ask for tradeoffs first
Loop-until-dry You need repeated search until no new findings One targeted verification pass
Pipeline Many items need the same multi-stage treatment Script + one Claude pass

Rule of thumb · use a few subagents for turn-by-turn delegation; use a workflow when the plan itself needs repeatable loops, branching, cross-checking, or dozens of workers.

Source: Dynamic workflows

Planning Mode

“Explore first. Edit second.”

Planning Mode Workflow

Planning workflow: request, explore the code, draft a plan covering files, steps, and risks, then an approval decision. Explore and draft happen in plan mode where Claude researches and writes a plan before changing source files. If revised, the loop returns to the draft; if approved, Claude executes and then verifies.

Enter plan mode · /plan, Shift+Tab, or claude --permission-mode plan. Review before approving. Planning can run shell commands; it is not an OS sandbox. Avoid enabling bypass permissions when you need edit restrictions.

Source: Plan mode and its limits

When Planning Mode Pays Off

Situation Without Planning With Planning
Refactor across 20 files Broken imports, partial changes Coherent strategy, clean execution
Add auth to existing app Picks wrong pattern for codebase Existing patterns understood first
Multi-service change Inconsistent API contracts All surfaces identified upfront
Mysterious bug Treats symptoms, not cause Root-cause analysis before editing

Rule of thumb · plan when the approach is uncertain, the change spans multiple files, or the code is unfamiliar. If you can describe the diff in one sentence, direct execution is usually enough.

Pro tip · front-load clarity: state intent, constraints, and acceptance criteria upfront. Let Claude draft the plan. Approve it or give one round of feedback — then execute.

Keep the Blast Radius Small

Before broad edits

  • Use /plan for cross-file changes
  • Start a worktree for parallel sessions
  • State files, commands, and acceptance criteria
  • Ask for a diff summary before commit

Before accepting work

  • Inspect git diff
  • Run tests and lint
  • Check generated artefacts
  • Review the PR like any teammate’s work

Principle · let Claude move quickly inside boundaries you can verify.

Delegate Intent, Verify Work

“Claude Code is an execution engine. Give it intent, constraints, and a finish line; then verify what changed.”

Define the What, Not the How

Two route maps contrast a route constrained by prescribed waypoints with several possible routes to a clear destination. The destination has a checklist, showing that the agent can choose its approach while success remains verifiable.

A concrete prompt · “Add unit tests for the auth module. Done when: all public functions covered, edge cases tested, conventions followed, pnpm test passes.”

Before accepting · run the named checks and inspect the tests. Passing a command alone does not prove the requested coverage or edge cases are present.

Source: Claude Code best practices

Git Worktrees

“When two Claude sessions edit the same files, you don’t get double the speed — you get merge conflicts. Worktrees give each session its own universe.”

Why Parallel Sessions Need Isolation

Two sessions collide while editing one shared folder. In separate worktrees, each session edits its own folder, while both remain connected to shared repository history.

The failure mode · one session’s half-finished edits can break another’s tests. Switching tasks may require stash/pop gymnastics.

The hand-off · give each session its own branch; build and test in that checkout. Review and merge completed work on your schedule.

Source: Parallel sessions with worktrees

Worktrees — How They Work

One shared .git directory with history, refs, and remotes feeds three worktree directories under .claude/worktrees (ui, auth, and bugfix), each on its own worktree branch and each driven by its own claude --worktree session.

Usage · claude --worktree feature-auth creates an isolated worktree and starts Claude in it. -w is the short alias.

Pro tip · add .claude/worktrees/ to .gitignore. Use .worktreeinclude to copy selected gitignored setup files such as .env into new worktrees.

Automation

“The same agent loop runs without a terminal session: in scripts, pipelines, and CI.”

Run Claude Non-Interactively

# Pipe input in, get an answer out
$ cat build.log | claude -p \
    "explain the root cause"

# Pre-approve the project test command
$ claude -p "fix the failing tests" \
    --allowedTools "Read,Edit,Bash(pnpm test *)"

# Structured output for scripts
$ claude -p "summarise this PR" \
    --output-format json | jq -r .result

-p / --print · runs one task and exits; a non-zero exit code means the run failed, so scripts can branch on it.

Bare CI runs · --bare skips discovered customisations and project instructions. It also skips subscription login: set ANTHROPIC_API_KEY or provider credentials. Hooks stay off, even via --settings.

Tool scope · --allowedTools pre-approves calls; --tools restricts built-in availability. With --permission-mode dontAsk, calls that would prompt are denied. Keep bypass mode for disposable containers.

In GitHub · Claude Code GitHub Actions responds to @claude mentions in issues and PRs.

Source: Run Claude Code programmatically

Summary

“Claude Code is most powerful when you treat it as a partner, not a search engine.”

Effective Usage: Mental Model

Four-step mental model. 1, set context: CLAUDE.md and skills, intent and done criteria. 2, choose depth: direct prompt, /plan or subagents, a worktree per task. 3, manage context: /context to inspect, /clear between tasks, /compact when long. 4, verify result: git diff, tests and lint, review the PR.

Delegate the work, keep ownership of the result.

Resources

Thank You


Other slide decks on software engineering practices

       


$ claude --help
Claude Code — AI pair programmer
Use it well. Ship great software.