Claude Code 最佳实践

​

给 Claude 一种验证其工作的方式

​

先探索，再规划，最后编码

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

I want to add Google OAuth. What files need to change?
What's the session flow? Create a plan.

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

commit with a descriptive message and open a PR

​

在提示中提供具体的上下文

​

提供丰富的内容

• 使用 @ 引用文件，而不是描述代码的位置。Claude 在响应前读取文件。
• 直接粘贴图像。将图像复制/粘贴或拖放到提示中。
• 提供 URL 用于文档和 API 参考。使用 /permissions 将常用域名加入白名单。
• 管道数据，通过运行 cat error.log | claude 直接发送文件内容。
• 让 Claude 获取它需要的东西。告诉 Claude 使用 Bash 命令、MCP 工具或通过读取文件来自己拉取上下文。

​

配置你的环境

​

编写有效的 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

See @README.md for project overview and @package.json for available npm commands.

# Additional Instructions
- Git workflow: @docs/git-instructions.md
- Personal overrides: @~/.claude/my-project-instructions.md

• 主文件夹（~/.claude/CLAUDE.md）：适用于所有 Claude 会话
• 项目根目录（./CLAUDE.md）：检入 git 以与你的团队共享，或将其命名为 CLAUDE.local.md 并将其 .gitignore
• 父目录：对于 monorepos 很有用，其中 root/CLAUDE.md 和 root/foo/CLAUDE.md 都会自动拉入
• 子目录：当处理这些目录中的文件时，Claude 按需拉入子 CLAUDE.md 文件

​

配置权限

• 权限白名单：允许你知道是安全的特定工具（如 npm run lint 或 git commit）
• 沙箱：启用操作系统级隔离，限制文件系统和网络访问，允许 Claude 在定义的边界内更自由地工作

​

使用 CLI 工具

​

连接 MCP servers

​

设置 hooks

​

创建 skills

---
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/)

---
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

​

创建自定义 subagents

---
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.

​

安装 plugins

​

有效沟通

​

提出代码库问题

• 日志记录如何工作？
• 我如何创建新的 API 端点？
• foo.rs 第 134 行的 async move { ... } 是什么意思？
• CustomerOnboardingFlowImpl 处理哪些边界情况？
• 为什么这段代码在第 333 行调用 foo() 而不是 bar()？

​

让 Claude 采访你

I want to build [brief description]. 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.

​

管理你的会话

​

尽早且经常纠正方向

• Esc：使用 Esc 键停止 Claude 的中途操作。上下文被保留，所以你可以重定向。
• Esc + Esc 或 /rewind：按 Esc 两次或运行 /rewind 打开 rewind 菜单并恢复之前的对话和代码状态。
• "撤销那个"：让 Claude 恢复其更改。
• /clear：重置不相关任务之间的上下文。具有无关上下文的长会话可能会降低性能。

​

积极管理上下文

• 在任务之间频繁使用 /clear 以完全重置 context window
• 当自动压缩触发时，Claude 总结最重要的内容，包括代码模式、文件状态和关键决策
• 为了更好地控制，运行 /compact <instructions>，如 /compact Focus on the API changes
• 在 CLAUDE.md 中自定义压缩行为，使用像 "When compacting, always preserve the full list of modified files and any test commands" 这样的指令，以确保关键上下文在总结中幸存

​

使用 subagents 进行调查

Use subagents to investigate how our authentication system handles token
refresh, and whether we have any existing OAuth utilities I should reuse.

use a subagent to review this code for edge cases

​

使用检查点进行 Rewind

​

恢复对话

claude --continue    # Resume the most recent conversation
claude --resume      # Select from recent conversations

​

自动化和扩展

​

运行 headless 模式

# One-off queries
claude -p "Explain what this project does"

# Structured output for scripts
claude -p "List all API endpoints" --output-format json

# Streaming for real-time processing
claude -p "Analyze this log file" --output-format stream-json

​

运行多个 Claude 会话

• Claude Desktop：以视觉方式管理多个本地会话。每个会话都获得自己的隔离 worktree。
• 网络上的 Claude Code：在 Anthropic 的安全云基础设施中的隔离 VM 上运行。
• Agent teams：具有共享任务、消息和团队主管的多个会话的自动协调。

​

跨文件扇出

for file in $(cat files.txt); do
  claude -p "Migrate $file from React to Vue. Return OK or FAIL." \
    --allowedTools "Edit,Bash(git commit *)"
done

claude -p "<your prompt>" --output-format json | your_command

​

安全自主模式

​

避免常见的失败模式

• 厨房水槽会话。 你从一个任务开始，然后问 Claude 一些无关的东西，然后回到第一个任务。上下文充满了无关的信息。

  修复：在不相关的任务之间使用 /clear。

• 一次又一次地纠正。 Claude 做错了什么，你纠正它，它仍然是错的，你再次纠正。上下文被失败的方法污染。

  修复：在两次失败的纠正后，/clear 并写一个更好的初始提示，包含你学到的东西。

• 过度指定的 CLAUDE.md。 如果你的 CLAUDE.md 太长，Claude 会忽略一半，因为重要的规则在噪音中丢失。

  修复：无情地修剪。如果 Claude 已经在没有指令的情况下正确地做某事，删除它或将其转换为 hook。

• 信任然后验证的差距。 Claude 产生一个看起来合理的实现，但不处理边界情况。

  修复：始终提供验证（测试、脚本、屏幕截图）。如果你无法验证它，不要发布它。

• 无限探索。 你要求 Claude “调查”某些东西而不限定范围。Claude 读取数百个文件，填满上下文。

  修复：狭隘地限定调查范围或使用 subagents，以便探索不会消耗你的主上下文。

​

培养你的直觉

​

相关资源