20 Claude Code Tips, Checked Against Anthropic's Docs

Most Claude Code sessions that go sideways fail in one of three ways. Claude didn't know something that lives only in your head. It had no way to tell whether the work was really done. Or it did something you assumed it never would. Each tip here fixes one of those, and none of them needs more than a few lines of setup.

What Claude Code is and where its settings live

Anthropic describes Claude Code as an agentic coding tool that reads your codebase, edits files, runs commands and connects to your development tools, in the terminal, IDE extensions, a desktop app and the browser. If you are still choosing a tool, our Codex vs Claude Code and Cursor vs Claude Code comparisons cover plans and limits. This post assumes you already use it.

Three settings files matter. ~/.claude/settings.json applies to you in every project. .claude/settings.json is shared: commit it and your team gets the same permissions and hooks. .claude/settings.local.json is yours for one project, and Claude Code keeps it out of git when it creates the file.

Memory and CLAUDE.md tips

CLAUDE.md is context, not configuration. Claude reads it every session and usually follows it, but nothing enforces it. That's why the shortest file that covers the facts beats a long manifesto.

1. Run /init, then cut CLAUDE.md down to what Claude can't see

/init writes a first CLAUDE.md from your codebase. Then trim it. Anthropic's docs suggest staying under about 200 lines and leaving out what Claude can find by reading the repo. Keep the commands that prove work is done and the decisions that live in people's heads.

# Commands
- Install: pnpm install
- Test one file: pnpm vitest run [path]
- Typecheck: pnpm tsc --noEmit (run it before you say a task is done)

# Things the code won't tell you
- Staging deploys from the release branch, never from main
- Integration tests need the local Postgres on port 5433 (docker compose up db)
- Never edit src/generated/; pnpm codegen rebuilds it

2. Scope rules to the files they apply to

A migration rule is noise while Claude edits CSS. Put it in .claude/rules/ with a paths field and it loads only when Claude reads or edits a matching file.

---
paths:
  - "db/migrations/**/*.sql"
---

# Migration rules
- Every migration gets a matching down migration in the same folder
- Never rename a column in one step: add, backfill, then drop in a later release
- Run pnpm db:check after writing a migration and paste the output

3. Keep personal notes out of the shared file

Your sandbox URL doesn't belong in the team's CLAUDE.md. Put it in CLAUDE.local.md and add that file to .gitignore. Using several worktrees? Import a file from your home folder instead, since a gitignored file exists only in the worktree where you made it.

# CLAUDE.local.md (gitignored)
- My local API runs on http://localhost:4100
- Use the seed account in scripts/seed-users.ts for manual testing
- Notes I reuse in every worktree: @~/.claude/notes/billing-service.md

4. Let auto memory learn, and audit it with /memory

Auto memory is on by default in local sessions: when you correct Claude or ask it to remember something, it can save a note for next time. /memory lists your instruction files, toggles auto memory and opens the memory folder so you can delete stale notes.

remember that the payments sandbox resets every night at midnight UTC, so old test charges disappear

/memory

Planning and prompting tips

A specific prompt is information Claude doesn't have: which file, what the symptom is, what "fixed" looks like. The same habits that help in chat apply here, and our best Claude prompts cover them for the chat app.

5. Plan big changes before any file moves

Plan mode lets Claude read files and propose a plan without editing your source. Press Shift+Tab to cycle into it, or prefix one prompt with /plan. Press Ctrl+G to edit the plan in your text editor before you approve it.

claude --permission-mode plan

/plan move session storage from cookies to Redis. List every file you would touch, the order of the changes and how we roll back. Don't edit anything yet.

6. Give Claude a check it can run

Anthropic's best-practices page leans on this one hardest. Without a pass or fail signal, Claude stops when the work looks done. With a test, build or linter, it fixes what broke and runs the check again. Ask for the command output as evidence.

The CSV export drops rows whose name contains a comma. Reproduce it with a failing test in tests/export.test.ts, fix it in src/export/csv.ts, then run pnpm vitest run tests/export.test.ts and show me the output. Done means that test and the existing export tests pass.

7. Hand over the file, the log or the screenshot

Describing an error loses detail. Type @ and a path to include a file in your message, paste a screenshot straight into the prompt, or pipe command output into claude -p from your shell.

cat logs/deploy-failure.txt | claude -p "find the first real error in this log and the file it points to"

Compare @src/components/Pricing.tsx with the screenshot I pasted and list every spacing difference

8. Steer early, and restart after two failed corrections

Watch the first minute. If you've corrected the same thing twice, the docs recommend /clear and one better prompt over a third correction. Checkpoints cover only edits made with Claude's file tools, so keep committing to git.

