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 也可以定义你直接调用的可重复工作流： 

.claude/skills/fix-issue/SKILL.md

报告错误代码

复制

询问AI

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

 运行 /fix-issue 1234 来调用它。对于具有你想手动触发的副作用的工作流，使用 disable-model-invocation: true。 

### 

[​](https://code.claude.com/docs/zh-CN/best-practices#创建自定义-subagents)

创建自定义 subagents



在 .claude/agents/ 中定义专门的助手，Claude 可以委托给它们进行隔离的任务。

 [Subagents](https://code.claude.com/docs/zh-CN/sub-agents) 在自己的上下文中运行，拥有自己的一组允许的工具。它们对于读取许多文件或需要专门关注而不会使主对话变得混乱的任务很有用。 

.claude/agents/security-reviewer.md

报告错误代码

复制

询问AI

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.


 明确告诉 Claude 使用 subagents：“使用 subagent 审查此代码以查找安全问题。“ 

### 

[​](https://code.claude.com/docs/zh-CN/best-practices#安装-plugins)

安装 plugins



运行 /plugin 浏览市场。Plugins 添加 skills、工具和集成，无需配置。

 [Plugins](https://code.claude.com/docs/zh-CN/plugins) 将 skills、hooks、subagents 和 MCP servers 捆绑到来自社区和 Anthropic 的单个可安装单元中。如果你使用类型化语言，安装 [代码智能 plugin](https://code.claude.com/docs/zh-CN/discover-plugins#code-intelligence) 为 Claude 提供精确的符号导航和编辑后的自动错误检测。 有关在 skills、subagents、hooks 和 MCP 之间选择的指导，请参阅 [扩展 Claude Code](https://code.claude.com/docs/zh-CN/features-overview#match-features-to-your-goal)。  

## 

[​](https://code.claude.com/docs/zh-CN/best-practices#有效沟通)

有效沟通

 你与 Claude Code 沟通的方式会显著影响结果的质量。 

### 

[​](https://code.claude.com/docs/zh-CN/best-practices#提出代码库问题)

提出代码库问题



问 Claude 你会问资深工程师的问题。

 当加入新代码库时，使用 Claude Code 进行学习和探索。你可以问 Claude 你会问另一位工程师的相同类型的问题：  
- 日志记录如何工作？


- 我如何创建新的 API 端点？


- foo.rs 第 134 行的 async move { ... } 是什么意思？


- CustomerOnboardingFlowImpl 处理哪些边界情况？


- 为什么这段代码在第 333 行调用 foo() 而不是 bar()？

  以这种方式使用 Claude Code 是一个有效的入职工作流，改进了入职时间并减少了对其他工程师的负担。无需特殊提示：直接提问。 

### 

[​](https://code.claude.com/docs/zh-CN/best-practices#让-claude-采访你)

让 Claude 采访你



对于较大的功能，让 Claude 先采访你。从最小的提示开始，并要求 Claude 使用 AskUserQuestion 工具采访你。

 Claude 会询问你可能还没有考虑过的事情，包括技术实现、UI/UX、边界情况和权衡。 

报告错误代码

复制

询问AI

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. Dont ask obvious questions, dig into the hard parts I might not have considered.

Keep interviewing until weve covered everything, then write a complete spec to SPEC.md.


 规范完成后，启动一个新会话来执行它。新会话有干净的上下文，完全专注于实现，你有一个书面规范可以参考。  

## 

[​](https://code.claude.com/docs/zh-CN/best-practices#管理你的会话)

管理你的会话

 对话是持久的和可逆的。利用这一点！ 

### 

[​](https://code.claude.com/docs/zh-CN/best-practices#尽早且经常纠正方向)

尽早且经常纠正方向



一旦你注意到 Claude 偏离轨道，立即纠正它。

 最好的结果来自紧密的反馈循环。虽然 Claude 有时会在第一次尝试时完美地解决问题，但快速纠正通常会更快地产生更好的解决方案。  
- Esc：使用 Esc 键停止 Claude 的中途操作。上下文被保留，所以你可以重定向。


- Esc + Esc 或 /rewind：按 Esc 两次或运行 /rewind 打开 rewind 菜单并恢复之前的对话和代码状态。


- 撤销那个：让 Claude 恢复其更改。


- /clear：重置不相关任务之间的上下文。具有无关上下文的长会话可能会降低性能。

  如果你在一个会话中对同一问题纠正了 Claude 两次以上，上下文会被失败的方法污染。运行 /clear 并使用更具体的提示重新开始，该提示包含你学到的东西。具有更好提示的干净会话几乎总是优于具有累积更正的长会话。 

### 

[​](https://code.claude.com/docs/zh-CN/best-practices#积极管理上下文)

积极管理上下文



在不相关的任务之间频繁运行 /clear 以重置上下文。

 当你接近上下文限制时，Claude Code 会自动压缩对话历史，这保留了重要的代码和决策，同时释放空间。 在长会话中，Claude 的 context window 可能会被无关的对话、文件内容和命令填满。这可能会降低性能，有时会分散 Claude 的注意力。  
- 在任务之间频繁使用 /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 这样的指令，以确保关键上下文在总结中幸存



### 

[​](https://code.claude.com/docs/zh-CN/best-practices#使用-subagents-进行调查)

使用 subagents 进行调查



使用 use subagents to investigate X 委托研究。它们在单独的上下文中探索，为实现保持你的主对话干净。

 由于上下文是你的基本约束，subagents 是最强大的可用工具之一。当 Claude 研究代码库时，它读取许多文件，所有这些都会消耗你的上下文。Subagents 在单独的 context windows 中运行并报告摘要： 

报告错误代码

复制

询问AI

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


 subagent 探索代码库、读取相关文件并报告发现，所有这些都不会使你的主对话变得混乱。 你也可以在 Claude 实现某些东西后使用 subagents 进行验证： 

报告错误代码

复制

询问AI

use a subagent to review this code for edge cases




### 

[​](https://code.claude.com/docs/zh-CN/best-practices#使用检查点进行-rewind)

使用检查点进行 Rewind



Claude 进行的每个操作都会创建一个检查点。你可以将对话、代码或两者恢复到任何之前的检查点。

 Claude 在更改前自动创建检查点。双击 Escape 或运行 /rewind 打开检查点菜单。你可以仅恢复对话（保留代码更改）、仅恢复代码（保留对话）或恢复两者。 与其仔细规划每一步，不如告诉 Claude 尝试一些冒险的事情。如果不起作用，rewind 并尝试不同的方法。检查点在会话中持续，所以你可以关闭终端并稍后仍然 rewind。 

检查点仅跟踪 Claude 进行的更改，不跟踪外部进程。这不是 git 的替代品。



### 

[​](https://code.claude.com/docs/zh-CN/best-practices#恢复对话)

恢复对话



运行 claude --continue 从你离开的地方继续，或 --resume 从最近的会话中选择。

 Claude Code 在本地保存对话。当任务跨越多个会话时（你开始一个功能，被中断，第二天回来），你不必重新解释上下文： 

报告错误代码

复制

询问AI

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


 使用 /rename 给会话起描述性名称（oauth-migration、debugging-memory-leak），以便你稍后可以找到它们。像对待分支一样对待会话。不同的工作流可以有单独的、持久的上下文。  

## 

[​](https://code.claude.com/docs/zh-CN/best-practices#自动化和扩展)

自动化和扩展

 一旦你对一个 Claude 有效，通过并行会话、headless 模式和扇出模式来增加你的输出。 到目前为止，一切都假设一个人、一个 Claude 和一个对话。但 Claude Code 可以水平扩展。本部分中的技术展示了你如何完成更多工作。 

### 

[​](https://code.claude.com/docs/zh-CN/best-practices#运行-headless-模式)

运行 headless 模式



在 CI、pre-commit hooks 或脚本中使用 claude -p prompt。添加 --output-format stream-json 用于流式 JSON 输出。

 使用 claude -p your prompt，你可以无头运行 Claude，无需交互式会话。Headless 模式是你将 Claude 集成到 CI 管道、pre-commit hooks 或任何自动化工作流中的方式。输出格式（纯文本、JSON、流式 JSON）让你以编程方式解析结果。 

报告错误代码

复制

询问AI

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




### 

[​](https://code.claude.com/docs/zh-CN/best-practices#运行多个-claude-会话)

运行多个 Claude 会话



并行运行多个 Claude 会话以加快开发、运行隔离的实验或启动复杂的工作流。

 有三种主要方式来运行并行会话：  
- [Claude Desktop](https://code.claude.com/docs/zh-CN/desktop)：以视觉方式管理多个本地会话。每个会话都获得自己的隔离 worktree。


- [网络上的 Claude Code](https://code.claude.com/docs/zh-CN/claude-code-on-the-web)：在 Anthropic 的安全云基础设施中的隔离 VM 上运行。


- [Agent teams](https://code.claude.com/docs/zh-CN/agent-teams)：具有共享任务、消息和团队主管的多个会话的自动协调。

  除了并行化工作外，多个会话还支持质量聚焦的工作流。新鲜的上下文改进代码审查，因为 Claude 不会偏向于它刚刚编写的代码。 例如，使用 Writer/Reviewer 模式： 

会话 A（Writer）会话 B（Reviewer）为我们的 API 端点实现速率限制器审查 @src/middleware/rateLimiter.ts 中的速率限制器实现。查找边界情况、竞态条件和与我们现有中间件模式的一致性。这是审查反馈：[会话 B 输出]。解决这些问题。

 你可以对测试做类似的事情：让一个 Claude 编写测试，然后另一个编写代码来通过它们。 

### 

[​](https://code.claude.com/docs/zh-CN/best-practices#跨文件扇出)

跨文件扇出



循环遍历任务，为每个任务调用 claude -p。使用 --allowedTools 限定批量操作的权限。

 对于大型迁移或分析，你可以在许多并行 Claude 调用中分配工作： 

1

生成任务列表

让 Claude 列出所有需要迁移的文件（例如，list all 2,000 Python files that need migrating）

2

编写脚本来循环遍历列表

报告错误代码

复制

询问AI

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


3

在几个文件上测试，然后大规模运行

根据前 2-3 个文件出错的情况改进你的提示，然后在完整集合上运行。--allowedTools 标志限制 Claude 可以做什么，这在你无人值守运行时很重要。

 你也可以将 Claude 集成到现有的数据/处理管道中： 

报告错误代码

复制

询问AI

claude -p your prompt --output-format json | your_command

```

在开发期间使用 --verbose 进行调试，在生产中关闭它。

​

安全自主模式

使用 claude --dangerously-skip-permissions 绕过所有权限检查并让 Claude 不间断地工作。这对于修复 lint 错误或生成样板代码等工作流很有效。

让 Claude 运行任意命令是有风险的，可能导致数据丢失、系统损坏或数据泄露（例如，通过提示注入攻击）。为了最小化这些风险，在没有互联网访问的容器中使用 --dangerously-skip-permissions。启用沙箱（/sandbox）后，你会获得类似的自主权，但安全性更好。沙箱预先定义边界，而不是绕过所有检查。

​

避免常见的失败模式

这些是常见的错误。尽早识别它们可以节省时间：
- 厨房水槽会话。 你从一个任务开始，然后问 Claude 一些无关的东西，然后回到第一个任务。上下文充满了无关的信息。 修复：在不相关的任务之间使用 /clear。

  • 一次又一次地纠正。 Claude 做错了什么，你纠正它，它仍然是错的，你再次纠正。上下文被失败的方法污染。 修复：在两次失败的纠正后，/clear 并写一个更好的初始提示，包含你学到的东西。

  • 过度指定的 CLAUDE.md。 如果你的 CLAUDE.md 太长，Claude 会忽略一半，因为重要的规则在噪音中丢失。 修复：无情地修剪。如果 Claude 已经在没有指令的情况下正确地做某事，删除它或将其转换为 hook。

  • 信任然后验证的差距。 Claude 产生一个看起来合理的实现，但不处理边界情况。 修复：始终提供验证（测试、脚本、屏幕截图）。如果你无法验证它，不要发布它。

  • 无限探索。 你要求 Claude “调查”某些东西而不限定范围。Claude 读取数百个文件，填满上下文。 修复：狭隘地限定调查范围或使用 subagents，以便探索不会消耗你的主上下文。

​

培养你的直觉

本指南中的模式不是一成不变的。它们是通常效果很好的起点，但可能不是每种情况的最优选择。 有时你_应该_让上下文累积，因为你深入一个复杂的问题，历史很有价值。有时你应该跳过规划，让 Claude 弄清楚，因为任务是探索性的。有时模糊的提示正是你想要的，因为你想看看 Claude 如何解释问题，然后再限制它。 注意什么有效。当 Claude 产生很好的输出时，注意你做了什么：提示结构、你提供的上下文、你所在的模式。当 Claude 遇到困难时，问为什么。上下文太嘈杂了吗？提示太模糊了吗？任务对于一次通过来说太大了吗？ 随着时间的推移，你会培养任何指南都无法捕捉的直觉。你会知道何时具体以及何时开放，何时规划以及何时探索，何时清除上下文以及何时让它累积。

​

相关资源

Claude Code 如何工作理解代理循环、工具和上下文管理扩展 Claude Code在 skills、hooks、MCP、subagents 和 plugins 之间选择常见工作流调试、测试、PR 等的分步配方CLAUDE.md存储项目约定和持久上下文

此页面对您有帮助吗？

是否

常见工作流程Claude Code on the web

⌘I

Claude Code Docs home page

xlinkedin

Company

AnthropicCareersEconomic FuturesResearchNewsTrust centerTransparency

Help and security

AvailabilityStatusSupport center

Learn

CoursesMCP connectorsCustomer storiesEngineering blogEventsPowered by ClaudeService partnersStartups program

Terms and policies

Privacy policyDisclosure policyUsage policyCommercial termsConsumer terms