Claude Code 最佳实践指南

On this page

Give Claude a way to verify its work

Explore first, then plan, then code

Provide specific context in your prompts Provide rich content

Configure your environment Write an effective CLAUDE.md

Communicate effectively Ask codebase questions

Let Claude interview you

Manage your session Course-correct early and often

Manage context aggressively

Use subagents for investigation

Rewind with checkpoints

Resume conversations

Automate and scale Run non-interactive mode

Run multiple Claude sessions

Fan out across files

Run autonomously with auto mode

Add an adversarial review step

Avoid common failure patterns

Develop your intuition

Related resources

Copy page Copy page Tips and patterns for getting the most out of Claude Code, from configuring your environment to scaling across parallel sessions.

Copy page Copy page Claude Code is an agentic coding environment. Unlike a chatbot that answers questions and waits, Claude Code can read your files, run commands, make changes, and autonomously work through problems while you watch, redirect, or step away entirely. This changes how you work. Instead of writing code yourself and asking Claude to review it, you describe what you want and Claude figures out how to build it. Claude explores, plans, and implements. But this autonomy still comes with a learning curve. Claude works within certain constraints you need to understand. This guide covers patterns that have proven effective across Anthropic’s internal teams and for engineers using Claude Code across various codebases, languages, and environments. For how the agentic loop works, see How Claude Code works .

Most best practices are based on one constraint: Claude’s context window fills up fast, and performance degrades as it fills. Claude’s context window holds your entire conversation, including every message, every file Claude reads, and every command output. However, this can fill up fast. A single debugging session or codebase exploration might generate and consume tens of thousands of tokens. This matters since LLM performance degrades as context fills. When the context window is getting full, Claude may start “forgetting” earlier instructions or making more mistakes. The context window is the most important resource to manage. To see how a session fills up in practice, watch an interactive walkthrough of what loads at startup and what each file read costs. Track context usage continuously with a custom status line , and see Reduce token usage for strategies on reducing token usage.

Give Claude a way to verify its work

Give Claude a check it can run: tests, a build, a screenshot to compare. It’s the difference between a session you watch and one you walk away from. Claude stops when the work looks done. Without a check it can run, “looks done” is the only signal available, and you become the verification loop: every mistake waits for you to notice it. Give Claude something that produces a pass or fail, and the loop closes on its own. Claude does the work, runs the check, reads the result, and iterates until the check passes. The check is anything that returns a signal Claude can read in the conversation: a test suite, a build exit code, a linter, a script that diffs output against a fixture, or a browser screenshot compared against a design. Run /verify yourself after Claude’s check passes to confirm the change against the running app. Strategy Before After Provide verification criteria ”implement a function that validates email addresses" "write a validateEmail function. example test cases: user@example.com is true, invalid is false, user@.com is false. run the tests after implementing” Verify UI changes visually ”make the dashboard look better" "[paste screenshot] implement this design. take a screenshot of the result and compare it to the original. list differences and fix them” Address root causes, not symptoms ”the build is failing" "the build fails with this error: [paste error]. fix it and verify the build succeeds. address the root cause, don’t suppress the error” Once the check exists, decide how hard it gates the stop:

In one prompt : ask Claude to run the check and iterate in the same message, as in the table above.

Across a session : set the check as a /goal condition . A separate evaluator re-checks it after every turn and Claude keeps working until the goal resolves. If Claude stalls, Claude Code eventually stops the run with the goal still set — see how /goal evaluation works .

As a deterministic gate : a Stop hook runs your check as a script and blocks the turn from ending until it passes. Stop input covers the cap on consecutive blocks.

By a second opinion : a verification subagent or a dynamic workflow that checks its own findings has a fresh model try to refute the result, so the agent doing the work isn’t the one grading it.

Explore first, then plan, then code

Separate research and planning from implementation to avoid solving the wrong problem. Letting Claude jump straight to coding can produce code that solves the wrong problem. Use plan mode to separate exploration from execution. The recommended workflow has four phases: 1 Explore

read /src/auth and understand how we handle sessions and login. also look at how we manage environment variables for secrets. 2 Plan

I want to add Google OAuth. What files need to change? What's the session flow? Create a plan. Press Ctrl+G to open the plan in your text editor for direct editing before Claude proceeds. 3 Implement

implement the OAuth flow from your plan. write tests for the callback handler, run the test suite and fix any failures. 4 Commit

commit with a descriptive message and open a PR

Plan mode is useful, but also adds overhead. For tasks where the scope is clear and the fix is small (like fixing a typo, adding a log line, or renaming a variable) ask Claude to do it directly. Planning is most useful when you’re uncertain about the approach, when the change modifies multiple files, or when you’re unfamiliar with the code being modified. If you could describe the diff in one sentence, skip the plan.