Esc        stop the current action and keep the work so far
Esc Esc    open the rewind menu (on an empty prompt)
/rewind    restore code, conversation or both to an earlier prompt
/clear     start fresh with a better prompt

Permission and safety tips

Anything that must always or never happen belongs here, not in CLAUDE.md. Permission rules and hooks are enforced by Claude Code, the program, so they hold even when the model forgets.

9. Write allow and deny rules instead of clicking through prompts

Manage rules with /permissions or in a settings file. Claude Code checks deny, then ask, then allow, so a broad deny always wins, and Read deny rules keep secrets away from Claude's file tools.

{
  "permissions": {
    "allow": [
      "Bash(pnpm test *)",
      "Bash(pnpm lint *)",
      "Bash(git diff *)"
    ],
    "deny": [
      "Bash(git push *)",
      "Read(./.env)",
      "Read(./secrets/**)"
    ]
  }
}

10. Pick a permission mode on purpose

Manual mode (config value default) asks before most actions, acceptEdits lets file edits run, plan blocks edits, auto has a classifier review actions instead of you, and dontAsk denies anything not pre-approved, which suits CI. The docs say new terminal and VS Code sessions start in auto mode.

claude --permission-mode acceptEdits
claude --permission-mode plan
claude -p "run the test suite" --permission-mode dontAsk --allowedTools "Bash(pnpm test *)" "Read"

11. Use a PreToolUse hook for anything that must never happen

Hooks are shell commands Claude Code runs at fixed points, so they don't rely on the model remembering a rule. A PreToolUse hook that exits with code 2 blocks the call and sends its stderr to Claude as the reason. Type /hooks to confirm it loaded.

#!/bin/bash
# .claude/hooks/no-prod.sh: block shell commands aimed at production
CMD=$(jq -r '.tool_input.command')
if echo "$CMD" | grep -qE -- '--context[= ]prod|PROD_DATABASE_URL'; then
  echo "Blocked: this repo never runs commands against production" >&2
  exit 2
fi
exit 0

# in .claude/settings.json
{
  "hooks": {
    "PreToolUse": [
      { "matcher": "Bash", "hooks": [ { "type": "command", "command": "\"$CLAUDE_PROJECT_DIR\"/.claude/hooks/no-prod.sh" } ] }
    ]
  }
}

12. Make 'done' mean the checks pass with a Stop hook

A Stop hook runs whenever Claude tries to end its turn. If your command exits with code 2, Claude gets its stderr and keeps working. Per the docs, Claude Code overrides the block after eight stops in a row with no tool call between them.

{
  "hooks": {
    "Stop": [
      { "hooks": [ { "type": "command", "command": "pnpm lint 1>&2 || exit 2" } ] }
    ]
  }
}

Reusable workflow tips

Once a prompt works three times, stop retyping it. Skills hold procedures, subagents hold focused workers, and MCP servers bring in outside tools. If MCP is new to you, start with our explainer on what MCP is and why it matters.

13. Turn a procedure you keep pasting into a skill

A skill is a folder with a SKILL.md file whose body loads only when it runs. Custom commands have been merged into skills, so .claude/commands/deploy.md and .claude/skills/deploy/SKILL.md both create /deploy. Set disable-model-invocation: true on anything with side effects.

---
name: release-notes
description: Drafts release notes from merged pull requests. Use when the user asks for release notes or a changelog entry.
disable-model-invocation: true
---

Draft release notes for version $ARGUMENTS.
1. Run git log --merges --oneline for the range since the last tag
2. Group changes under Added, Changed and Fixed
3. Write one plain sentence per change, for customers rather than engineers
4. Flag anything that changes pricing, permissions or data retention

# run it with: /release-notes [version]

14. Give narrow jobs to a subagent

A subagent works in its own context window with its own prompt, tools and model, then returns a summary. Only name and description are required. The docs are blunt: delegating doesn't improve the answer, but a fresh reviewer that never saw your reasoning does help.

---
name: test-gap-finder
description: Finds untested branches in changed code. Use after a feature is implemented and before review.
tools: Read, Grep, Glob, Bash
model: sonnet
---

You review the current git diff for code paths that no test reaches.
For each gap, give the file, the line, the input that reaches it and a one-line test name.
Do not write or edit files. Report at most 10 gaps, riskiest first.

15. Add MCP servers at the right scope

Local scope (the default) keeps a server private to you in one project, user scope covers all your projects, and project scope writes it to .mcp.json for the team. Anthropic warns that servers fetching outside content can expose you to prompt injection.

claude mcp add --transport http --scope project [name] [server URL]
claude mcp list
/mcp

Context and cost tips

