Claude Code Docs

基本命令

命令	功能	示例
claude	启动交互模式	claude
claude "task"	运行一次性任务	claude "fix the build error"
claude -p "query"	运行一次性查询，然后退出	claude -p "explain this function"
claude -c	在当前目录中继续最近的对话	claude -c
claude -r	恢复之前的对话	claude -r
/clear	清除对话历史	/clear
/help	显示可用命令	/help
exit 或 Ctrl+D	退出 Claude Code	exit

• 对您的请求要具体
• 使用分步说明
• 让 Claude 先探索
• 使用快捷方式节省时间

Claude Code 如何工作

收集上下文 、采取行动 和验证结果

代理循环由两个组件驱动：模型进行推理和工具采取行动

Claude Code 充当 Claude 周围的代理框架：它提供工具、上下文管理和执行环境，将语言模型转变为能够进行编码的代理。

模型: Claude

Sonnet 可以很好地处理大多数编码任务。Opus 为复杂的架构决策提供更强的推理能力

/model 切换或使用 claude --model <name> 启动

工具

工具是使 Claude Code 成为代理的原因。

没有工具，Claude 只能用文本回应。有了工具，Claude 可以采取行动

每个工具使用都会返回信息，反馈到循环中，告知 Claude 的下一个决定。

类别	Claude 可以做什么
文件操作	读取文件、编辑代码、创建新文件、重命名和重新组织
搜索	按模式查找文件、使用正则表达式搜索内容、探索代码库
执行	运行 shell 命令、启动服务器、运行测试、使用 git
网络	搜索网络、获取文档、查找错误消息
代码智能	编辑后查看类型错误和警告、跳转到定义、查找引用（需要代码智能插件）

内置工具是基础。使用 skills 扩展 Claude 知道的内容、使用 MCP 连接到外部服务、使用 hooks 自动化工作流，以及将任务卸载给 subagents。

• **CLAUDE.md。**存储项目特定的说明、约定和 Claude 应该在每个会话中了解的上下文。
• MEMORY.md 的前 200 行或 25KB（以先到者为准）在每个会话开始时加载。
• 您配置的扩展。 用于外部服务的 MCP servers、用于工作流的 skills、用于委派工作的 subagents 和用于浏览器交互的 Claude in Chrome。

执行环境

环境	代码运行位置	用例
本地	您的机器	默认。完全访问您的文件、工具和环境
云	Anthropic 管理的虚拟机	卸载任务、处理您本地没有的仓库
远程控制	您的机器，从浏览器控制	使用网络 UI 同时保持一切本地

界面

终端、桌面应用、IDE 扩展、claude.ai/code、远程控制、Slack 和 CI/CD 管道

使用会话

对话保存在本地。每条消息、工具使用和结果都被写入 ~/.claude/projects/ 下的纯文本 JSONL 文件

会话是独立的。 每个新会话都以新的上下文窗口开始，没有来自以前会话的对话历史。Claude 可以使用自动内存跨会话保持学习，

跨分支工作

每个 Claude Code 对话都是一个与您当前目录相关的会话

恢复或分叉会话

使用 claude --continue 或 claude --resume 恢复会话会在相同的会话 ID 下重新打开它，并将新消息附加到现有对话。使用 --fork-session 或 /branch 分叉会将历史复制到新的会话 ID 中，保持原始会话不变

上下文窗口

Claude 的上下文窗口保存您的对话历史、文件内容、命令输出、CLAUDE.md、自动内存、加载的 skills 和系统说明。

Claude 自动压缩，但对话早期的说明可能会丢失。将持久规则放在 CLAUDE.md 中，并运行 /context 以查看什么在占用空间。

当上下文填满时:清除较旧的工具输出，然后在需要时总结对话。对话早期的详细说明可能会丢失。将持久规则放在 CLAUDE.md 中，而不是依赖对话历史。

控制在压缩期间保留的内容，在 CLAUDE.md 中添加"Compact Instructions"部分或使用焦点运行 /compact（如 /compact focus on the API changes）。

MCP 工具定义默认被延迟，并通过工具搜索按需加载，因此只有工具名称消耗上下文，直到 Claude 使用特定工具。

使用 skills 和 subagents 管理上下文

Skills 按需加载。Claude 在会话开始时看到 skill 描述，但完整内容仅在使用 skill 时加载。

手动调用的 skills，设置 disable-model-invocation: true 以将描述保留在上下文之外，直到您需要它们。
Subagents 获得自己的新上下文，完全独立于您的主对话。完成后，他们返回一个摘要。

使用检查点和权限保持安全

• 检查点让您撤销文件更改
  • 每个文件编辑都是可逆的。 按两次 Esc 以回退到之前的状态，或要求 Claude 撤销。
• 权限控制 Claude 可以在不询问的情况下做什么。
  • 检查点是会话本地的，独立于 git。

控制 Claude 可以做什么

按 Shift+Tab 循环通过权限模式：

• 默认：Claude 在文件编辑和 shell 命令之前询问
• 自动接受编辑 ：Claude 编辑文件并运行常见的文件系统命令（如 mkdir 和 mv）而不询问，仍然询问其他命令
• Plan Mode：Claude 仅使用只读工具，创建您可以在执行前批准的计划
• 自动模式：Claude 使用后台安全检查评估所有操作。目前是研究预览