Provide specific context in your prompts

The more precise your instructions, the fewer corrections you’ll need. Claude can infer intent, but it can’t read your mind. Reference specific files, mention constraints, and point to example patterns. Strategy Before After Scope the task. Specify which file, what scenario, and testing preferences. ”add tests for foo.py" "write a test for foo.py covering the edge case where the user is logged out. avoid mocks.” Point to sources. Direct Claude to the source that can answer a question. ”why does ExecutionFactory have such a weird api?" "look through ExecutionFactory’s git history and summarize how its api came to be” Reference existing patterns. Point Claude to patterns in your codebase. ”add a calendar widget" "look at how existing widgets are implemented on the home page to understand the patterns. HotDogWidget.php is a good example. follow the pattern to implement a new calendar widget that lets the user select a month and paginate forwards/backwards to pick a year. build from scratch without libraries other than the ones already used in the codebase.” Describe the symptom. Provide the symptom, the likely location, and what “fixed” looks like. ”fix the login bug" "users report that login fails after session timeout. check the auth flow in src/auth/, especially token refresh. write a failing test that reproduces the issue, then fix it” Vague prompts can be useful when you’re exploring and can afford to course-correct. A prompt like "what would you improve in this file?" can surface things you wouldn’t have thought to ask about. Provide rich content

Use @ to reference files, paste screenshots/images, or pipe data directly. You can provide rich data to Claude in several ways:

Reference files with @ instead of describing where code lives. Claude reads the file before responding.

Paste images directly . Copy/paste or drag and drop images into the prompt.

Give URLs for documentation and API references. Use /permissions to allowlist frequently-used domains.

Pipe in data by running cat error.log | claude to send file contents directly.

Let Claude fetch what it needs . Tell Claude to pull context itself using Bash commands, MCP tools, or by reading files.

Configure your environment

Write an effective CLAUDE.md

Run /init to generate a starter CLAUDE.md file based on your current project structure, then refine over time. CLAUDE.md is a special file that Claude reads at the start of every conversation. Include Bash commands, code style, and workflow rules. This gives Claude persistent context it can’t infer from code alone. There’s no required format for CLAUDE.md files, but keep it short and human-readable. For example: CLAUDE.md # Code style - Use ES modules (import/export) syntax, not CommonJS (require) - Destructure imports when possible (eg. import { foo } from 'bar')

# Workflow - Be sure to typecheck when you're done making a series of code changes - Prefer running single tests, and not the whole test suite, for performance

Run /context to confirm Claude loaded the file. CLAUDE.md is loaded every session, so only include things that apply broadly. For domain knowledge or workflows that are only relevant sometimes, use skills instead. Claude loads them on demand without bloating every conversation. Keep it concise. For each line, ask: “Would removing this cause Claude to make mistakes?” If not, cut it. Bloated CLAUDE.md files cause Claude to ignore your actual instructions! ✅ Include ❌ Exclude Bash commands Claude can’t guess Anything Claude can figure out by reading code Code style rules that differ from defaults Standard language conventions Claude already knows Testing instructions and preferred test runners Detailed API documentation (link to docs instead) Repository etiquette (branch naming, PR conventions) Information that changes frequently Architectural decisions specific to your project Long explanations or tutorials Developer environment quirks (required env vars) File-by-file descriptions of the codebase Common gotchas or non-obvious behaviors Self-evident practices like “write clean code” If Claude keeps doing something you don’t want despite having a rule against it, the file is probably too long and the rule is getting lost. If Claude asks you questions that are answered in CLAUDE.md, the phrasing might be ambiguous. Treat CLAUDE.md like code: review it when things go wrong, prune it regularly, and test changes by observing whether Claude’s behavior actually shifts. For a checked-in CLAUDE.md, run /doctor and Claude proposes cuts for content it can derive from the codebase. If Claude keeps skipping one instruction, add emphasis such as “IMPORTANT” to that line alone. If you emphasize many lines, none of them stands out. Check CLAUDE.md into git so your team can contribute. The file compounds in value over time. CLAUDE.md files can import additional files using @path/to/import syntax. For import rules and where CLAUDE.md files can live, see CLAUDE.md files . Configure permissions

