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 以与你的团队共享
• 父目录：对于 monorepos 有用，其中 root/CLAUDE.md 和 root/foo/CLAUDE.md 都会自动拉入
• 子目录：当处理这些目录中的文件时，Claude 按需拉入子 CLAUDE.md 文件

​

配置权限

• Auto mode：一个单独的分类器模型审查命令并仅阻止看起来有风险的东西：范围升级、未知基础设施或由敌对内容驱动的操作。最适合当你信任任务的总体方向但不想点击通过每一步时
• 权限允许列表：允许你知道是安全的特定工具，如 npm run lint 或 git commit
• 沙箱：启用操作系统级隔离，限制文件系统和网络访问，允许 Claude 在定义的边界内更自由地工作

​

使用 CLI 工具

​

连接 MCP 服务器

​

设置 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。Context 被保留，所以你可以重定向。
• Esc + Esc 或 /rewind：按 Esc 两次或运行 /rewind 来打开 rewind 菜单并恢复之前的对话和代码状态，或从选定的消息进行总结。
• "撤销那个"：让 Claude 恢复其更改。
• /clear：在不相关的任务之间重置 context。长会话与无关的 context 可能会降低性能。

​

积极管理 context

• 在任务之间频繁使用 /clear 来完全重置 context window
• 当自动压缩触发时，Claude 总结最重要的东西，包括代码模式、文件状态和关键决策
• 为了更多控制，运行 /compact <instructions>，如 /compact Focus on the API changes
• 要仅压缩对话的一部分，使用 Esc + Esc 或 /rewind，选择消息检查点，并选择 从这里总结。这会压缩从该点开始的消息，同时保持早期 context 完整。
• 在 CLAUDE.md 中使用像 "When compacting, always preserve the full list of modified files and any test commands" 这样的指令来自定义压缩行为，以确保关键 context 在总结中存活
• 对于不需要留在 context 中的快速问题，使用 /btw。答案出现在可关闭的覆盖层中，永远不会进入对话历史，所以你可以检查细节而不增加 context。

​

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

​

自动化和扩展

​

运行非交互模式

# 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 Code 桌面应用：以视觉方式管理多个本地会话。每个会话获得自己的隔离 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

​

使用 auto mode 自主运行

claude --permission-mode auto -p "fix all lint errors"

​

避免常见失败模式

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

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

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

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

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

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

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

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

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

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

​

培养你的直觉

​

相关资源

• Claude Code 如何工作：代理循环、工具和 context 管理
• 扩展 Claude Code：skills、hooks、MCP、subagents 和 plugins
• 常见工作流：调试、测试、PR 等的分步配方
• CLAUDE.md：存储项目约定和持久 context