.claude/settings.json 中允许特定命令，以便 Claude 不会每次都询问。

有效使用 Claude Code

向 Claude Code 寻求帮助

• Claude Code 可以教您如何使用它。提出问题.
  • /init 引导您为项目创建 CLAUDE.md
  • /agents 帮助您配置自定义 subagents
  • /doctor 诊断您的安装的常见问题
• 您不需要完美的提示。从您想要的开始，然后细化：

中断和引导：任何时刻重定向 Claude，无需等待轮次完成或重新开始

• 按 Esc 立即停止 Claude。正在运行的工具调用被取消，Claude 等待您的下一条指令。
• 输入更正并按 Enter 在不停止正在运行的工具的情况下发送。Claude 在当前操作完成后立即读取它，并在决定下一步之前进行调整。
• 预先具体
  • 您的初始提示越精确，您需要的更正就越少。
    • 参考特定文件、提及约束并指出示例模式。

给 Claude 一些东西来验证

• Claude 在能够检查自己的工作时表现更好。包括测试用例、粘贴预期 UI 的屏幕截图或定义您想要的输出。
  *
  对于视觉工作，粘贴设计的屏幕截图并要求 Claude 将其实现与其进行比较。

在实现之前探索

• 对于复杂的问题，将研究与编码分开。使用 Plan Mode（按 Shift+Tab 两次）首先分析代码库：
• 审查计划，通过对话细化它，然后让 Claude 实现。这种两阶段方法比直接跳到代码产生更好的结果。

委派，不要指示

扩展 Claude Code

Claude Code 结合了一个能够推理代码的模型和内置工具，用于文件操作、搜索、执行和网络访问。

• 内置工具涵盖了大多数编码任务。
• 扩展添加功能
  • 自定义 Claude 的知识
  • 将其连接到外部服务
  • 自动化工作流。

扩展插入代理循环 agentic loop:的不同部分：

• CLAUDE.md 添加 Claude 每个会话都能看到的持久上下文
• Skills 添加可重用 的知识 和可调用的工作流
• 代码智能 将 Claude 连接到语言服务器，用于符号级导航和实时类型错误
• MCP 将 Claude 连接到外部服务和工具
• Subagents 在隔离的上下文中运行自己的循环，返回摘要
• Agent teams 协调多个独立会话，具有共享任务和点对点消息传递
• Hooks 在生命周期事件上触发，可以运行脚本、HTTP 请求、提示或 subagent
• Plugins 和 marketplaces 打包和分发这些功能

Skills 是最灵活的扩展。Skill 是一个包含知识、工作流或说明的 markdown 文件。

使用 /deploy 之类的命令调用 skills，或者 Claude 可以在相关时自动加载它们。

Skills 可以在您当前的对话中运行，也可以通过 subagents 在隔离的上下文中运行。

将功能与您的目标相匹配

功能	作用	何时使用	示例
CLAUDE.md	每次对话加载的持久上下文	项目约定、"始终执行 X" 规则	"使用 pnpm，而不是 npm。提交前运行测试。"
Skill	Claude 可以使用的说明、知识和工作流	可重用内容、参考文档、可重复的任务	/deploy 运行您的部署清单；包含端点模式的 API 文档 skill
Subagent	返回摘要结果的隔离执行上下文	上下文隔离、并行任务、专门的工作者	读取许多文件但仅返回关键发现的研究任务
Agent teams	协调多个独立的 Claude Code 会话	并行研究、新功能开发、使用竞争假设进行调试	生成审查者同时检查安全性、性能和测试
Code intelligence	语言服务器导航和诊断	类型化语言、大型代码库（其中 grep 速度慢或不精确）	跳转到符号的定义，而不是读取整个文件
MCP	连接到外部服务	外部数据或操作	查询您的数据库、发布到 Slack、控制浏览器
Hook	由事件触发的脚本、HTTP 请求、提示或 subagent	必须在每个匹配事件上运行的自动化	每次文件编辑后运行 ESLint

Plugins 是打包层。Plugin 将 skills、hooks、subagents 和 MCP servers 捆绑到单个可安装单元中。

Plugin skills 是命名空间的（如 /my-plugin:review），因此多个 plugins 可以共存。

当您想在多个存储库中重用相同的设置或通过 marketplace 分发给他人时，使用 plugins。

随时间推移构建您的设置

触发器	添加
Claude 两次出错约定或命令	将其添加到 CLAUDE.md
您一直在输入相同的提示来启动任务	将其保存为用户可调用的 skill
您第三次将相同的剧本或多步骤过程粘贴到聊天中	将其捕获为 skill
您一直在从 Claude 看不到的浏览器标签页复制数据	将该系统连接为 MCP server
Claude 读取许多文件以查找符号的定义或使用位置	为您的语言安装 code intelligence plugin
一个辅助任务用您不会再次引用的输出淹没您的对话	通过 subagent 路由它
您希望每次都发生某事而无需询问	编写 hook
第二个存储库需要相同的设置	将其打包为 plugin