To get fewer prompts without giving up control, pre-approve the tools you trust with /permissions and let sandboxed commands run without asking with /sandbox . Switch to Manual mode when you want to approve edits and commands yourself. With Claude Code v2.1.283 or later, auto mode is the built-in starting permission mode for interactive terminal and VS Code sessions: a separate classifier model reviews most actions instead of you and blocks only what looks risky, such as scope escalation, unknown infrastructure, or hostile-content-driven actions. On earlier versions, auto mode is the built-in starting permission mode only on Pro, Max, and Team plans. In Manual mode, Claude Code asks before actions that might modify your system: file writes, Bash commands, MCP tools. That’s safe but tedious. After the tenth approval you’re clicking through rather than reviewing. Two tools cut those interruptions in Manual mode and apply in auto mode as well:

Permission allowlists : permit specific tools you know are safe, like npm run lint or git commit

Sandboxing : enable OS-level isolation that restricts filesystem and network access, allowing Claude to work more freely within defined boundaries

Use CLI tools

Tell Claude Code to use CLI tools like gh , aws , gcloud , and sentry-cli when interacting with external services. CLI tools are the most context-efficient way to interact with external services. If you use GitHub, install the gh CLI. Claude knows how to use it for creating issues, opening pull requests, and reading comments. Without gh , Claude can still use the GitHub API, but unauthenticated requests often hit rate limits. Claude is also effective at learning CLI tools it doesn’t already know. Try prompts like Use 'foo-cli-tool --help' to learn about foo tool, then use it to solve A, B, C. Connect MCP servers

Run claude mcp add with a server name and URL or command to connect external tools like Notion, Figma, or your database. For example: claude mcp add --transport http notion https://mcp.notion.com/mcp . With MCP servers , you can ask Claude to implement features from issue trackers, query databases, analyze monitoring data, integrate designs from Figma, and automate workflows. Set up hooks

Use hooks for actions that must happen every time with zero exceptions. Hooks run scripts automatically at specific points in Claude’s workflow. Unlike CLAUDE.md instructions which are advisory, hooks are deterministic and guarantee the action happens. Claude can write hooks for you. Try prompts like “Write a hook that runs eslint after every file edit” or “Write a hook that blocks writes to the migrations folder.” Edit .claude/settings.json directly to configure hooks by hand, and run /hooks to browse what’s configured. Create skills

Create SKILL.md files in .claude/skills/ to give Claude domain knowledge and reusable workflows. Skills extend Claude’s knowledge with information specific to your project, team, or domain. Claude applies them automatically when relevant, or you can invoke them directly with /skill-name . Create a skill by adding a directory with a SKILL.md to .claude/skills/ : .claude/skills/api-conventions/SKILL.md --- name : api-conventions description : REST API design conventions for our services --- # API Conventions - Use kebab-case for URL paths - Use camelCase for JSON properties - Always include pagination for list endpoints - Version APIs in the URL path (/v1/, /v2/)

Skills can also define repeatable workflows you invoke directly: .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. Understand the problem described in the issue 3. Search the codebase for relevant files 4. Implement the necessary changes to fix the issue 5. Write and run tests to verify the fix 6. Ensure code passes linting and type checking 7. Create a descriptive commit message 8. Push and create a PR

Run /fix-issue 1234 to invoke it. Use disable-model-invocation: true for workflows with side effects that you want to trigger manually. Create custom subagents

Define specialized assistants in .claude/agents/ that Claude can delegate to for isolated tasks. Subagents run in their own context with their own set of allowed tools. They’re useful for tasks that read many files or need specialized focus without cluttering your main conversation. .claude/agents/security-reviewer.md --- name : security-reviewer description : Reviews code for security vulnerabilities tools : Read, Grep, Glob, Bash model : opus --- You are a senior security engineer. Review code for: - Injection vulnerabilities (SQL, XSS, command injection) - Authentication and authorization flaws - Secrets or credentials in code - Insecure data handling

Provide specific line references and suggested fixes.

Tell Claude to use subagents explicitly: “Use a subagent to review this code for security issues.” Install plugins

Run /plugin to browse the marketplace. Plugins add skills, tools, and integrations without configuration. Plugins bundle skills, hooks, subagents, and MCP servers into a single installable unit from the community and Anthropic. If you work with a typed language, install a code intelligence plugin to give Claude precise symbol navigation and automatic error detection after edits. For guidance on choosing between skills, subagents, hooks, and MCP, see Extend Claude Code .

Communicate effectively

Ask codebase questions

Ask Claude questions you’d ask a senior engineer. When onboarding to a new codebase, use Claude Code for learning and exploration. You can ask Claude the same sorts of questions you would ask another engineer:

How does logging work?

How do I make a new API endpoint?

What does async move { ... } do on line 134 of foo.rs ?

What edge cases does CustomerOnboardingFlowImpl handle?

Why does this code call foo() instead of bar() on line 333?

Let Claude interview you