Content
# Claude Code Tips
Collection of my favorite Claude Code tips as I explore it.
## Table of Contents
### General
- [Tip 1: Name and resume sessions like git branches](#tip-1-name-and-resume-sessions-like-git-branches)
- [Tip 2: Match your effort level to the task](#tip-2-match-your-effort-level-to-the-task)
- [Tip 3: Skip local file discovery for scripted runs](#tip-3-skip-local-file-discovery-for-scripted-runs)
- [Tip 4: Turn on Explanatory or Learning mode to study a codebase](#tip-4-turn-on-explanatory-or-learning-mode-to-study-a-codebase)
- [Tip 5: Move sessions between your laptop, phone, and the cloud](#tip-5-move-sessions-between-your-laptop-phone-and-the-cloud)
- [Tip 6: Turn a recurring task into a loop or a scheduled job](#tip-6-turn-a-recurring-task-into-a-loop-or-a-scheduled-job)
- [Tip 7: Understand what auto mode decides for you](#tip-7-understand-what-auto-mode-decides-for-you)
- [Tip 8: Track your token spend with ccusage](#tip-8-track-your-token-spend-with-ccusage)
- [Tip 9: Organize multiple projects with a terminal multiplexer app](#tip-9-organize-multiple-projects-with-a-terminal-multiplexer-app)
- [Tip 10: View all background sessions with agent view](#tip-10-view-all-background-sessions-with-agent-view)
- [Tip 11: Install a language server plugin for real code navigation](#tip-11-install-a-language-server-plugin-for-real-code-navigation)
- [Tip 12: Check your context usage with /context](#tip-12-check-your-context-usage-with-context)
- [Tip 13: Analyze your usage patterns with /insights](#tip-13-analyze-your-usage-patterns-with-insights)
### Command
- [Tip 1: Give Claude a standing goal for the whole session](#tip-1-give-claude-a-standing-goal-for-the-whole-session)
- [Tip 2: Let /batch run a migration across hundreds of files](#tip-2-let-batch-run-a-migration-across-hundreds-of-files)
- [Tip 3: Run parallel sessions in isolated worktrees](#tip-3-run-parallel-sessions-in-isolated-worktrees)
- [Tip 4: Pre-approve the commands you already trust](#tip-4-pre-approve-the-commands-you-already-trust)
- [Tip 5: Sandbox risky commands instead of prompting for each one](#tip-5-sandbox-risky-commands-instead-of-prompting-for-each-one)
- [Tip 6: Script Claude into CI and pre-commit hooks](#tip-6-script-claude-into-ci-and-pre-commit-hooks)
- [Tip 7: Bootstrap CLAUDE.md with /init instead of starting from a blank file](#tip-7-bootstrap-claudemd-with-init-instead-of-starting-from-a-blank-file)
- [Tip 8: Be aware of ultra features](#tip-8-be-aware-of-ultra-features)
### Agent
- [Tip 1: Define reusable subagents instead of re-explaining a role every time](#tip-1-define-reusable-subagents-instead-of-re-explaining-a-role-every-time)
- [Tip 2: Delegate research to a subagent to keep it out of your context](#tip-2-delegate-research-to-a-subagent-to-keep-it-out-of-your-context)
- [Tip 3: Have a fresh subagent grade the work before you call it done](#tip-3-have-a-fresh-subagent-grade-the-work-before-you-call-it-done)
- [Tip 4: Batch large changes across worktree-isolated agents](#tip-4-batch-large-changes-across-worktree-isolated-agents)
- [Tip 5: Use agent teams when work needs multiple roles, not just parallel copies](#tip-5-use-agent-teams-when-work-needs-multiple-roles-not-just-parallel-copies)
### Skill
- [Tip 1: Restrict a skill to manual invocation so Claude doesn't guess when to use it](#tip-1-restrict-a-skill-to-manual-invocation-so-claude-doesnt-guess-when-to-use-it)
- [Tip 2: Use another CLI when WebFetch can't fetch a page](#tip-2-use-another-cli-when-webfetch-cant-fetch-a-page)
- [Tip 3: Let a plugin enforce TDD and root-cause debugging discipline](#tip-3-let-a-plugin-enforce-tdd-and-root-cause-debugging-discipline)
- [Tip 4: Give Claude a real browser for pages WebFetch can't handle](#tip-4-give-claude-a-real-browser-for-pages-webfetch-cant-handle)
- [Tip 5: Browse skills.sh before writing one from scratch](#tip-5-browse-skillssh-before-writing-one-from-scratch)
- [Tip 6: Use skill-creator to create new skill](#tip-6-use-skill-creator-to-create-new-skill)
- [Tip 7: Install a skill to curb overengineering and unrequested changes](#tip-7-install-a-skill-to-curb-overengineering-and-unrequested-changes)
- [Tip 8: Turn a manual double-check into a self-verifying skill](#tip-8-turn-a-manual-double-check-into-a-self-verifying-skill)
### Mcp
- [Tip 1: Bundle MCP servers, skills, and hooks together as a plugin](#tip-1-bundle-mcp-servers-skills-and-hooks-together-as-a-plugin)
- [Tip 2: Tune how aggressively Claude loads your MCP tool definitions](#tip-2-tune-how-aggressively-claude-loads-your-mcp-tool-definitions)
- [Tip 3: Keep raw tool output out of your context with a sandboxed MCP server](#tip-3-keep-raw-tool-output-out-of-your-context-with-a-sandboxed-mcp-server)
- [Tip 4: Give Claude persistent memory across sessions with claude-mem](#tip-4-give-claude-persistent-memory-across-sessions-with-claude-mem)
- [Tip 5: Bridge Claude Code and Codex with a plugin](#tip-5-bridge-claude-code-and-codex-with-a-plugin)
- [Tip 6: Browse docs with Context7](#tip-6-browse-docs-with-context7)
### Prompt
- [Tip 1: Have Claude interview you before building something big](#tip-1-have-claude-interview-you-before-building-something-big)
- [Tip 2: Write the code in one session, review it in another](#tip-2-write-the-code-in-one-session-review-it-in-another)
- [Tip 3: Put your planning effort into plan mode, not into micromanaging](#tip-3-put-your-planning-effort-into-plan-mode-not-into-micromanaging)
- [Tip 4: Move plans out of the 30-day cache and into your repo](#tip-4-move-plans-out-of-the-30-day-cache-and-into-your-repo)
- [Tip 5: Keep exploration out of the plan you're about to approve](#tip-5-keep-exploration-out-of-the-plan-youre-about-to-approve)
### Hooks
- [Tip 1: Hook into specific moments in Claude's lifecycle](#tip-1-hook-into-specific-moments-in-claudes-lifecycle)
- [Tip 2: Auto-format on every edit with a PostToolUse hook](#tip-2-auto-format-on-every-edit-with-a-posttooluse-hook)
- [Tip 3: Use a Stop hook as a deterministic gate for unattended runs](#tip-3-use-a-stop-hook-as-a-deterministic-gate-for-unattended-runs)
- [Tip 4: Get worktree isolation on non-git version control](#tip-4-get-worktree-isolation-on-non-git-version-control)
- [Tip 5: Turn hooks into ambient audio cues](#tip-5-turn-hooks-into-ambient-audio-cues)
### Workflow
- [Tip 1: Treat CLAUDE.md as a file you keep improving, not a one-time README](#tip-1-treat-claudemd-as-a-file-you-keep-improving-not-a-one-time-readme)
- [Tip 2: Reserve "IMPORTANT" for the one rule Claude keeps missing](#tip-2-reserve-important-for-the-one-rule-claude-keeps-missing)
- [Tip 3: Let /doctor prune your CLAUDE.md for you](#tip-3-let-doctor-prune-your-claudemd-for-you)
- [Tip 4: Give Claude a way to check its own work](#tip-4-give-claude-a-way-to-check-its-own-work)
- [Tip 5: Run risky, unsupervised work in a container](#tip-5-run-risky-unsupervised-work-in-a-container)
### Context
- [Tip 1: Manage context deliberately instead of just filling it up](#tip-1-manage-context-deliberately-instead-of-just-filling-it-up)
## General
### Tip 1: Name and resume sessions like git branches
Claude Code saves every conversation locally, so a task that spans multiple sittings doesn't need re-explaining from scratch. Run `/rename` to give a session a descriptive name, the same way you'd name a branch. Use `claude --continue` to pick up your most recent session, or `claude --resume` to choose from a list of past ones. Treat each workstream as its own persistent context: one session per feature, not one giant thread for everything you touch this week. Descriptive names pay off weeks later, when you're trying to remember which session already has the context you need.
Example:
```
claude --resume
```
Then pick "oauth-migration" from the list to jump back into that work with full context intact.
Reference: [Manage sessions](https://code.claude.com/docs/en/sessions)
### Tip 2: Match your effort level to the task
Run `/effort` to control how hard Claude thinks before responding. Levels range from low (fewer tokens, faster) through medium, high, xhigh, max, and auto, where Claude picks per request. The default is high on Team, Enterprise, and direct API access, and medium everywhere else. Reach for xhigh on complex coding or agentic work when you want deeper reasoning without paying the full cost of max. Save max for the genuinely hard cases: a gnarly debugging session or an architecture decision where you want Claude to think for as long as it needs. Max burns through usage limits faster, so turn it on for the session that needs it rather than leaving it as your default.
Example:
```
/effort xhigh
Refactor the auth module to support multi-tenant sessions without breaking existing token validation.
```
Reference: [Power user tips](https://support.claude.com/en/articles/14554000-claude-code-power-user-tips)
### Tip 3: Skip local file discovery for scripted runs
By default, `claude -p` and the SDKs search your filesystem for CLAUDE.md files, settings, and MCP configs before every run. That's the right behavior interactively, but for scripted or CI usage you already know exactly what should load. Add `--bare` and pass `--system-prompt`, `--mcp-config`, and `--settings` explicitly instead, and startup gets roughly 10x faster. This local search was a default set early on, and the Claude Code team plans to flip it in a future version, so `--bare` is the flag worth reaching for today whenever you're calling Claude from a script.
Example:
```
claude -p "summarize this codebase" \
--output-format=stream-json \
--verbose \
--bare
```
Reference: [Power user tips](https://support.claude.com/en/articles/14554000-claude-code-power-user-tips)
### Tip 4: Turn on Explanatory or Learning mode to study a codebase
Output styles change how Claude talks, not just what it does. Set one in `/config`. Explanatory mode has Claude narrate the frameworks and patterns behind its own changes as it works, which is useful when you're onboarding onto code you didn't write. Learning mode goes a step further and coaches you through the change instead of just making it for you. Combine either one with a direct ask: have Claude generate an HTML walkthrough of a tricky module, draw an ASCII diagram of a protocol, or quiz you on a file until your explanation lines up with its own.
Example:
```
/config
```
Set output style to Explanatory, then:
```
Walk me through how the request middleware pipeline works in @src/server/middleware, explaining the pattern as you go.
```
Reference: [Power user tips](https://support.claude.com/en/articles/14554000-claude-code-power-user-tips)
### Tip 5: Move sessions between your laptop, phone, and the cloud
A session doesn't have to stay on one machine. Run `/teleport` (or `claude --teleport`) to pull a cloud session down and keep working from your terminal. Run `/remote-control` to flip that around and drive a local session from your phone or a browser instead. The Claude mobile app has a dedicated Code tab for this, and an iMessage plugin lets you fire off tasks from any Apple device without opening the app at all. If you want this available everywhere by default, turn on "Enable Remote Control for all sessions" in `/config` instead of switching it on per session.
Reference: [Power user tips](https://support.claude.com/en/articles/14554000-claude-code-power-user-tips)
### Tip 6: Turn a recurring task into a loop or a scheduled job
`/loop` repeats a task locally on an interval for up to three days, which covers things like babysitting open PRs or closing out stale ones without you kicking it off by hand each time. `/schedule` does the same job but runs in the cloud, so it keeps going after you close your laptop. The strongest version of this pattern pairs a schedule with a skill: write the workflow once as a skill, then schedule it to run on its own.
Example:
```
/loop 5m /babysit
/loop 1h /pr-pruner
```
```
/schedule a daily job that looks at all PRs shipped since yesterday and updates our docs based on the changes. Use the Slack MCP to message #docs-update with the changes
```
Reference: [Power user tips](https://support.claude.com/en/articles/14554000-claude-code-power-user-tips)
### Tip 7: Understand what auto mode decides for you
On Pro, Max, and Team plans, auto mode is the default permission mode for interactive terminal and VS Code sessions. A separate classifier model reviews each action before it runs and approves the routine ones on its own, only stopping you for things like scope escalation, unfamiliar infrastructure, or an action that looks driven by hostile content Claude just read. You can switch modes at any point in a session with Shift+Tab if you'd rather approve everything by hand for a while. For scripted runs, pass the mode explicitly instead of relying on the interactive default, and know that a non-interactive run doesn't stop just because the classifier blocks a few actions in a row.
Example:
```
claude --permission-mode auto -p "fix all lint errors"
```
Reference: [Permission modes](https://code.claude.com/docs/en/permission-modes)
### Tip 8: Track your token spend with ccusage
Claude Code writes every session's token counts to local JSONL logs but doesn't surface spend anywhere on its own. [ccusage](https://github.com/ccusage/ccusage) reads those logs directly and turns them into daily, weekly, monthly, and per-session usage reports, all without sending anything off your machine. It also tracks Claude's 5-hour billing blocks live, so you can watch usage accumulate against your current window instead of finding out you're close to a limit after you've hit it. Costs are estimated from public pricing rather than pulled from your actual bill, so treat the numbers as a close approximation, not a receipt. Run it with `npx` and no install step, which makes it easy to check on a whim or drop into a dashboard script.
Example:
```
npx ccusage@latest
npx ccusage@latest blocks --live
```
Reference: [ccusage](https://github.com/ccusage/ccusage)
### Tip 9: Organize multiple projects with a terminal multiplexer app
Running several Claude Code sessions across different projects gets messy fast when they're all just tabs in one terminal window. [Muxy](https://muxy.app/) is a native Mac terminal built on Ghostty that groups terminals by project instead of by raw session, so each codebase gets its own space with its own tabs, split panes, and git worktrees. Its iOS and Android companion apps let you check on or drive a running session from your phone, similar to Claude's own remote control feature but at the multiplexer level instead of the session level. Muxy also ships an Agent Skill (`muxy-cli`) that lets Claude open projects, create splits, send keystrokes, and read pane output on its own, so a session can manage its own workspace layout instead of just running inside it.
Example:
```
npx skills add github.com/muxy-app/muxy/tree/main/Muxy/Resources/skills/muxy-cli
```
Reference: [Muxy](https://muxy.app/)
### Tip 10: View all background sessions with agent view
`claude agents` opens one screen listing every background session you have running: what needs your input, what's still working, and what's finished. Sessions group under those three headers, so you can scan a dozen tasks at once instead of opening each transcript to check on it.
Type into the dispatch input at the bottom to start a new background session right from the list, or press Enter on a row to attach and drop into the full interactive session, complete with a short recap of what happened while you were away. Press the left arrow or run `/exit` to detach and return to the list.
Run `/background` (or `/bg`) from any interactive session to send it to the background instead of quitting it, and `/fork` to split off a copy of the current conversation as a new row while the original keeps running. It's in research preview, and background sessions burn through your subscription usage the same as an interactive one: ten running in parallel costs roughly ten times what one does.
Example:
```
claude agents
```
Then type at the dispatch input:
```
run the test suite and fix any failures
```
Reference: [Manage multiple agents with agent view](https://code.claude.com/docs/en/agent-view)
### Tip 11: Install a language server plugin for real code navigation
Claude Code has a built-in `LSP` tool, but it stays inactive until you install a language server for your codebase. With one installed, Claude can jump to a symbol's definition, find every reference to it, read type information at a position, list the symbols in a file or across the whole workspace, find implementations of an interface, and trace call hierarchies. That's a step up from grep, which only matches text and can't tell a real reference from a coincidental match. The LSP tool also works quietly in the background: after every edit, it reports type errors and warnings right away, so Claude can fix them before running a full build. Anthropic maintains ready-made plugins for common languages, including `typescript-lsp`, `pyright-lsp`, `gopls-lsp`, `rust-analyzer-lsp`, `csharp-lsp`, `jdtls-lsp`, `kotlin-lsp`, `clangd-lsp`, `ruby-lsp`, `php-lsp`, `swift-lsp`, and `lua-lsp`. Install the one matching your stack with `/plugin`, and Claude picks it up automatically, no extra config needed.
Example:
```
/plugin
```
Search "lsp" under Discover, install `typescript-lsp` (or whichever matches your stack), then ask:
```
Find every caller of formatCurrency and update the call sites to pass the new locale argument.
```
Reference: [Tools reference: LSP tool behavior](https://code.claude.com/docs/en/tools#lsp-tool-behavior)
### Tip 12: Check your context usage with /context
Run `/context` to see exactly what's filling your context window. It breaks down token usage by category: system prompt, tools, MCP servers, memory files, loaded CLAUDE.md files, and conversation history, plus how much of the window is left. This is the fastest way to catch a bloated CLAUDE.md or a memory file eating tokens before auto-compaction kicks in and summarizes your session. It also lists which CLAUDE.md and memory files are actively loaded, so you can tell what's shaping Claude's behavior right now instead of guessing.
Reach for it when a session feels sluggish, when you're not sure why context filled up faster than expected, or before starting a long task where you want some headroom left.
Example:
```
/context
```
Reference: [Context window](https://code.claude.com/docs/en/context-window)
### Tip 13: Analyze your usage patterns with /insights
Run `/insights` for a report on how you work, not how many tokens you've burned. It looks at your recent sessions on this machine and writes an HTML report covering what you spend time on, friction points like misunderstood requests or buggy code, and features worth trying that you haven't picked up yet. A single run covers up to 200 sessions it hasn't seen before and skips very short ones; when sessions are left out, the header shows the analyzed count against the total, like `200 sessions (412 total)`.
The report lands at `~/.claude/usage-data/report.html`, and each run keeps a timestamped copy alongside it instead of overwriting the last one, so you can compare over time. Reports follow the same cleanup schedule as other session data and get deleted after `cleanupPeriodDays` (30 days by default). It only sees sessions on this machine, not other devices or claude.ai, and it's not available from cloud sessions at all. Unlike ccusage (Tip 8), which parses local logs for free, `/insights` runs through your actual account, so a report counts against your plan or API usage like any other command.
Example:
```
/insights
```
Reference: [Manage costs effectively: Analyze your usage patterns](https://code.claude.com/docs/en/costs#analyze-your-usage-patterns)
## Command
### Tip 1: Give Claude a standing goal for the whole session
`/goal` sets a condition that gets re-checked after every turn, not just once at the start. A separate evaluator watches for it, and Claude keeps working across turns until the condition actually resolves, instead of treating "done" as something it only claims once. If Claude genuinely can't get there, Claude Code eventually stops the run rather than looping forever, but the goal stays set so you can pick it back up later. This is the difference between asking Claude to fix something once and asking it to keep trying until the thing is actually fixed.
Example:
```
/goal all tests in the payments/ directory pass and `npm run typecheck` is clean
```
Reference: [/goal](https://code.claude.com/docs/en/goal)
### Tip 2: Let /batch run a migration across hundreds of files
`/batch` interviews you about a migration up front, then fans the work out across as many worktree agents as it needs, dozens or hundreds if the change calls for it. Each agent works in its own isolated worktree, tests its own changes, and opens its own PR. You answer a handful of questions once instead of babysitting a change that touches your whole codebase file by file.
Example:
```
/batch migrate src/ from JavaScript to TypeScript
```
Reference: [Power user tips](https://support.claude.com/en/articles/14554000-claude-code-power-user-tips)
### Tip 3: Run parallel sessions in isolated worktrees
The single biggest change most engineers can make to their workflow is running 3-5 Claude sessions at once, each in its own git worktree, so they can't step on each other's file edits. `claude --worktree` (or `claude --worktree my-feature`) starts a session in a fresh worktree, and adding `--tmux` gives it its own detachable terminal session too. If your version control isn't git (Mercurial, Perforce, SVN), define `WorktreeCreate` and `WorktreeRemove` hooks in settings.json to get the same isolation. Name your worktrees and set up shell aliases to jump between them, or you'll quickly lose track of which terminal is doing what.
Example:
```
claude --worktree auth-refactor --tmux
```
Reference: [Hooks](https://code.claude.com/docs/en/hooks)
### Tip 4: Pre-approve the commands you already trust
Instead of choosing between approving every single action or skipping permissions entirely, run `/permissions` to allowlist the commands you already trust, then check that list into `.claude/settings.json` for your whole team. It supports real wildcard syntax, so a rule like `"Bash(bun run *)"` or `"Edit(/docs/**)"` covers a whole category of actions at once. Everything you add is additive to the small set of safe commands Claude Code pre-approves out of the box, and the result is an auditable allowlist instead of a black box.
Example: `.claude/settings.json`
```json
{
"permissions": {
"allow": ["Bash(bun run *)", "Edit(/docs/**)"]
}
}
```
Reference: [Power user tips](https://support.claude.com/en/articles/14554000-claude-code-power-user-tips)
### Tip 5: Sandbox risky commands instead of prompting for each one
`/sandbox` opts you into Claude Code's open source sandbox runtime, which isolates both the filesystem and the network on your own machine. You get three modes: sandboxed with auto-allow, sandboxed with regular permission prompts still on, or no sandbox at all. This cuts the number of prompts you see while actually improving safety, since a sandboxed command that goes wrong can't reach outside its box in the first place. It's worth turning on before you turn on auto mode, not instead of it, since the two solve different problems.
Reference: [Power user tips](https://support.claude.com/en/articles/14554000-claude-code-power-user-tips)
### Tip 6: Script Claude into CI and pre-commit hooks
`claude -p "prompt"` runs Claude non-interactively and still creates a resumable session unless you pass `--no-session-persistence`. Pick your output format based on what's downstream: plain text for a one-off query, `--output-format json` for a single object you can parse, or `--output-format stream-json` for one JSON event per line when you want to process output as it arrives. This is what turns Claude Code into something you wire into a pipeline rather than something you only run by hand.
Example:
```
claude -p "list all API endpoints" --output-format json
```
Reference: [Headless mode](https://code.claude.com/docs/en/headless)
### Tip 7: Bootstrap CLAUDE.md with /init instead of starting from a blank file
`/init` is an interactive slash command you run inside a session, not a terminal command. It scans your repo, build files, and configs, then drafts a starter CLAUDE.md with the build and test commands, directory layout, and conventions it can infer on its own. Run it again later and it proposes edits to your existing CLAUDE.md instead of overwriting it.
Treat the output as a first draft, not a finished file: it can't guess deployment steps, business rules, or team conventions that live only in people's heads, so add those yourself before committing it. Once it's in, keep improving it the way the Workflow tips below describe, catching a mistake and writing the fix back into the file so the whole team benefits from it.
Example:
```
/init
```
Reference: [CLAUDE.md files](https://code.claude.com/docs/en/memory)
### Tip 8: Be aware of ultra features
Claude Code has picked up several features named around "ultra," and they're easy to mix up since only one of them is a slash command in the usual sense. `/code-review ultra` (aliased `/ultrareview` where available) is a research-preview command that sends a branch diff or GitHub PR to a fleet of reviewer agents running in a remote sandbox, with every finding independently reproduced before it's reported back, a heavier and slower tool than the local `/code-review`. `/effort ultracode` is a session setting, not a model effort level: it pushes reasoning to `xhigh` and turns on automatic workflow orchestration so Claude plans and executes multi-step tasks with its own dynamic subagent workflows.
It's easy to assume "ultracode" also works as an inline prompt keyword the way other effort boosts do, but it doesn't. That inline trigger is a different word, `ultrathink`, which asks for deeper reasoning on just that one turn without touching your session's effort setting at all. And if you're looking for `/ultraplan`, stop: Anthropic retired the command, its keyword trigger, and the plan-approval dialog option that used to launch it, pointing people toward Plan Mode or Claude Code on the web instead.
See [tips/ultra-features.md](tips/ultra-features.md) for a full comparison table, including model and account requirements for each.
Example:
```
/code-review ultra
```
```
ultrathink: find the root cause of the race condition in the connection pool, then fix it
```
Reference: [Ultrareview](https://code.claude.com/docs/en/ultrareview), [Model configuration](https://code.claude.com/docs/en/model-config)
## Agent
### Tip 1: Define reusable subagents instead of re-explaining a role every time
Drop a markdown file into `.claude/agents/` with a `name`, `description`, and optionally a restricted `tools` list, and you have a reusable subagent you can invoke with `claude --agent=<name>` or let Claude reach for on its own. A read-only agent scoped to just the Read tool is a common one to keep around for safe exploration of unfamiliar code. Boris Cherny keeps a small library of these for jobs he runs often, a code simplifier, a build checker, a test runner, each one starting from a clean context and returning just a result.
Example: `.claude/agents/ReadOnly.md`
```
---
name: ReadOnly
description: Read-only agent restricted to the Read tool only
tools: Read
---
You are a read-only agent that cannot edit files or run bash.
```
Reference: [Subagents](https://code.claude.com/docs/en/sub-agents)
### Tip 2: Delegate research to a subagent to keep it out of your context
Context is the real constraint in a long session, and exploration is usually the biggest cost against it. Tell Claude to use a subagent to investigate something, and that research happens in a separate context entirely, leaving your main conversation focused on implementation. This matters most on an unfamiliar codebase, where the alternative is burning through half your context window finding the right files before you've written a line of code.
Example:
```
Use a subagent to investigate how our existing rate limiter is implemented and where it's used, then summarize the findings before we touch anything.
```
Reference: [Subagents](https://code.claude.com/docs/en/sub-agents)
### Tip 3: Have a fresh subagent grade the work before you call it done
The longer a run goes unattended, the more it matters that something other than the agent that did the work checks it. Before treating a task as finished, have a subagent review the diff in a fresh context with only the diff and your criteria, not the reasoning that produced the change, so it isn't grading its own homework. Claude Code ships a `/code-review` skill that does exactly this: it reviews the current diff in a fresh subagent and reports findings back to your session.
Example:
```
/code-review
```
or write your own criteria:
```
Spin up a subagent with only the current diff and this checklist: no unhandled errors, no new dependencies, tests cover the new branch. Report gaps, don't fix them.
```
Reference: [Subagents](https://code.claude.com/docs/en/sub-agents)
### Tip 4: Batch large changes across worktree-isolated agents
Add `isolation: worktree` to a subagent's frontmatter and Claude Code runs that agent in its own git worktree automatically, which matters once you're launching many agents against the same repo at the same time. This is what makes a prompt like "migrate all sync IO to async, launch 10 parallel agents" safe to run: each agent tests its own change end to end and opens its own PR, without ten agents fighting over the same working directory.
Example: `.claude/agents/worktree-worker.md`
```
---
name: worktree-worker
model: haiku
isolation: worktree
---
```
Then prompt:
```
Migrate all sync IO to async. Batch the changes and launch 10 parallel agents with worktree isolation. Each agent should test its changes end to end, then put up a PR.
```
Reference: [Power user tips](https://support.claude.com/en/articles/14554000-claude-code-power-user-tips)
### Tip 5: Use agent teams when work needs multiple roles, not just parallel copies
A subagent hands back one result and disappears. An agent team keeps every teammate alive as its own full Claude Code session, one that can message any other teammate directly and pull work off a task list the whole team shares. One session takes the lead, spawning teammates and handing out tasks, but you can talk to any teammate directly and redirect it yourself without going through the lead.
That gives you real coordination a subagent can't: teammates compare notes, challenge each other's findings, or split ownership across a feature's frontend, backend, and tests. Reach for it when you're debugging with competing hypotheses, running a review that needs several angles at once, or splitting a feature cleanly enough to give each teammate their own slice.
It's still experimental, gated behind `CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1`, and burns tokens fast since every teammate holds its own full context window, so start with 3-5 teammates and save it for work where the parallelism actually pays off. For anything sequential or single-file, delegating to a plain subagent (Tip 2) stays cheaper and simpler.
Example: `.claude/settings.json`
```json
{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }
```
Then:
```
Spawn a team of 3 to review the auth module: one on token handling,
one on session management, one on input validation. Have them share
findings with each other before reporting back to me.
```
Reference: [Agent teams](https://code.claude.com/docs/en/agent-teams)
## Skill
### Tip 1: Restrict a skill to manual invocation so Claude doesn't guess when to use it
A skill is a `SKILL.md` file under `.claude/skills/<name>/` with a `name` and `description`, and Claude applies it automatically when it looks relevant, or you can call it directly with `/skill-name`. Some skills shouldn't be auto-invoked, like an issue-fixer that takes an argument and touches multiple files on your say-so alone. Set `disable-model-invocation: true` in the frontmatter for those, and the skill only runs when someone explicitly asks for it by name.
Example: `.claude/skills/fix-issue/SKILL.md`
```
---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Analyze and fix the GitHub issue: $ARGUMENTS.
1. Use `gh issue view` to get the issue details
2. Search the codebase for relevant files
3. Implement the fix and write a test for it
```
Example:
```
/fix-issue 482
```
Reference: [Skills](https://code.claude.com/docs/en/skills)
### Tip 2: Use another CLI when WebFetch can't fetch a page
WebFetch can't reach every site, Reddit is a common example. Rather than giving up, write a skill that shells out to a different CLI with its own web access through a tmux session: start it, send the query, capture the output, parse the result. Package this as a skill instead of pasting the same instructions into CLAUDE.md, since a skill only loads into context when Claude actually needs it, while anything in CLAUDE.md loads into every single conversation whether that conversation needs it or not.
Example:
```
Check how Claude Code skills are being discussed on Reddit and summarize the sentiment.
```
Reference: [Skills](https://code.claude.com/docs/en/skills)
### Tip 3: Let a plugin enforce TDD and root-cause debugging discipline
Left alone, Claude tends to jump straight to code. The [Superpowers](https://claude.com/plugins/superpowers) plugin is a skill pack that pushes back on that: it forces red-green-refactor TDD, so a test has to fail before any implementation gets written, and it runs a four-phase debugging process that investigates the root cause instead of guessing at a fix.
It also ships a brainstorming skill that questions your requirements before any code gets touched, and a review skill that hands the diff to a separate subagent instead of grading its own homework. These skills activate on their own once installed, so you don't have to invoke them by name, and every session inherits the same discipline instead of you re-explaining "write the test first" in every prompt.
Example:
```
/plugin install superpowers@claude-plugins-official
```
```
Add rate limiting to the public API.
```
Reference: [Discover and install plugins](https://code.claude.com/docs/en/discover-plugins)
### Tip 4: Give Claude a real browser for pages WebFetch can't handle
WebFetch reads static HTML, so it misses anything a page only renders after JavaScript runs, and it can't click a button, fill in a form, or step through a login. [agent-browser](https://github.com/vercel-labs/agent-browser) installs as a skill (`npx skills add vercel-labs/agent-browser`) and drives a real Chrome instance instead.
Claude reads the page's accessibility tree and gets back stable references like `@e2` for each interactive element, then clicks, types, or screenshots against that reference instead of guessing a CSS selector that breaks the moment the layout shifts. Reach for this when you're testing your own app end to end, reading a page that only renders after JavaScript runs, or walking through a flow that needs a login. Keep WebFetch for the simple case: pulling text off a page that doesn't need any interaction.
Example:
```
npx skills add vercel-labs/agent-browser
```
```
Open our staging checkout page, fill in the test card details, complete the purchase, and screenshot the confirmation screen.
```
Reference: [agent-browser](https://github.com/vercel-labs/agent-browser)
### Tip 5: Browse skills.sh before writing one from scratch
[skills.sh](https://www.skills.sh) is Vercel's directory of open-source agent skills, searchable by name or by what they do. Before writing a new skill from scratch, check whether someone already published one for the same job. The `npx skills` CLI handles the whole lifecycle: `npx skills add <owner/repo>` installs a skill from the registry, `npx skills list` shows what's installed, and `npx skills update` pulls the latest version of everything you've added instead of you tracking each source repo by hand. It's the same CLI Tip 4's agent-browser example uses to install, just applied as your everyday way of managing every skill you pull in, not a one-off install command.
Example:
```
npx skills add vercel-labs/agent-browser
npx skills list
npx skills update
```
Reference: [skills.sh](https://www.skills.sh)
### Tip 6: Use skill-creator to create new skill
Writing a `SKILL.md` by hand usually means guessing at the description and shipping it untested. The official [skill-creator](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/skill-creator) plugin turns that into a loop: draft the skill, write a handful of test prompts, run them with a Claude instance that has the skill against one that doesn't, and compare the outputs side by side in a local viewer. You look at the results, give feedback, and it rewrites the skill and reruns until the outputs are good.
Once the skill behaves the way you want, it has a separate step for optimizing the `description` field in the frontmatter. That field is the only thing Claude reads to decide whether to auto-invoke a skill, so a vague description means Claude either ignores the skill when it should fire or fires it when it shouldn't. The optimizer scores candidate descriptions against your test prompts and picks the one that triggers most reliably.
Example:
```
/plugin install skill-creator@claude-plugins-official
```
```
I want a skill that reviews Terraform plans for cost regressions before merge. Help me build and test it.
```
Reference: [skill-creator](https://github.com/anthropics/claude-plugins-official/tree/main/plugins/skill-creator)
### Tip 7: Install a skill to curb overengineering and unrequested changes
Left alone, Claude tends to make silent assumptions, add unrequested abstractions, and touch code beyond what was asked. [andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills) is a single CLAUDE.md file distilled from Andrej Karpathy's public notes on common LLM coding mistakes, and it pushes back on exactly those habits. It tells Claude to state its assumptions and ask when unsure instead of guessing, keep changes to the minimum the task needs, leave adjacent code alone, and turn each task into a success criterion it can verify before calling the work done.
Install it as a plugin with `/plugin install andrej-karpathy-skills@karpathy-skills`, or copy the file straight into your project's `.claude/` folder if you'd rather review it first. Once it's in place it applies to every session automatically, the same way any CLAUDE.md does, so there's no name to invoke.
Example:
```
/plugin install andrej-karpathy-skills@karpathy-skills
```
```
Add rate limiting to the public API.
```
Reference: [andrej-karpathy-skills](https://github.com/multica-ai/andrej-karpathy-skills)
### Tip 8: Turn a manual double-check into a self-verifying skill
Notice the checks you do by hand after Claude finishes: grepping logs for a request ID, confirming a payload didn't leak into an error log, re-reading a diff for a pattern you always catch. Each one you keep doing yourself is a verification step Claude can't infer on its own, so write it down as a skill instead of repeating the correction every time. A verification skill is a plain-English description of the check plus the fix, the same way you'd hand it to a new teammate: what to look for, and what to do when it's wrong.
How it gets triggered depends on the check. A standalone skill you invoke by name suits a cross-cutting audit like security or accessibility that doesn't need to run on every change. Embedding the check straight into a producing skill's instructions, like appending "run eslint on it and fix any errors" to a component-scaffolding skill, makes it run automatically every time that skill fires. Chaining several verification skills in sequence, for example `/code-review` then `/simplify` then `/verify`, turns a personal habit into a repeatable pipeline, and wiring that same chain into a GitHub Action makes it shared infrastructure instead of something only you remember to run.
Before writing one, check what's built in: the `/verify` skill, listing exact build and test commands in CLAUDE.md so Claude catches toolchain errors instead of guessing, and Claude Code's own code review integration.
Example: `.claude/skills/log-hygiene/SKILL.md`
```
---
name: log-hygiene
description: Check new error logs for a request ID and no leaked payload data
---
For any error log statement you add or touch:
1. Confirm it includes the current request ID
2. Confirm it does not log the raw request/response payload
3. If either check fails, fix it: add the request ID where it's missing,
and strip the payload from the log call
```
Reference: [Building verification loops in Claude Code with skills](https://claude.com/blog/building-verification-loops-in-claude-code-with-skills)
## Mcp
### Tip 1: Bundle MCP servers, skills, and hooks together as a plugin
Once you're managing more than one or two MCP connections, a plugin is the better unit to work in. A single plugin can bundle language servers, MCP connections, skills, agents, and hooks into one install. Run `/plugin` to install from Anthropic's official marketplace, or stand up an internal one for your org and check the marketplace reference into `settings.json` so every new developer gets it automatically on setup.
Example:
```
/plugin
```
or add a server directly:
```
claude mcp add sentry --url https://mcp.sentry.dev
```
Reference: [MCP](https://code.claude.com/docs/en/mcp)
### Tip 2: Tune how aggressively Claude loads your MCP tool definitions
Every MCP tool's schema counts against your context window before Claude has used it even once, and fifty tools can burn 10-20k tokens before you've typed a word. Tool search is on by default in current versions of Claude Code: instead of loading every schema upfront, Claude searches your tool catalog and pulls in only what the current task needs, up to five tools at a time. Set `ENABLE_TOOL_SEARCH=auto:5` if you want it to kick in earlier, once definitions cross 5% of the context window instead of the default threshold, or set it to `false` if you run a small, stable toolset and would rather load everything upfront and skip the extra round trip.
Reference: [Scale to many tools with tool search](https://code.claude.com/docs/en/agent-sdk/tool-search)
### Tip 3: Keep raw tool output out of your context with a sandboxed MCP server
Every byte a tool call returns lands in your context window, whether you needed all of it or not. [context-mode](https://github.com/mksglu/context-mode) is an MCP server that works around this: it runs commands and file reads in a subprocess, indexes the full output with SQLite, and hands back only what you explicitly print. A repo-wide grep or a log scan that would normally dump thousands of lines into the conversation instead returns a short, derived answer, and the rest stays searchable if you need it later.
It also snapshots the conversation right before a compaction and reindexes it, so a compacted session can pull back a specific decision or file instead of losing it for good. This is worth reaching for whenever the output size is unpredictable and you plan to filter it down anyway, not for a command whose short output you'd read in full regardless.
Example:
```
Count the exported functions in every .ts file under src/, then report only the top 10 by count.
```
With context-mode installed, Claude runs this in the sandbox and returns a 10-line summary instead of reading all the files into context.
Reference: [context-mode](https://github.com/mksglu/context-mode)
### Tip 4: Give Claude persistent memory across sessions with claude-mem
Session resume with `--continue` or `--resume` replays a transcript, and CLAUDE.md only holds what you type into it yourself. Neither one remembers what Claude actually found out while working. [claude-mem](https://github.com/thedotmack/claude-mem) fills that gap: a plugin that hooks into five points in Claude's lifecycle and captures decisions, bug fixes, and other observations into a local SQLite and vector store as you go.
A `SessionStart` hook then feeds the relevant slice of that history back in automatically at the start of your next session, no manual note-taking required. Install it from the plugin marketplace and restart Claude Code and it starts capturing immediately, no slash command needed to turn it on.
Once enough history has built up, the bundled `mem-search` skill lets you ask about your own project's past in plain language. Wrap anything sensitive in `<private>` tags to keep it out of storage. Everything runs locally by default, and signing in only adds an optional hosted memory tier on top.
Example:
```
/plugin marketplace add thedotmack/claude-mem
/plugin install claude-mem
```
Then, in a later session:
```
What did we decide about the retry policy in the payments service?
```
Reference: [claude-mem](https://github.com/thedotmack/claude-mem)
### Tip 5: Bridge Claude Code and Codex with a plugin
Claude Code and Codex CLI don't talk to each other by default, even when they sit on the same machine and repo. OpenAI's [codex-plugin-cc](https://github.com/openai/codex-plugin-cc) plugin adds that bridge: it delegates work to your local Codex CLI and reads the result back, using the same install and login you already have. `/codex:review` runs a normal Codex code review on your uncommitted changes or a branch diff, and `/codex:rescue` hands a stuck task, like a failing build or a flaky test, to a `codex:codex-rescue` subagent. Both support `--background`, so you can keep working in Claude Code while Codex runs, then check in with `/codex:status` and `/codex:result`. `/codex:transfer` goes the other direction: it turns your current Claude Code conversation into a Codex thread you can resume with `codex resume <session-id>`. Install it with `/plugin marketplace add openai/codex-plugin-cc` and `/plugin install codex@openai-codex`, then run `/codex:setup` to confirm Codex is installed and signed in. It needs Node.js 18.18 or later, plus a ChatGPT subscription or an OpenAI API key.
Example:
```
/codex:review --background
/codex:status
/codex:result
```
Reference: [codex-plugin-cc](https://github.com/openai/codex-plugin-cc)
### Tip 6: Browse docs with Context7
LLM training data goes stale, so Claude will often suggest APIs from a library's older major version, or invent methods that don't exist at all. [Context7](https://github.com/upstash/context7) fixes this by fetching current, version-specific docs and code examples straight from the source and dropping them into your prompt, instead of relying on what Claude memorized during training. Add it as an MCP server, then append "use context7" to a prompt whenever you're working against a library that ships fast or just had a breaking change. Under the hood it exposes two tools: `resolve-library-id` turns a name like "Next.js" into an exact Context7 library ID, and `query-docs` fetches the relevant docs for that ID and your question. A free API key from the Context7 dashboard raises your rate limit; the server also works anonymously with a lower cap.
Example:
```
claude mcp add --transport http context7 https://mcp.context7.com/mcp
```
Then in a prompt:
```
Create a Next.js middleware that checks a JWT cookie and redirects
unauthenticated users to /login. use context7
```
Reference: [Context7](https://github.com/upstash/context7)
## Prompt
### Tip 1: Have Claude interview you before building something big
For a feature with real design decisions in it, don't start by writing a spec yourself. Start with a one-line prompt and let Claude interview you using the `AskUserQuestion` tool instead. It surfaces edge cases, tradeoffs, and UX questions you haven't considered yet, then writes the result to `SPEC.md`. Start a brand new session to actually build the feature: that session gets a clean context focused entirely on implementation, with a written spec to work from instead of a long back-and-forth it would otherwise have to re-derive.
Example:
```
I want to build a rate limiter for our public API. Interview me in detail using the AskUserQuestion tool.
Ask about technical implementation, UI/UX, edge cases, concerns, and tradeoffs. Don't ask obvious questions, dig into the hard parts I might not have considered.
Keep interviewing until we've covered everything, then write a complete spec to SPEC.md.
```
Reference: [Best practices](https://code.claude.com/docs/en/best-practices)
### Tip 2: Write the code in one session, review it in another
A session that just wrote a piece of code is biased toward believing it's correct. Open a second session with a fresh context, hand it just the file or the diff, and ask it to review, and it will catch things the first session glossed over. The same split works for tests: have one session write tests first, then a different session write the code that has to pass them.
Example:
Session A: `Implement a rate limiter for our API endpoints`
Session B: `Review the rate limiter implementation in @src/middleware/rateLimiter.ts. Look for edge cases, race conditions, and consistency with our existing middleware. Don't fix anything, just report what you find.`
Reference: [Best practices](https://code.claude.com/docs/en/best-practices)
### Tip 3: Put your planning effort into plan mode, not into micromanaging
Shift+Tab cycles into plan mode. The idea is to pour your attention into getting the plan right so Claude can implement it in one pass, rather than course-correcting it turn by turn during implementation. A pattern worth stealing: have one Claude write the plan, then start a second Claude to review it the way a staff engineer would before you approve it. If something goes sideways mid-implementation, go back to plan mode and re-plan instead of trying to patch your way out live.
Example:
```
Plan a migration of our session storage from Redis to Postgres. Don't write any code yet.
```
Reference: [Power user tips](https://support.claude.com/en/articles/14554000-claude-code-power-user-tips)
### Tip 4: Move plans out of the 30-day cache and into your repo
Plan mode writes every plan to `~/.claude/plans` by default — a global folder outside your project that Claude Code's cleanup routine clears out after 30 days. That's fine for a plan you'll implement the same afternoon, but not for one you want to diff, revisit weeks later, or hand to a teammate. Set `plansDirectory` in `.claude/settings.json` to a repo-relative path, and plans land there instead, version-controlled right alongside the code they describe. If you want more structure than a flat folder of plan files — grouping by feature, tracking each one's state as work progresses — a tool like [kaji](https://github.com/onmyway133/kaji) builds that folder hierarchy for you and is designed around this same explore-plan-implement workflow.
Example:
```json
{
"plansDirectory": "./plans"
}
```
Reference: [Settings reference](https://code.claude.com/docs/en/settings-reference)
### Tip 5: Keep exploration out of the plan you're about to approve
Plan mode collapses two different jobs into one prompt if you're not careful: understanding the code and deciding what to change. Ask Claude to read and explain first, with no plan attached, then ask for the plan as a separate follow-up once you've both seen what's actually there. This catches wrong assumptions before they get baked into a plan you approve at a glance, and gives you a natural point to redirect if the exploration turns up something you didn't expect.
Not every task needs this split. If you could describe the diff in one sentence, like renaming a variable or adding a log line, skip plan mode and let Claude just do it. Reach for the split when you're unfamiliar with the code, the change touches multiple files, or you're genuinely unsure of the approach.
Example:
```
claude --permission-mode plan
```
```
Read src/auth and figure out how we handle sessions and login. Also check how we manage environment variables for secrets. Don't propose a plan yet, just tell me what you find.
```
Once you've confirmed the findings:
```
Now write a plan for adding Google OAuth: what files change, what the session flow looks like.
```
Reference: [Best practices](https://code.claude.com/docs/en/best-practices#explore-first-then-plan-then-code)
## Hooks
### Tip 1: Hook into specific moments in Claude's lifecycle
Hooks run your own logic deterministically at fixed points in a session: `SessionStart` when a session begins, `PreToolUse` and `PostToolUse` around every tool call, `PermissionRequest` when Claude is about to ask you for approval, `Stop` when a turn is about to end, and `PostCompact` right after context gets compressed. You don't need to write these by hand from scratch. Ask Claude directly and it will generate one for you, matcher and all.
Example:
```
Write a hook that runs eslint after every file edit
```
Reference: [Hooks](https://code.claude.com/docs/en/hooks)
### Tip 2: Auto-format on every edit with a PostToolUse hook
`PostToolUse` is the hook worth setting up first, since it catches formatting issues right after Claude writes or edits a file, before they ever reach CI. Match on the `Write` and `Edit` tools and run your formatter as a command. A failing formatter shouldn't block the edit itself, so a trailing `|| true` keeps the session moving even if formatting fails.
Example: `.claude/settings.json`
```json
{
"hooks": {
"PostToolUse": [
{
"matcher": "Write|Edit",
"hooks": [{ "type": "command", "command": "bun run format || true" }]
}
]
}
}
```
Reference: [Hooks](https://code.claude.com/docs/en/hooks)
### Tip 3: Use a Stop hook as a deterministic gate for unattended runs
For a long run you want to walk away from, a `Stop` hook is more reliable than asking Claude nicely to verify itself before finishing. It runs your check as a script and refuses to let the turn end until that check passes. Claude Code caps this at 8 consecutive blocks and then ends the turn anyway, so a broken check can't trap a session forever. This is the difference between "please run the tests before you finish" as a suggestion and a turn that mechanically cannot end while the tests are red.
Reference: [Hooks](https://code.claude.com/docs/en/hooks)
### Tip 4: Get worktree isolation on non-git version control
`--worktree` only works with git, but the isolation it buys you doesn't have to be git-specific. Define `WorktreeCreate` and `WorktreeRemove` hooks in `settings.json`, and Claude Code calls them to set up and tear down an isolated workspace on Mercurial, Perforce, or SVN the same way it would with a native git worktree. This is the only way to get parallel, non-interfering sessions if your team isn't on git, and it's a small amount of hook code for a real workflow unlock.
Reference: [Hooks](https://code.claude.com/docs/en/hooks)
### Tip 5: Turn hooks into ambient audio cues
Hooks don't have to check things — they can just make noise. Wire a `Stop` hook to play a short sound file and you get an audible signal the moment Claude finishes a turn, so you can tab away to another window instead of watching the terminal for a response to land. Add `SessionStart` for a "session begins" chime, or `PreCompact` as a heads-up that your context is about to get rewritten. The part that actually matters: append `&` to the player command so it runs in the background — without it, the sound blocks the hook and delays whatever Claude does next. On macOS, `afplay` needs no extra install; Linux has `paplay` or `aplay`, and Windows can shell out to a PowerShell media call. Stick to two or three events — a hook that fires on every tool call turns your terminal into noise, not a signal.
Example: `.claude/settings.json`
```json
{
"hooks": {
"Stop": [
{
"hooks": [{ "type": "command", "command": "afplay ~/.claude/sounds/done.mp3 &" }]
}
]
}
}
```
Reference: [Hooks](https://code.claude.com/docs/en/hooks)
## Workflow
### Tip 1: Treat CLAUDE.md as a file you keep improving, not a one-time README
CLAUDE.md isn't documentation, it's instructions: naming rules, test commands, style preferences, and mistakes Claude has made before. When Claude gets something wrong, fix the immediate problem, then ask it to update CLAUDE.md so the same mistake doesn't happen again. Boris Cherny calls this "Compounding Engineering": every caught mistake becomes prevention for every future session, and because the file is checked into git, one engineer's fix helps the whole team. If you've installed the GitHub Action, you can even trigger this straight from a PR comment.
Example:
```
@claude nit: use a string literal, not a ts enum. Add to CLAUDE.md to never use enums, always prefer literal unions.
```
Reference: [CLAUDE.md files](https://code.claude.com/docs/en/memory)
### Tip 2: Reserve "IMPORTANT" for the one rule Claude keeps missing
If Claude keeps skipping a specific instruction in CLAUDE.md, adding emphasis like "IMPORTANT" to that single line pulls it back into focus. The catch is that this only works if you use it sparingly: emphasize five lines and none of them stand out anymore. Save it for the rule that's actually getting ignored, not as your default way of writing every line in CLAUDE.md.
Example:
```
IMPORTANT: never commit directly to main, always open a PR.
```
Reference: [Best practices](https://code.claude.com/docs/en/best-practices)
### Tip 3: Let /doctor prune your CLAUDE.md for you
A CLAUDE.md file grows over time, and a bloated one is exactly what causes Claude to miss instructions buried in the noise. Run `/doctor` on a checked-in CLAUDE.md and Claude proposes cuts for anything it can already derive by reading the codebase, like standard language conventions or self-evident practices you didn't need to spell out. Treat the file like code: review it when something goes wrong, prune it on a schedule, and confirm a change actually shifted Claude's behavior instead of assuming it will.
Reference: [Best practices](https://code.claude.com/docs/en/best-practices)
### Tip 4: Give Claude a way to check its own work
This is the single most valuable habit on this whole list. Without a feedback loop, Claude assumes its output is correct and stops there. With one, it iterates until the output actually is correct. What that loop looks like depends on the domain: a screenshot compared against a spec for web work, a simulator run for mobile, a test suite for a backend. Boris Cherny estimates this alone is worth a 2-3x improvement in output quality. Before starting anything nontrivial, ask what "done and correct" looks like, and make sure Claude has a way to check it, not just a way to claim it.
Example:
```
Implement the checkout flow, then take a screenshot of the final state and compare it against @designs/checkout.png before telling me it's done.
```
Reference: [Best practices](https://code.claude.com/docs/en/best-practices)
### Tip 5: Run risky, unsupervised work in a container
A session running with `--dangerously-skip-permissions` shouldn't run on your host machine, because if something goes wrong there's nothing containing the damage. Move that session into a container instead, and a bad outcome stays inside the container. This is the right setup for long research tasks, or for something like patching a minified CLI bundle after an upgrade: Claude can explore, apply a patch, notice it didn't work, and iterate, all without you approving each step, because the blast radius is contained by the environment rather than by your attention.
Reference: [Permission modes](https://code.claude.com/docs/en/permission-modes)
## Context
### Tip 1: Manage context deliberately instead of just filling it up
Every message you send gets the full conversation pasted back into the model from scratch. There's no memory between turns, only a transcript that grows and gets replayed in full each time. Whatever isn't in that transcript doesn't exist to the model, and whatever is in it competes for a fixed amount of attention.
That second part is why longer sessions quietly get worse. Attention is finite, so adding more tokens shrinks the share any single token gets. Anthropic calls the resulting quality drop "context rot", and it starts from the first token you add, not past some threshold. It's also why a rule sitting untouched in your CLAUDE.md can still get ignored forty turns in: the instruction never left the window, it just stopped getting enough attention to act on. And it's why a wrong assumption or a bad file read from ten messages back can quietly shape the next fifty, since the model has no way to un-see something once it's in context.
Piling on more rules doesn't fix this, since every added rule competes for the same limited attention. What helps is managing what actually stays in the window: send exploration to a subagent so its dead ends never enter your context, use `/rewind` to drop a failed attempt from the conversation without losing the code already on disk, run `/compact` yourself at a clean breakpoint instead of waiting for it to trigger mid-task, and `/clear` once a piece of work is genuinely done instead of dragging it into the next one. See [context engineering](tips/context-engineering.md) for how these compare and when to reach for each.
Prompt examples:
```
Spawn a subagent to find every place we call the legacy payment API. Report back only the call sites and their signatures, not the files you read to find them.
```
```
/rewind
```
Then pick "Restore conversation only" to drop the last few turns of a failed debugging attempt while keeping the code changes on disk, and tell Claude what you changed by hand.
Reference: [Effective context engineering for AI agents](https://www.anthropic.com/engineering/effective-context-engineering-for-ai-agents), [Checkpointing](https://code.claude.com/docs/en/checkpointing)
Connection Info
You Might Also Like
No recommendations available