重复的错误或反复出现的审查评论是 CLAUDE.md 编辑

一直手动调整的工作流是需要另一次修订的 skill。

比较相似的功能

Skills 和 subagents 解决不同的问题：

• Skills 是可重用的内容
• Subagents 是与主对话分开

方面	Skill	Subagent
它是什么	可重用的说明、知识或工作流	具有自己上下文的隔离工作者
关键优势	在上下文之间共享内容	上下文隔离。工作单独进行，仅返回摘要
上下文窗口影响	添加到您的主窗口	使用具有自己输入和输出令牌的单独窗口
最适合	参考材料、可调用的工作流	读取许多文件的任务、并行工作、专门的工作者

Skills 可以是参考或操作。

• 参考 skills 提供 Claude 在整个会话中使用的知识
• 操作 skills 告诉 Claude 执行特定操作（如运行您的部署工作流的 /deploy）。

当您需要上下文隔离或上下文窗口变满时，使用 subagent。

• Subagent 可能读取数十个文件或运行广泛的搜索，但您的主对话仅接收摘要。
• 定义 subagents 可以有自己的说明并可以预加载 skills。

它们可以结合。

• Subagent 可以预加载特定的 skills（skills: 字段）。
• Skill 可以使用 context: fork 在隔离的上下文中运行。有关详细信息，请参阅 Skills。

CLAUDE.md vs Skill

方面	CLAUDE.md	Skill
加载	每个会话，自动	按需
可以包含文件	是，使用 @path 导入	是，使用 @path 导入
可以触发工作流	否	是，使用 /<name>
最适合	"始终执行 X" 规则	参考材料、可调用的工作流

如果 Claude 应该始终知道它，请将其放在 CLAUDE.md 中：

• 编码约定、构建命令、项目结构、"永远不要执行 X" 规则。

如果它是 Claude 有时需要的参考材料（API 文档、风格指南）或您使用 /<name> 触发的工作流（部署、审查、发布），请将其放在 skill 中。

经验法则： 保持 CLAUDE.md 在 200 行以下。如果它在增长，将参考内容移到 skills 或拆分为 .claude/rules/ 文件。

CLAUDE.md vs Rules vs Skills

方面	CLAUDE.md	.claude/rules/	Skill
加载	每个会话	每个会话，或当打开匹配的文件时	按需，当调用或相关时
范围	整个项目	可以限定到文件路径	特定于任务
最适合	核心约定和构建命令	特定于语言或目录的指南	参考材料、可重复的工作流

对于每个会话需要的说明，使用 CLAUDE.md：

• 构建命令、测试约定、项目架构。

使用 rules 来保持 CLAUDE.md 专注。

• 带有 paths frontmatter 的 rules 仅在 Claude 处理匹配文件时加载，节省上下文。

对于 Claude 有时只需要的内容，使用 skills，

• 如 API 文档或您使用 /<name> 触发的部署清单。

Subagent vs Agent team

• Subagents 在您的会话内运行并将结果报告回您的主上下文
• Agent teams 是相互通信的独立 Claude Code 会话

方面	Subagent	Agent team
上下文	自己的上下文窗口；结果返回给调用者	自己的上下文窗口；完全独立
通信	仅向主代理报告结果	队友直接相互发送消息
协调	主代理管理所有工作	具有自我协调的共享任务列表
最适合	仅结果重要的专注任务	需要讨论和协作的复杂工作
令牌成本	较低：结果摘要返回到主上下文	较高：每个队友是一个单独的 Claude 实例

当您需要一个快速、专注的工作者时，使用 subagent：

• Subagent 完成工作并返回摘要。您的主对话保持清洁。

当队友需要共享发现、相互质疑和独立协调时，使用 agent team。Agent teams 是实验性的，默认禁用。

• Agent teams 最适合具有竞争假设的研究、并行代码审查以及每个队友拥有单独部分的新功能开发。

过渡点： 如果您运行并行 subagents 但遇到上下文限制，或者您的 subagents 需要相互通信，agent teams 是自然的下一步。

MCP vs Skill

MCP 将 Claude 连接到外部服务。Skills 扩展 Claude 的知识，包括如何有效地使用这些服务。

方面	MCP	Skill
它是什么	连接到外部服务的协议	知识、工作流和参考材料
提供	工具和数据访问	知识、工作流、参考材料
示例	Slack 集成、数据库查询、浏览器控制	代码审查清单、部署工作流、API 风格指南

• MCP 给予 Claude 与外部系统交互的目的构建的工具，连接和身份验证由服务器处理。
• Skills 给予 Claude 关于如何有效使用这些工具的知识，以及您可以使用 /<name> 触发的工作流。Skill 可能包括您团队的数据库架构和查询模式，或带有您团队消息格式规则的 /post-to-slack 工作流。

Hook vs Skill

Hook 在生命周期事件上触发；skill 被加载到上下文中供 Claude 应用。

