12 Claude Code tips that change the quality of the work

1. Make CLAUDE.md an executable briefing, not a wiki

What it is

CLAUDE.md is project memory loaded into every session. Its job is to tell a competent engineer what this repository does differently: the commands that are not obvious, conventions that contradict ecosystem defaults, protected areas, and the verification expected before handoff. It is not architecture documentation and it is not a place to teach the language.

Why it matters

The first expensive phase of an agent task is orientation. Without a briefing, every session spends turns finding the package manager, guessing how to run one test, and discovering the same trap by failing. A good file removes those turns. A bad one creates a standing context tax: it is sent at launch, buries the important rules, and reduces adherence. Anthropic recommends keeping each file under 200 lines for that reason.

Exactly how to do it

# Project

TypeScript API. pnpm workspace. Postgres through Drizzle.

# Commands

- `pnpm test src/auth/session.test.ts` runs one test file.
- `pnpm test` runs the full suite and takes about four minutes.
- `pnpm lint --fix` must pass before handoff.
- `docker compose up -d db` starts the integration-test database.

# Conventions

- Named exports only.
- Money crosses boundaries as integer minor units.
- Errors use `AppError` from `src/errors.ts`.

# Boundaries

- Never edit `src/generated/`.
- Ask before changing a migration already on main.
- Do not commit or push unless the task explicitly requests it.

Run /init once if you want a draft, then cut anything Claude can derive from the tree. Run /memory to confirm the file loaded. Move path-specific rules into .claude/rules/ with a paths: glob, and move any multi-step procedure into a skill. Imports organise text but do not save context because imported files also load.

2. Use plan mode when direction is the expensive part

What it is

Plan mode lets Claude read files, search the repository, and run read-only commands while blocking source edits. It separates deciding what should change from producing a diff. You can enter it for one task with /plan, cycle to it with Shift+Tab, launch in it, or make it the project default.

Why it matters

A wrong implementation is cheap when the intended diff is one line. It is expensive when the change crosses storage, API, and UI layers, because you pay for the run, the review, and the undo before correcting the design. Plan mode moves that decision to the point where changing it costs a paragraph rather than a branch. It also produces a reviewable scope: named files, migration implications, failure modes, and verification steps.

Exactly how to do it

claude --permission-mode plan

# or from an ordinary session
/plan add organisation-scoped API keys with rotation and audit logging

{
  "permissions": {
    "defaultMode": "plan"
  }
}

Ask the plan to name the files it will touch, the existing pattern it will follow, data migrations, compatibility concerns, tests, and an explicit out-of-scope list. When the proposal appears, press Ctrl+G to edit it in your normal editor. Approve into Manual, Accept Edits, or Auto only after those decisions are right. If planning has accumulated a large exploration transcript, use the approval option that clears planning context before implementation.

3. Turn verification into a hook, not a closing sentence

What it is

A hook is code Claude Code runs at a defined lifecycle event. A PostToolUse hook can format a file after every edit; a PreToolUse hook can block a forbidden action; a Stop hook can inspect the final state before a turn ends. Unlike a line in CLAUDE.md, a command hook does not depend on the model remembering to comply.

Why it matters

The agent needs a machine-readable definition of done. Without one, it stops when the code looks plausible and leaves failures for the human review loop. A deterministic gate turns the desired workflow into the environment: formatting happens after edits, generated files stay protected, and a handoff cannot claim success without the project check. This is the biggest step from assisted typing to an agent that can finish a bounded task unattended.

Exactly how to do it

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r .tool_input.file_path | xargs npx prettier --write"
          }
        ]
      }
    ],
    "Stop": [
      {
        "hooks": [
          {
            "type": "command",
            "command": "./scripts/verify-agent-change.sh"
          }
        ]
      }
    ]
  }
}

Make the verification script fast enough to run repeatedly and precise enough to return a non-zero exit only for a fixable failure. A common ladder is: targeted tests, type check, lint, then the broader suite only when affected. Inspect active hooks with /hooks. Use PreToolUse for hard policy, such as rejecting edits under a generated directory, instead of hoping a prose instruction wins every time.