Anthropic's best-practices page says running out of context is now rare, since most current models have a 1M-token window. Clearing still matters: a focused conversation gives better answers and costs less.

16. Compact with a focus, and clear between tasks

Automatic compaction guesses what matters. Run /compact with instructions before a long new step, /context to see what fills the window, and /clear when the next task is unrelated. Instructions you only typed in chat get summarized; CLAUDE.md is re-read from disk.

/context
/compact keep the failing test names, the root cause and the remaining steps
/clear

17. Watch /usage and match model and effort to the job

/usage (alias /cost) shows session cost and plan limits. Anthropic's cost guide says Sonnet handles most coding tasks well and costs less than Opus, and suggests lower effort for simple tasks.

/usage
/model
/effort low

18. Ask side questions with /btw

Quick question mid-task? /btw answers it without adding anything to the conversation history, so the main thread stays on the work.

/btw which file defines the retry limit for outgoing webhooks?

Parallel and scripted work tips

The last two tips take Claude Code out of a single terminal tab: several isolated sessions at once, and runs that start from a script or CI job.

19. Run parallel sessions in git worktrees

Two sessions in one checkout collide. Start each with --worktree (or -w) and a name to get its own worktree under .claude/worktrees/ on a branch named worktree-[name]. Install dependencies there first.

claude --worktree checkout-redesign
claude --worktree fix-flaky-auth-test

echo ".claude/worktrees/" >> .gitignore

20. Script repeat jobs with claude -p

The -p flag runs Claude Code non-interactively. It reads stdin and takes --allowedTools and --output-format json. Add --bare in CI: without it, a -p run loads the project's hooks and .mcp.json servers even in a folder you never trusted.

git diff main | claude -p "review this diff for missing error handling and list file:line for each issue" > review.md

claude --bare -p "list every TODO added on this branch with file and line" --allowedTools "Read" "Grep" "Bash(git diff *)" --output-format json

Which Claude Code feature to use for which job

Common mistakes

• Describing your architecture in CLAUDE.md. Anthropic's docs say Claude reads the repo itself; write down only what isn't in it.
• SHOUTING a rule Claude keeps missing. The docs say piling on emphasis makes Claude over-apply it. Turn a hard rule into a hook or a deny rule, or shorten the file.
• Adding CLAUDE.local.md to a repo that relies on AGENTS.md. It counts as a CLAUDE.md file, so Claude stops reading AGENTS.md for you unless you change the Project instructions setting.
• Treating checkpoints as version control. Files changed by shell commands aren't restored by /rewind. Commit often.
• Running claude -p in CI without --bare. The run can load hooks and MCP servers from the checked-out repo.
• Connecting MCP servers you haven't vetted. A server that pulls in outside content can carry prompt injection into your session.

For habits that apply to any AI coding tool, such as reviewing every diff and keeping changes small, see our best practices for AI coding.

Frequently Asked Questions

What are the most useful Claude Code tips for beginners?
Run /init to get a starter CLAUDE.md and cut it down to what Claude can't learn from the code, use plan mode (Shift+Tab or /plan) before large changes, give Claude a test or build command it can run to check its own work, and run /clear when you switch to an unrelated task.

Where does Claude Code keep its instructions and settings?
Instructions live in ./CLAUDE.md or ./.claude/CLAUDE.md (team), ~/.claude/CLAUDE.md (you) and CLAUDE.local.md (you, one project). Settings live in ~/.claude/settings.json, .claude/settings.json and .claude/settings.local.json at the same three levels. Skills sit in .claude/skills, subagents in .claude/agents and project MCP servers in .mcp.json.

Does Claude Code read AGENTS.md?
Yes, when there is no CLAUDE.md or CLAUDE.local.md in your working directory or above it. If both exist, Claude reads the CLAUDE.md files only, unless you change the Project instructions setting in /config or import AGENTS.md from CLAUDE.md.

How do I stop Claude Code asking for permission on every command?
Add allow rules for commands you trust, such as Bash(pnpm test *), through /permissions or .claude/settings.json, and pick a mode that fits: acceptEdits for file edits, or auto mode, where a classifier reviews actions instead of you. Deny rules still apply in every mode.

What is the difference between a skill and a subagent in Claude Code?
A skill is a SKILL.md file of instructions that runs in your conversation when you type /skill-name or when Claude decides it is relevant. A subagent is a separate worker with its own context window, system prompt, tools and model, which does a side task and returns a summary.

How can I keep Claude Code costs down?
Run /clear between unrelated tasks, check /usage for session cost and plan limits, and match the model and effort to the job with /model and /effort. Anthropic's cost guide says Sonnet handles most coding tasks well and costs less than Opus, and its subagent docs note that subagent requests count toward the same usage limits.