方面	Hook	Skill
运行	Shell 命令、HTTP 请求、LLM 提示或 subagent	Claude 读取和遵循的说明
由以下触发	生命周期事件，如 PostToolUse 或 SessionStart	您输入 /<name>，或 Claude 将描述与您的任务相匹配
确定性	总是在其事件上触发；触发器是有保证的	Claude 解释说明；结果可能会有所不同
上下文成本	零，除非 hook 返回输出	描述在每个会话加载；使用时加载完整内容
最适合	每次都以相同方式运行且不需要 Claude 思考的操作	需要推理的工作流、参考材料、多步骤任务

• 当操作必须每次都以相同方式发生且不需要 Claude 思考时，使用 hook。
• 当 Claude 应该决定如何应用步骤或内容是知识而不是脚本时，使用 skill。
• 将护栏放在 hooks 中。 CLAUDE.md 或 skill 中的"永远不要编辑 .env"之类的说明是请求，而不是保证。阻止编辑的 PreToolUse hook 是强制执行。如果规则必须每次都成立，将其作为 hook 而不是提示说明。
• Hook 输出进入上下文。 运行您的 linter 的 PostToolUse hook 将结果作为 Claude 读取的文本反馈；/fix-lint skill 告诉 Claude 如何解决它们。

了解功能如何分层

功能可以在多个级别定义：用户范围、每个项目、通过 plugins 或通过托管策略。

可以在子目录中嵌套 CLAUDE.md 文件或在 monorepo 的特定包中放置 skills。

• CLAUDE.md 文件 是累加的：所有级别同时向 Claude 的上下文贡献内容。来自您的工作目录及以上的文件在启动时加载；子目录在您在其中工作时加载。当说明冲突时，Claude 使用判断来协调它们，更具体的说明通常优先。有关详细信息，请参阅 CLAUDE.md 文件如何加载。
• Skills 和 subagents 按名称覆盖：当相同的名称存在于多个级别时，一个定义根据优先级获胜（对于 skills 为托管 > 用户 > 项目；对于 subagents 为托管 > CLI 标志 > 项目 > 用户 > plugin）。Plugin skills 是 命名空间的 以避免冲突。有关详细信息，请参阅 skill 发现 和 subagent 范围。
• MCP 服务器 按名称覆盖：本地 > 项目 > 用户。有关详细信息，请参阅 MCP 范围。
• Hooks 合并：所有注册的 hooks 为其匹配的事件触发，无论来源如何。有关详细信息，请参阅 hooks。

组合功能

每个扩展解决不同的问题：

• CLAUDE.md 处理始终开启的上下文，
• skills 处理按需知识和工作流，
• MCP 处理外部连接，
• subagents 处理隔离，
• hooks 处理自动化。

真实的设置根据您的工作流组合它们。

模式	工作原理	示例
Skill + MCP	MCP 提供连接；skill 教导 Claude 如何很好地使用它	MCP 连接到您的数据库，skill 记录您的架构和查询模式
Skill + Subagent	Skill 为并行工作生成 subagents	/audit skill 启动在隔离上下文中工作的安全性、性能和风格 subagents
CLAUDE.md + Skills	CLAUDE.md 保存始终开启的规则；skills 保存按需加载的参考材料	CLAUDE.md 说"遵循我们的 API 约定"，skill 包含完整的 API 风格指南
Hook + MCP	Hook 通过 MCP 触发外部操作	编辑后 hook 在 Claude 修改关键文件时发送 Slack 通知

了解上下文成本

您添加的每个功能都会消耗 Claude 的一些上下文。太多可能会填满您的上下文窗口，但它也可能增加噪音，请参阅 探索上下文窗口。

按功能的上下文成本

功能	何时加载	加载内容	上下文成本
CLAUDE.md	会话开始	完整内容	每个请求
Skills	会话开始 + 使用时	启动时的描述，使用时的完整内容	低（每个请求的描述）*
MCP 服务器	会话开始	工具名称；完整架构按需	低，直到使用工具
Code intelligence	文件编辑后和按需	编辑后的诊断；符号查找时的位置信息	低；减少其他地方的文件读取
Subagents	生成时	具有指定 skills 的新鲜上下文	与主会话隔离
Hooks	触发时	无（外部运行）	零，除非 hook 返回额外上下文

*默认情况下，skill 描述在会话开始时加载，以便 Claude 可以决定何时使用它们。

在 skill 的 frontmatter 中设置 disable-model-invocation: true 以将其完全隐藏在 Claude 中，直到您手动调用它。

对于您未编写的 skill，在设置中设置 skillOverrides 以在不编辑其文件的情况下执行相同操作。

了解功能如何加载

• CLAUDE.md

  • 何时： 会话开始

  • 加载内容： 所有 CLAUDE.md 文件的完整内容（托管、用户和项目级别）。

  • 继承： Claude 从您的工作目录读取 CLAUDE.md 文件直到根目录，并在访问这些文件时发现子目录中的嵌套文件。有关详细信息，请参阅 CLAUDE.md 文件如何加载。