4. Send noisy work to a fresh-context subagent

What it is

A subagent is a delegated worker with its own context window, system prompt, tool set, model, and optional worktree. It receives a task summary rather than the parent conversation, does the bounded work, and returns a result. The main session keeps the decision-making context while the subagent absorbs file reads, search results, and command output.

Why it matters

Long investigations damage the session that must later implement the answer. Hundreds of search matches and test logs crowd out the original requirements, then compaction summarises away details you still need. Delegating repository reconnaissance, documentation research, log analysis, or independent review keeps that material in another window. A custom subagent also makes the same review standard reusable instead of re-prompted.

Exactly how to do it

---
name: reviewer
description: Review a proposed change for reproducible correctness and security bugs.
tools: Read, Grep, Glob, Bash
model: sonnet
permissionMode: dontAsk
---

Read the diff against the merge base. Run only read-only git and targeted test commands. Report findings only when you can cite a file and line, explain the concrete failure, and describe a minimal reproduction. Do not report style preferences.

Open /agents to create or inspect definitions, or ask Claude explicitly: Use the reviewer subagent on the current diff and return only P0/P1 findings. Use /subtask when a side task should inherit the current conversation and return its result in the background. Choose a narrow tool list and a cheaper model for mechanical search. Subagents cannot spawn other subagents, so keep orchestration in the parent.

5. Give every parallel editor its own worktree

What it is

A git worktree is another checkout of the same repository on a separate branch. Claude Code creates one under .claude/worktrees/ with --worktree or -w, can enter one during a session, and can isolate a subagent by setting isolation: worktree. History and remotes are shared; working files and the index are not.

Why it matters

Parallel agents in one checkout race on the same files, staging area, dependency tree, and branch. Even when they touch different modules, one formatter or generated file can overwrite the other session. A worktree makes file collisions structurally impossible and turns cleanup into deleting one checkout and branch. It also creates a review unit: one task, one diff, one place to run verification.

Exactly how to do it

claude -w auth-refresh
claude -w billing-timeout

# inspect all checkouts and branches
git worktree list

# non-interactive worktrees do not show an exit cleanup prompt
git worktree remove .claude/worktrees/auth-refresh
git worktree prune

.env.example
.env.test
config/local-fixtures.json

The include file uses gitignore syntax and copies only files that are already gitignored, never tracked source. Use it for the minimum local setup a fresh checkout needs. Install dependencies inside each worktree unless the package manager safely shares a global cache. For custom subagents, add isolation: worktree to the frontmatter when they may edit.

6. Choose a permission mode instead of accumulating prompts

What it is

A permission mode supplies the default answer when no rule matches. Manual asks, Accept Edits lets local file work proceed, Plan stays read-only, Auto uses a background safety classifier, dontAsk denies anything not pre-approved, and bypassPermissions skips the permission layer. Allow, ask, and deny rules then carve out specific operations.

Why it matters

Repeated prompts are both slow and weak security. After approving the same test command forty times, the human stops reading. The fix is not approving everything; it is making the policy explicit. Routine verification should run without interruption, irreversible but legitimate operations should always ask, and credentials or destructive commands should be denied before the agent considers them.

Exactly how to do it

{
  "permissions": {
    "defaultMode": "acceptEdits",
    "allow": [
      "Bash(pnpm test *)",
      "Bash(pnpm lint *)",
      "Bash(git status)",
      "Bash(git diff *)",
      "Read(src/**)",
      "Edit(src/**)"
    ],
    "ask": [
      "Bash(git push *)",
      "Bash(npm publish *)"
    ],
    "deny": [
      "Read(.env)",
      "Read(.env.*)",
      "Read(~/.ssh/**)",
      "Bash(rm -rf *)",
      "Bash(git reset --hard *)"
    ]
  }
}

Rules are evaluated deny, then ask, then allow. Specificity does not override that order, so narrow a deny instead of trying to add an exception below it. Use /permissions to see every rule and source file. For CI, start with --permission-mode dontAsk: a missing allow rule becomes a clean failure rather than an invisible approval.