• Skills

  • Skills 是 Claude 工具包中的额外功能。它们可以是参考材料（如 API 风格指南）或可调用的工作流，您可以使用 /<name> 触发（如 /deploy）。

  • Claude Code 包括 捆绑的 skills，如 /code-review、/batch 和 /debug，可以开箱即用。

  • 何时： 取决于 skill 的配置。

    • 默认情况下，描述在会话开始时加载，完整内容在使用时加载。

    • 对于仅用户 skills（disable-model-invocation: true），在您调用它们之前不加载任何内容。

  • 加载内容： 对于模型可调用的 skills，Claude 在每个请求中看到名称和描述。

    • 当您使用 /<name> 调用 skill 或 Claude 自动加载它时，完整内容加载到您的对话中。

  • Claude 如何选择 skills： Claude 将您的任务与 skill 描述相匹配，以决定哪些相关。

    • 要告诉 Claude 使用特定的 skill，请使用 /<name> 调用它。带有 disable-model-invocation: true 的 Skills 对 Claude 不可见，直到您调用它们。

  • 上下文成本： 低，直到使用。仅用户 skills 在调用前成本为零。

  • 在 subagents 中： Skills 在 subagents 中的工作方式不同。不是按需加载，而是在 subagent 的 skills 字段中列出的 skills 在启动时完全预加载到其上下文中。Subagents 仍然可以通过 Skill 工具发现和调用未列出的项目、用户和插件 skills。

• MCP 服务器

  • 何时： 会话开始。
  • 加载内容： 来自连接的服务器的工具名称。完整的 JSON 架构保持延迟，直到 Claude 需要特定工具。
  • 上下文成本： 工具搜索默认启用，因此空闲 MCP 工具消耗最少的上下文。

• Code intelligence

  • 何时： 文件编辑后，以及当 Claude 导航代码时按需。

  • 加载内容： 每次文件编辑后的类型错误和警告。当 Claude 查找符号时的定义、引用和类型信息。

  • 上下文成本： 低。符号查找通常替代广泛的文件读取，因此净上下文使用可能会下降。

• Subagents

  • 何时： 按需，当您或 Claude 为任务生成一个时。

  • 加载内容： 新鲜、隔离的上下文，包含：

    • agent 的自己的系统提示，而不是完整的 Claude Code 系统提示
    • agent 的 skills: 字段中列出的 skills 的完整内容
    • CLAUDE.md 和 git 状态，除了内置的 Explore 和 Plan agents 省略两者
    • 主 agent 在提示中传递的任何上下文

  • 上下文成本： 与主会话隔离。Subagents 不继承您的对话历史或调用的 skills。

• Hooks

  • 何时： 触发时。Hooks 在特定的生命周期事件上触发，如工具执行、会话边界、提示提交、权限请求和压缩。有关完整列表，请参阅 Hooks。

  • 加载内容： 默认情况下无。Hooks 在主对话外执行。

  • 上下文成本： 零，除非 hook 返回作为消息添加到您的对话中的输出。

探索 .claude 目录

Claude Code 读取 CLAUDE.md、settings.json、hooks、skills、commands、subagents、workflows、rules 和自动内存的位置。

项目中的 .claude 目录团队共享；

~/.claude 中的文件是个人配置，适用于您的所有项目。

大多数用户只编辑 CLAUDE.md 和 settings.json。目录的其余部分是可选的：根据需要添加 skills、rules 或 subagents。

探索目录

• CLAUDE.md

  • Project instructions Claude reads every session

  • Put your conventions, common commands, and architectural context here

  • Target under 200 lines

  • specific tasks, move it to a skill or a path-scoped rule

  • List the commands you run most

  • Run /memory to open and edit CLAUDE.md

  • Also works at .claude/CLAUDE.md

    # Project conventions
    
    ## Commands
    - Build: `npm run build`
    - Test: `npm test`
    - Lint: `npm run lint`
    
    ## Stack
    - TypeScript with strict mode
    - React 19, functional components only
    
    ## Rules
    - Named exports, never default exports
    - Tests live next to source: `foo.ts` -> `foo.test.ts`
    - All API routes return `{ data, error }` shape

• .mcp.json

  • Project-scoped MCP servers

  • Configures Model Context Protocol (MCP) servers that give Claude access to external tools: databases, APIs, browsers, and more

  • Personal servers ~/.claude.json

  • Use environment variable

  • Lives at the project root

  • For servers only you need, run claude mcp add --scope user. This writes to ~/.claude.json instead of .mcp.json

    {
      "mcpServers": {
        "github": {
          "command": "npx",
          "args": ["-y", "@modelcontextprotocol/server-github"],
          "env": {
            "GITHUB_TOKEN": "${GITHUB_TOKEN}"
          }
        }
      }
    }

• .worktreeinclude

  • Gitignored files to copy into new worktreesgit worktree via --worktree

  • Lists gitignored files to copy from your main repository into each new worktree

  • untracked files like .env

  • Patterns here use .gitignore syntax

  • Comments start with # and blank lines are ignored, same as .gitignore.

    # Local environment
    .env
    .env.local
    
    # API credentials
    config/secrets.json

• .claude/

  • Project-level configuration, rules, and extensions
  • settings.json

    • Permissions, hooks, and configuration

    • Overrides global ~/.claude/settings.json. Local settings, CLI flags, and managed settings override this

    • CLAUDE.md, which Claude reads as guidance, these are enforced whether Claude follows them or not.

    • permissions: allow, deny, or prompt before Claude uses specific tools or commands

    • hooks: run your own scripts on events like before a tool call or after a file edit

    • statusLine: customize the line shown at the bottom while Claude works

    • model: pick a default model for this project

    • env: environment variables set in every session

    • ​​​​​​outputStyle: select a custom system-prompt style from output-styles/

    • Bash permission patterns support wildcards: Bash(npm test *) matches any command starting with npm test

    • Array settings like permissions.allow combine across all scopes; scalar settings like model use the most specific value

      {
        "permissions": {
          "allow": [
            "Bash(npm test *)",
            "Bash(npm run *)"
          ],
          "deny": [
            "Bash(rm -rf *)"
          ]
        },
        "hooks": {
          "PostToolUse": [{
            "matcher": "Edit|Write",
            "hooks": [{
              "type": "command",
              "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
            }]
          }]
        }
      }

• settings.local.json

  • personal settings overrides

  • adds this file to ~/.config/git/ignore
    *

      {
        "permissions": {
          "allow": [
            "Bash(docker *)"
          ]
        }
      }

  • Same schema as settings.json

• rules/

  • Rules without paths: load at session start.

  • Rules with paths: load when a matching file enters context

  • testing.md

    • Loaded when Claude reads a file matching the paths: globs below

      ---
      paths:
        - "**/*.test.ts"
        - "**/*.test.tsx"
      ---
      
      # Testing Rules
      
      - Use descriptive test names: "should [expected] when [condition]"
      - Mock external dependencies, not internal modules
      - Clean up side effects in afterEach

  • api-design.md

    ---
    paths:
      - "src/api/**/*.ts"
    ---
    
    # API Design Rules
    
    - All endpoints must validate input with Zod schemas
    - Return shape: { data: T } | { error: string }
    - Rate limit all public endpoints