7. Add MCP servers by capability, not by novelty

What it is

Model Context Protocol servers add external tools and data to Claude Code: an issue tracker, browser, documentation index, database, deployment system, or an internal service. Remote HTTP is the preferred transport, stdio runs a local process, and WebSocket is available for servers that push events. Project-scoped definitions live in .mcp.json; private local and user scopes live in ~/.claude.json.

Why it matters

The useful payoff is removing lossy copy and paste. Claude can read the actual ticket, inspect a failing trace, or query a schema while keeping citations and identifiers intact. The cost is context and authority. Tool names enter context even when definitions are deferred, a large catalog makes selection worse, and the server acts with its own credential. Installing ten overlapping servers can make the agent slower and less predictable than installing none.

Exactly how to do it

claude mcp add --transport http --scope project docs https://mcp.example.com/mcp

claude mcp add --env INTERNAL_TOKEN="$INTERNAL_TOKEN" --transport stdio local-db -- npx -y @company/db-mcp

claude mcp list
claude mcp get docs

Commit the generated .mcp.json only after reviewing its command, URL, and environment placeholders. Run Claude interactively once to approve a project server, then use /mcp for OAuth and health. Prefer a read-only or repository-scoped token. If a CI job needs a fixed set, launch with --strict-mcp-config --mcp-config ./ci-mcp.json so user and project servers cannot enter the run unexpectedly.

8. Name, resume, and branch sessions like workstreams

What it is

Claude Code saves interactive conversations locally and associates them with project directories. A session name gives the transcript a stable handle; resume continues the same history; branch or --fork-session creates a new transcript from that history while preserving the original. These are conversation operations, separate from git branches and filesystem checkpoints.

Why it matters

Re-explaining a task is expensive and inaccurate. The resumed session already contains the files read, decisions made, rejected approaches, and pending work. Naming also prevents the common failure where -c opens whichever unrelated task happened to run last. Branching is the right move when you want to test a second design without contaminating the first conversation with competing reasoning.

Exactly how to do it

claude -n auth-token-rotation

# inside the session, rename at any point
/rename auth-token-rotation

# return tomorrow
claude --resume auth-token-rotation

# try a second design without changing the original transcript
claude --resume auth-token-rotation --fork-session

# or branch while already inside
/branch auth-token-rotation-alt

Use claude --resume for the picker and claude -c only when one workstream clearly owns the directory. Use /clear old-name to start clean while labelling the session you are leaving. Do not open the same un-forked session in two terminals: their messages interleave into one transcript. Print-mode sessions do not appear in the picker but remain resumable by explicit session ID unless persistence is disabled.

9. Treat context and usage as budgets you can inspect

What it is

/context shows what occupies the context window: system instructions, memory, tools, messages, and tool results. /usage shows session tokens or estimated API cost, subscription windows, activity, and breakdowns that can include skills, subagents, plugins, and MCP servers. One is the model's working attention; the other is the capacity or money consumed to produce it.

Why it matters

Agent quality usually degrades before the window is visibly full. Claude rereads files, forgets an early constraint, or returns to a rejected approach. Meanwhile, parallel sessions and high-effort models can consume a subscription window faster than intuition suggests. Inspecting both budgets turns an apparently mysterious quality drop into an operational decision: clear, compact, delegate, change model, or stop starting more work.

Exactly how to do it

Run /context all before forced compaction, while you can still decide what the summary must retain. For API automation, collect total_cost_usd and per-model usage from --output-format json. For team-wide attribution, export OpenTelemetry metrics rather than scraping individual terminals. Provider billing remains authoritative; local cost is an estimate.

10. Route model and effort to the shape of the task

What it is

Model routing means selecting the model and reasoning effort for the work rather than using one maximum setting everywhere. Claude Code accepts aliases such as sonnet, opus, and haiku, a hybrid opusplan setting, model choices in subagent and skill frontmatter, and effort controls through /effort, --effort, settings, or an environment variable.