• skills/

  • Use frontmatter to control that: disable-model-invocation: true for user-only workflows like /deploy,

  • user-invocable: false to hide from the / menu while Claude can still invoke it.

  • security-review/

    • SKILL.md

      • Entrypoint: trigger, invocability, instructions
      • User types /security-review <target>; Claude cannot auto-invoke this skill

        • The ``!`...``` line runs a shell command and injects its output into the prompt.

        • $ARGUMENTS substitutes whatever you typed after the skill name.

          ---
          description: Reviews code changes for security vulnerabilities, authentication gaps, and injection risks
          disable-model-invocation: true
          argument-hint: <branch-or-path>
          ---
          
          ## Diff to review
          
          !`git diff $ARGUMENTS`
          
          Audit the changes above for:
          
          1. Injection vulnerabilities (SQL, XSS, command)
          2. Authentication and authorization gaps
          3. Hardcoded secrets or credentials
          
          Use checklist.md in this skill directory for the full review checklist.
          
          Report findings with severity ratings and remediation steps.

    • checklist.md

    • Claude reads it on demand while running the skill

    • Skills can bundle any supporting files: reference docs, templates, scripts.

      # Security Review Checklist
      
      ## Input Validation
      - [ ] All user input sanitized before DB queries
      - [ ] File upload MIME types validated
      - [ ] Path traversal prevented on file operations
      
      ## Authentication
      - [ ] JWT tokens expire after 24 hours
      - [ ] API keys stored in environment variables
      - [ ] Passwords hashed with bcrypt or argon2

  • commands/

    • Single-file prompts invoked with /name

    • Use $ARGUMENTS in the file to accept parameters: /fix-issue 123

    • if a skill and command share a name, the skill takes precedence

    • New commands should usually be skills instead; commands remain supported

    • fix-issue.md

      • Invoked as /fix-issue <number>

        ---
        argument-hint: <issue-number>
        ---
        
        !`gh issue view $ARGUMENTS`
        
        Investigate and fix the issue above.
        
        1. Trace the bug to its root cause
        2. Implement the fix
        3. Write or update tests
        4. Summarize what you changed and why

    • output-styles/

      • ~/.claude/output-styles/

    • agents/

      • Specialized subagents with their own context window

      • subagent with its own system prompt,

      • code-reviewer.md

        ---
        name: code-reviewer
        description: Reviews code for correctness, security, and maintainability
        tools: Read, Grep, Glob
        ---
        
        You are a senior code reviewer. Review for:
        
        1. Correctness: logic errors, edge cases, null handling
        2. Security: injection, auth bypass, data exposure
        3. Maintainability: naming, complexity, duplication
        
        Every finding must include a concrete fix.

      • workflows/

        • Dynamic workflow scripts that orchestrate many subagents

    • <agent-name>/

      • MEMORY.md

        # code-reviewer memory
        
        ## Patterns seen
        - Project uses custom Result<T, E> type, not exceptions
        - Auth middleware expects Bearer token in Authorization header
        - Tests use factory functions in test/factories/
        
        ## Recurring issues
        - Missing null checks on API responses (src/api/*)
        - Unhandled promise rejections in background jobs

文件	位置	用途
managed-settings.json	系统级别，因操作系统而异	企业强制执行的设置，您无法覆盖。请参阅服务器管理的设置。
CLAUDE.local.md	项目根目录	您对此项目的私人偏好，与 CLAUDE.md 一起加载。手动创建它并将其添加到 .gitignore。
已安装的 plugins	~/.claude/plugins	克隆的市场、已安装的 plugin 版本和每个 plugin 的数据，由 claude plugin 命令管理。孤立版本在 plugin 更新或卸载后 7 天被删除。请参阅 plugin 缓存。

选择正确的文件

您想要	编辑	范围	参考
为 Claude 提供项目上下文和约定	CLAUDE.md	项目或全局	Memory
允许或阻止特定工具调用	settings.json permissions 或 hooks	项目或全局	Permissions、Hooks
在工具调用前后运行脚本	settings.json hooks	项目或全局	Hooks
为会话设置环境变量	settings.json env	项目或全局	Settings
将个人覆盖保留在 git 之外	settings.local.json	仅项目	Settings scopes
添加使用 /name 调用的提示或功能	skills/<name>/SKILL.md	项目或全局	Skills
定义具有自己工具的专门 subagent	agents/*.md	项目或全局	Subagents
通过脚本编排许多 subagent	workflows/*.js	项目或全局	Dynamic workflows
通过 MCP 连接外部工具	.mcp.json	仅项目	MCP
更改 Claude 格式化响应的方式	output-styles/*.md	项目或全局	Output styles

文件参考

文件	范围	提交	作用	参考
CLAUDE.md	项目和全局	✓	每个会话加载的指令	内存
rules/*.md	项目和全局	✓	主题范围的指令，可选择路径门控	Rules
settings.json	项目和全局	✓	权限、hooks、环境变量、模型默认值	设置
settings.local.json	仅项目		您的个人覆盖，自动 gitignored	设置范围
.mcp.json	仅项目	✓	团队共享的 MCP 服务器	MCP 范围
.worktreeinclude	仅项目	✓	Gitignored 文件以复制到新的 worktrees	Worktrees
skills/<name>/SKILL.md	项目和全局	✓	可重用的提示，使用 /name 调用或自动调用	Skills
commands/*.md	项目和全局	✓	单文件提示；与 skills 相同的机制	Skills
output-styles/*.md	项目和全局	✓	自定义系统提示部分	输出样式
agents/*.md	项目和全局	✓	Subagent 定义及其自己的提示和工具	Subagents
workflows/*.js	项目和全局	✓	由 Claude 编写并从 /workflows 保存的动态工作流脚本；每个文件都成为一个 /<name> 命令	动态工作流
agent-memory/<name>/	项目和全局	✓	Subagents 的持久内存	持久内存
~/.claude.json	仅全局		应用状态、OAuth、UI 切换、个人 MCP 服务器	全局配置
projects/<project>/memory/	仅全局		自动内存：Claude 在会话间对自己的笔记	自动内存
keybindings.json	仅全局		自定义快捷键	快捷键
themes/*.json	仅全局		自定义颜色主题	自定义主题

探索上下文窗口

时间线显示的内容

• 在您输入任何内容之前：CLAUDE.md、自动内存、MCP 工具名称和技能描述都加载到上下文中。
• 当 Claude 工作时：每个文件读取都会添加到上下文中
• 后续提示 ：子代理在其自己的单独上下文窗口中处理研究
• 最后 ：/compact用结构化摘要替换对话

压缩后保留的内容

机制	压缩后
系统提示和输出样式	不变；不是消息历史的一部分
项目根目录 CLAUDE.md 和无范围规则	从磁盘重新注入
自动内存	从磁盘重新注入
带有 paths: frontmatter 的规则	丢失，直到再次读取匹配的文件
子目录中的嵌套 CLAUDE.md	丢失，直到再次读取该子目录中的文件
调用的技能主体	重新注入，每个技能上限为 5,000 个令牌，总计 25,000 个令牌；最旧的首先删除
Hooks	不适用；hooks 作为代码运行，不是上下文

请将最重要的指令放在 SKILL.md 的顶部附近。

当您的上下文填满时

• 带有焦点的压缩 ：在开始长时间的新任务之前，运行带有指令的 /compact，例如 /compact focus on the auth bug fix。摘要保留您选择的内容，而不是自动传递猜测的重要内容。
• 在任务之间清除 ：切换到不相关的工作时运行 /clear。旧对话会挤出您接下来需要的文件，并在每条消息上花费令牌。
• 委托大型读取 ：将研究发送给子代理，以便文件内容保留在其上下文窗口中，而不是您的。

检查您自己的会话

/context 以获取按类别的实时分解和优化建议。运行 /memory 以检查在启动时加载了哪些 CLAUDE.md 和自动内存文件。

Claude Code 如何使用 prompt caching

Claude Code 自动管理 prompt caching。

缓存的组织方式

层	内容	更改时间
系统提示	核心指令、工具定义、输出样式	加载的工具定义集合更改，或 Claude Code 升级
项目上下文	CLAUDE.md、自动内存、无范围规则	会话开始，或在 /clear 或 /compact 之后
对话	您的消息、Claude 的响应、工具结果	每个回合

缓存位置

缓存发生在服务器端，在为您的模型提供服务的任何基础设施中。它的位置取决于您如何进行身份验证：

• API 密钥、Claude 订阅或 Claude Platform on AWS ：缓存位于 Anthropic 的基础设施中，通过 Claude API 访问
• Bedrock 或 Vertex AI：缓存位于您的云提供商的服务基础设施中
• Foundry：请求路由到 Anthropic 的基础设施
• 自定义 ANTHROPIC_BASE_URL 或 LLM gateway：缓存位于您的请求转发到的任何地方，缓存是否工作取决于网关

使缓存失效的操作

• 切换模型
  • /model
• 更改工作量级别
  • /effort
• 启用快速模式
  • 该请求头是缓存键的一部分，所以下一个请求读取整个对话历史记录而没有缓存命中。
• 连接或断开 MCP 服务器
  • 延迟工具，不会扰乱已缓存的任何内容。
  • 加载到前缀中的工具：对它们的任何更改都会使缓存失效
• 启用或禁用插件
  • Skills、commands、agents、hooks、LSP 服务器、monitors 和 themes 永远不会使缓存失效
• 拒绝整个工具
  • 像 Bash 或 WebFetch 这样的裸工具名称作为拒绝规则
• 压缩对话
  • 压缩用摘要替换您的消息历史记录。

保持缓存的操作

• 编辑存储库中的文件
• 在会话中期编辑 CLAUDE.md
• 更改输出样式
• 更改权限模式
• 调用技能和命令
• 运行 /recap
• 重绕对话
• 生成子代理

• 升级 Claude Code

Claude 如何记住你的项目

CLAUDE.md 文件为 Claude 提供持久指令，并让 Claude 通过自动记忆功能自动积累学习内容。

• CLAUDE.md 文件：你编写的指令，为 Claude 提供持久上下文
• 自动记忆：Claude 根据你的更正和偏好自己编写的笔记

CLAUDE.md 与自动记忆

的指令越具体和简洁，Claude 遵循它们的一致性就越高。

|----------|---------------|------------------------|
| 谁编写 | 你 | Claude |
| 包含内容 | 指令和规则 | 学习和模式 |
| 范围 | 项目、用户或组织 | 每个工作树，跨 worktrees 共享 |
| 加载到 | 每个会话 | 每个会话（前 200 行或 25KB） |
| 用于 | 编码标准、工作流、项目架构 | 构建命令、调试见解、Claude 发现的偏好 |

CLAUDE.md 文件

• Claude 第二次犯同样的错误
• 代码审查发现 Claude 应该了解这个代码库的内容
• 你在聊天中输入的相同更正或澄清是你上个会话输入的
• 新队友需要相同的上下文才能提高生产力

选择 CLAUDE.md 文件的位置

范围	位置	目的	用例示例	共享对象
托管策略	• macOS: /Library/Application Support/ClaudeCode/CLAUDE.md • Linux 和 WSL: /etc/claude-code/CLAUDE.md • Windows: C:\Program Files\ClaudeCode\CLAUDE.md	由 IT/DevOps 管理的组织范围指令	公司编码标准、安全策略、合规要求	组织中的所有用户
用户指令	~/.claude/CLAUDE.md	所有项目的个人偏好	代码样式偏好、个人工具快捷方式	仅你（所有项目）
项目指令	./CLAUDE.md 或 ./.claude/CLAUDE.md	项目的团队共享指令	项目架构、编码标准、常见工作流	通过源代码控制的团队成员
本地指令	./CLAUDE.local.md	个人项目特定偏好；添加到 .gitignore	你的沙箱 URL、首选测试数据	仅你（当前项目）

设置项目 CLAUDE.md

项目 CLAUDE.md 可以存储在 ./CLAUDE.md 或 ./.claude/CLAUDE.md 中。建此文件并添加适用于在项目上工作的任何人的指令：构建和测试命令、编码标准、架构决策、命名约定和常见工作流

编写有效的指令

• 大小：每个 CLAUDE.md 文件目标在 200 行以下。
• 结构：使用 markdown 标题和项目符号来分组相关指令。
• 具体性：编写具体到足以验证的指令。
• 一致性：如果两条规则相互矛盾，Claude 可能会任意选择一条。

导入其他文件

• CLAUDE.md 文件可以使用 @path/to/import 语法导入其他文件。
• 相对路径相对于包含导入的文件解析，而不是工作目录。
• 私人项目偏好，在项目根目录创建 CLAUDE.local.md
• CLAUDE.local.md 添加到你的 .gitignore

AGENTS.md

创建一个导入它的 CLAUDE.md

CLAUDE.md 文件如何加载

从当前工作目录向上遍历目录树来读取 CLAUDE.md 文件

使用 .claude/rules/ 组织规则

设置规则

claude/rules/ 目录中放置 markdown 文件。每个文件应涵盖一个主题，具有描述性文件名

特定路径的规则

---
paths:
  - "src/api/**/*.ts"
---

# API 开发规则

- 所有 API 端点必须包括输入验证
- 使用标准错误响应格式
- 包括 OpenAPI 文档注释

模式	匹配
**/*.ts	任何目录中的所有 TypeScript 文件
src/**/*	src/ 目录下的所有文件
*.md	项目根目录中的 Markdown 文件
src/components/*.tsx	特定目录中的 React 组件