Why it matters

Mechanical extraction, codebase search, architecture, and a subtle concurrency bug do not have the same reasoning requirement. Top models and maximum effort add latency and consume more tokens or subscription capacity; weak models waste the difference through corrections when the task is genuinely hard. Routing is useful only when it reduces total turns while preserving correctness, which is why the decision should be tied to a task class and measured.

Exactly how to do it

claude --model sonnet --effort medium
claude --model opus --effort xhigh
claude --model opusplan

/model sonnet
/effort high
/effort auto

Set model in settings only for a starting default, not as enforcement; users can still switch. Put model: haiku and an appropriate effort: in a narrow subagent definition. Enterprise deployments should pin provider-specific model IDs so an alias does not move before the account supports the new version. Record result quality, turns, elapsed time, and cost for repeatable task classes.

11. Make headless and CI runs bounded and structured

What it is

Non-interactive mode runs Claude Code as a command-line component: claude -p reads a prompt and optional stdin, performs agent turns, prints text or JSON, and exits. It supports validated JSON Schema output, streaming events, explicit tools, permission modes, turn caps, budget caps, and session resumption by ID.

Why it matters

Automation removes the person who would answer a prompt, notice an infinite loop, or reinterpret prose. A safe CI invocation therefore needs a closed tool set, a policy for unapproved calls, machine-readable output, and hard resource bounds. Without those, the same script can hang waiting for permission, mutate more than expected, or turn one review step into an unbounded API bill.

Exactly how to do it

git diff --merge-base origin/main HEAD | claude -p "Review for reproducible correctness bugs. Return only findings supported by the diff." --permission-mode dontAsk --allowedTools "Read" "Grep" "Glob" --output-format json --json-schema '{"type":"object","properties":{"findings":{"type":"array","items":{"type":"object","properties":{"file":{"type":"string"},"line":{"type":"integer"},"problem":{"type":"string"}},"required":["file","line","problem"]}}},"required":["findings"]}' --max-turns 6 --max-budget-usd 2.00

Parse .structured_output with jq; do not scrape the prose result. Use stream-json --verbose --include-partial-messages when a caller needs progress events. Piped stdin is capped, so point Claude at a file for large logs. Use dontAsk rather than bypass mode: anything outside the read-only set and explicit allow rules fails closed. Add --no-session-persistence for sensitive stateless jobs.

12. Turn repeated procedures into skills and slash commands

What it is

A skill is a directory whose SKILL.md describes a reusable workflow. Claude can select it when the description matches, or you can invoke it as /skill-name. Legacy files under .claude/commands/ still create slash commands, but skills are the preferred form because they can include scripts, templates, examples, tool restrictions, model and effort choices, and isolated execution.

Why it matters

Repeated prompting drifts. One person asks for the release checklist with six steps, another remembers five, and a third pastes an old version. Putting the procedure beside the code makes it reviewable and gives every session the same entry point. Unlike CLAUDE.md, only the skill name and description need standing context; the body and supporting references load when used.

Exactly how to do it

---
name: review-pr
description: Review a pull request for correctness and security findings with file and line evidence.
argument-hint: "[PR number or branch]"
disable-model-invocation: true
allowed-tools: Read, Grep, Glob, Bash
context: fork
model: sonnet
---

Review $ARGUMENTS.

1. Resolve the merge base and read the complete diff.
2. Read callers for every changed public function.
3. Run focused tests without modifying files.
4. Report only findings that can change runtime behaviour.
5. For each finding, give severity, file, line, failure path, and smallest fix.

Current diff summary:
!`git diff --stat --merge-base origin/main HEAD`

The project location is .claude/skills/name/SKILL.md; personal skills go under ~/.claude/skills/. Use $ARGUMENTS for invocation text and dynamic !`command` preprocessing only for commands you are willing to run before Claude sees the skill. Set disable-model-invocation: true when only a human should trigger it, and context: fork when its logs should stay outside the main conversation. Run /reload-skills after adding one in an existing directory.

Questions people ask

Keep reading