Claude Code 完全上手指南：在终端中释放 AI 编程的真正潜力Claude Code 是 Anthropic

概述

Claude Code 是 Anthropic 推出的一款智能编程工具，它是一个基于 AI 的代码助手，可以直接在终端中运行，帮助开发者更快地将想法转化为代码。

什么是 Claude Code？

Claude Code 是一个代理式编程工具（agentic coding tool），它不仅仅是一个聊天窗口或另一个 IDE，而是直接在你已经熟悉的工作环境中为你提供帮助。它能够：

从描述构建功能：用简单的英语告诉 Claude 你想要构建什么，它会制定计划、编写代码并确保代码正常工作
调试和修复问题：描述一个 bug 或粘贴错误信息，Claude Code 会分析你的代码库，识别问题并实现修复
导航任何代码库：询问关于团队代码库的任何问题，获得深思熟虑的答案。Claude Code 能够感知整个项目结构，可以从网络获取最新信息，并通过 MCP 从 Google Drive、Figma 和 Slack 等外部数据源获取信息
自动化繁琐任务：修复复杂的 lint 问题、解决合并冲突、编写发布说明。所有这些都可以通过开发机器上的单个命令完成，或在 CI 中自动完成

为什么开发者喜欢 Claude Code？

在你的终端中工作 不是另一个聊天窗口，不是另一个 IDE。Claude Code 在你已经工作的地方与你相遇，使用你已经喜爱的工具。

直接采取行动 Claude Code 可以直接编辑文件、运行命令和创建提交。需要更多功能？MCP 让 Claude 能够读取 Google Drive 中的设计文档、更新 Jira 中的工单，或使用你的自定义开发工具。

Unix 哲学 Claude Code 是可组合和可脚本化的。tail -f app.log | claude -p "如果在日志流中看到任何异常，请通过 Slack 通知我" 这样的命令是可以工作的。你的 CI 可以运行 claude -p "如果有新的文本字符串，将它们翻译成法语并为 @lang-fr-team 提出 PR 进行审查"。

适用人群

Claude Code 特别适合以下开发者：

希望提高编程效率的前端/后端工程师
需要快速理解和导航大型代码库的开发者
想要构建 LLM 应用但不想重复开发 MCP、工具调用、上下文管理等基础能力的开发者
想要自动化重复性编程任务的团队
追求现代化开发工作流的技术团队

与 Cursor 对比

作为同样基于 Claude 的 AI 编程工具，Claude Code 与 Cursor 各有特色：

Claude Code 的优势

更强的 MCP 生态集成

原生支持 MCP Resources 和 Prompts，可以无缝集成外部数据源
Cursor 目前对 MCP 的支持相对有限

高度可定制性

通过 claude-code-sdk 进行深度编程定制
支持任意修改 system prompt，应用场景不局限于编程领域
可扩展性更强，适合企业级定制需求

成熟的 Subagent 架构

提供完整的子代理系统，支持任务分解、并行执行和专业化处理
相比之下，Cursor 的 subagent 功能仍不够完善且处于 beta 阶段（截至 2025年10月15日）

Claude Code 相对的劣势

用户体验

代码审查时缺乏图形化界面，不如 Cursor 的 IDE 集成体验友好
主要基于终端交互，对习惯 GUI 的用户有一定门槛

学习成本

概念体系更复杂（Agents、Commands、Hooks、MCP 等）
需要用户对 LLM 技术栈有更深入的理解
配置和定制需要更多技术背景

安装Claude Code

前提：安装了Node.js 18 或更新版本

在终端运行如下命令：

# 安装 Claude Code
npm install -g @anthropic-ai/claude-code

# 导航到您的项目
cd your-awesome-project

# 开始使用 Claude 编程
claude
# 首次使用时会提示您登录

在~/.claude/settings.json文件中编写如下内容：

填写MAX_MCP_OUTPUT_TOKENS，允许MCP工具返回大量信息

{
  "env": {
    "DISABLE_PROMPT_CACHING": 0,
    "MAX_MCP_OUTPUT_TOKENS": 1000000,
    "ANTHROPIC_BASE_URL": "填写模型API的BaseURL",
    "ANTHROPIC_AUTH_TOKEN": "填写AK",
    "ANTHROPIC_MODEL": "填写模型名称",
    "ANTHROPIC_SMALL_FAST_MODEL": "填写模型名称"
  }
}

（可选）在JetBrains IDEs或VS Code中安装Claude Code的插件

核心功能

Subagents

分类

类型	文件位置	范围	优先级
项目sub-agent	工作目录下的`.claude/agents/`	在当前项目中可用	最高
用户sub-agent	`~/.claude/agents/`	在所有项目中可用	较低
内置sub-agent		在所有项目中可用	较低

内置sub-agent：

sub-agent	用途
general-purpose	通用代理，用于研究复杂问题、搜索代码和执行多步骤任务
statusline-setup	用于配置Claude Code状态栏设置
output-style-setup	用于创建Claude Code输出样式

结构定义

---
name: your-sub-agent-name
description: 描述何时应该调用此子代理
tools: tool1, tool2, tool3  # 可选 - 如果省略则继承所有工具
model: sonnet  # 可选 - 指定模型别名或 'inherit'
---

您的子代理系统提示在这里。这可以是多个段落
并且应该清楚地定义子代理的角色、能力和解决
问题的方法。

包括具体指令、最佳实践和子代理
应该遵循的任何约束。

注意：model默认值是sonnet，所以如果没有要指定的模型，建议填写inherit

管理方式

使用claude命令/agents进入管理界面
使用命令claude --agents直接管理（无头模式）
直接按照claude code规范写到对应目录文件中
使用SDK进行编程

使用方式

自动委托

Claude Code 主Agent基于以下内容自动委托任务：

您请求中的任务描述
sub-agent配置中的description字段
当前上下文和可用工具

显式调用

通过在命令中或提示词中提及特定sub-agent来请求它：

> 使用 test-runner sub-agent修复失败的测试
> 让 code-reviewer sub-agent查看我最近的更改
> 请 debugger sub-agent调查这个错误

实现原理

Claude Code有一个内部工具Task。

Task入参：

description (必需) ：任务的简短描述（3-5个词）
prompt (必需) ：要执行的具体任务描述
subagent_type (必需) ：要使用的sub-agent类型，接收一个动态的枚举值，枚举值来自sub-agent配置中的name字段

当需要把任务委派给一个sub-agent去执行时，当前parent-agent就会调用Task工具。

每个代理调用都是无状态的，sub-agent所需要的上下文信息仅通过入参字段prompt传递过去。

当sub-agent完成工作，就会把工作结果返回给parent-agent。

Agent Skills

什么是 Skills？

Skills 是包含指令、脚本和资源的文件夹，用于扩展 Claude 的专业能力。

与 Commands 的区别：

Skills：模型自动调用（Claude 根据任务描述智能识别）
Commands：用户手动调用（明确输入 /command 触发）

分类

类型	文件位置	范围
项目 Skills	工作目录下的 `.claude/skills/`	在当前项目中可用
个人 Skills	`~/.claude/skills/`	在所有项目中可用
插件 Skills	插件安装时自动添加	根据插件配置

实现原理

Skills 的设计遵循了一个重要原则：Progressive Disclosure（渐进式披露）——分阶段、按需加载信息，而不是在任务开始时就将所有内容全部塞入宝贵的上下文窗口中。

整个加载过程分为三个层次：

第一层：元数据（始终加载）

每个 Skill 的 SKILL.md 文件头部包含 YAML 元数据（name 和 description）：

---
name: pdf-processing
description: 提取 PDF 文件中的文本和表格,填写表单,合并文档。当处理 PDF 文件或用户提及 PDF、表单或文档提取时使用。
---

元数据在 Claude 启动时加载并始终保持在上下文窗口中，仅占用约 100 个 Token。Claude 通过 description 字段判断当前任务是否需要该 Skill。

第二层：核心指令（触发时加载）

当 Claude 识别到某个 Skill 与当前任务相关时，会使用 Bash 工具读取 SKILL.md 文件的主体内容：

# PDF 处理

## 快速入门

使用 `pdfplumber` 提取 PDF 文本：

import pdfplumber

with pdfplumber.open("document.pdf") as pdf:
    text = pdf.pages[0].extract_text()

如需了解高级表单填写，请参阅 [FORMS.md](FORMS.md)。

只有在这个阶段，Skill 的核心指令和工作流程才会进入上下文窗口，Claude 开始学习如何完成具体任务。

第三层：代码与资源（按需加载）

复杂的 Skill 可能包含多个文件，形成完整的知识库：

pdf-skill/
├── SKILL.md (核心指令)
├── FORMS.md (表单填写指南)
├── REFERENCE.md (详细的 API 参考)
└── scripts/
    └── fill_form.py (实用工具脚本)

Claude 会根据 SKILL.md 中的指引，在需要时才读取 FORMS.md 或执行 fill_form.py 脚本。

执行脚本是最高效的方式：脚本代码本身永远不会进入上下文窗口，只有脚本的输出结果（如"验证通过"或具体错误信息）会作为反馈进入上下文。

结构定义

最简单的 Skill 只需一个 SKILL.md 文件：

---
name: Your Skill Name
description: Brief description of what this Skill does and when to use it
allowed-tools: Read, Grep, Glob  # 可选 - 限制可用工具
---

# Your Skill Name

## Instructions
Provide clear, step-by-step guidance for Claude.

## Examples
Show concrete examples of using this Skill.

元数据字段

字段	必需	说明
name	是	Skill 的名称
description	是	功能和使用场景（关键：Claude 依据此字段决定是否使用）
allowed-tools	否	限制 Skill 可使用的工具列表

description 编写规范：

说明功能
说明使用场景
包含关键术语

示例：

description: Generate unit tests for Java classes using JUnit 5. Use when creating tests, testing Java code, or working with JUnit.

多文件 Skill

my-skill/
├── SKILL.md           (必需)
├── reference.md       (可选文档)
└── scripts/
    └── helper.py      (可选脚本)

从 SKILL.md 引用其他文件：

详细文档见 [reference.md](reference.md)

Claude 仅在需要时读取这些文件（渐进式披露）。

管理方式

直接在指定目录下创建和编辑文件。

# 创建个人 Skill
mkdir -p ~/.claude/skills/my-skill

# 创建项目 Skill
mkdir -p .claude/skills/my-skill

使用方式

自动调用

Claude 会根据任务自动识别和使用相关 Skills：

> 请分析这个 Excel 文件并生成数据透视表
# Claude 自动识别并使用 Excel Skill

查看可用 Skills

> What Skills are available?

或命令行查看：

ls ~/.claude/skills/*/SKILL.md
ls .claude/skills/*/SKILL.md

实战示例

pdf-processing/
├── SKILL.md
├── REFERENCE.md
└── scripts/
    ├── fill_form.py
    └── validate.py

SKILL.md：

---
name: PDF Processing
description: Extract text, fill forms, merge PDFs. Use when working with PDF files. Requires pypdf and pdfplumber packages.
---

# PDF Processing

## Quick start
\`\`\`python
import pdfplumber
with pdfplumber.open("doc.pdf") as pdf:
    text = pdf.pages[0].extract_text()
\`\`\`

详细 API 见 [REFERENCE.md](REFERENCE.md)

## Requirements
\`\`\`bash
pip install pypdf pdfplumber
\`\`\`

Commands

在交互式会话中使用斜杠命令控制Claude的行为。

分类

类型	文件位置	范围
项目命令	工作目录下的`.claude/commands/`	在当前项目中可用
用户命令	`~/.claude/commands/`	在所有项目中可用
内置命令		在所有项目中可用

内置命令见附录

结构定义

命令元数据

元数据	用途	默认值
allowed-tools	命令可以使用的工具列表	从对话中继承
argument-hint	斜杠命令预期的参数。示例：`argument-hint: add [tagId] \| remove [tagId] \| list`。此提示在用户自动完成斜杠命令时显示给用户。	无
description	命令的简要描述	使用提示的第一行
model	特定模型字符串	从对话中继承
disable-model-invocation	是否阻止`SlashCommand`工具调用此命令	false

例如：

---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
argument-hint: [message]
description: 创建git提交
model: claude-3-5-haiku-20241022
---

使用消息创建git提交：$ARGUMENTS

使用位置参数的示例：

---
argument-hint: [pr-number] [priority] [assignee]
description: 审查拉取请求
---

审查PR #$1，优先级为$2，分配给$3。
专注于安全性、性能和代码风格。

命令参数

使用参数占位符将动态值传递给命令：

使用$ARGUMENTS的所有参数

$ARGUMENTS占位符捕获传递给命令的所有参数：

# 命令定义
echo '按照我们的编码标准修复问题 #$ARGUMENTS' > .claude/commands/fix-issue.md

# 使用方法
> /fix-issue 123 high-priority
# $ARGUMENTS 变成："123 high-priority"

使用$1、$2等的单个参数

使用位置参数单独访问特定参数（类似于shell脚本）：

# 命令定义  
echo '审查PR #$1，优先级为$2，分配给$3' > .claude/commands/review-pr.md

# 使用方法
> /review-pr 456 high alice
# $1 变成"456"，$2 变成"high"，$3 变成"alice"

Bash命令执行

使用!前缀在斜杠命令运行之前执行bash命令。输出包含在命令上下文中。您_必须_包含带有Bash工具的allowed-tools，但您可以选择允许的特定bash命令。

例如：

---
allowed-tools: Bash(git add:*), Bash(git status:*), Bash(git commit:*)
description: 创建git提交
---

## 上下文

- 当前git状态：!`git status`
- 当前git差异（已暂存和未暂存的更改）：!`git diff HEAD`
- 当前分支：!`git branch --show-current`
- 最近的提交：!`git log --oneline -10`

## 您的任务

基于上述更改，创建单个git提交。

管理方式

通过在指定目录下创建和编辑文件来管理命令。

示例操作：

# 创建个人命令目录和文件
mkdir -p ~/.claude/commands/my-test
echo "分析此代码的性能问题并建议优化：" > ~/.claude/commands/test/optimize.md

命名规则：

目录路径 = 命令路径（每级目录用 / 分隔）
文件名 = 命令名 + .md 扩展名
调用格式 = /目录路径:文件名（目录分隔符 / 转换为 :，文件名去掉 .md 扩展名）

上述示例创建的命令调用方式为：/test:optimize

使用方式

命令语法

/<command-name> [arguments]

参数	描述
	从Markdown文件名派生的名称（不包含.md扩展名）
[arguments]	传递给命令的可选参数

MCP斜杠命令

MCP服务器可以将prompt公开为在Claude Code中可用的命令。这些命令从连接的MCP服务器动态发现。

MCP命令遵循以下模式：

/mcp__<server-name>__<prompt-name> [arguments]

MCP

MCP Server安装范围

名称	命令参数	文件位置	使用范围
本地	无需参数或`--scope local`	`~/.claude.json`中的`$.projects.{projectPath}.mcpServers`	单个项目且当前用户
项目	`--scope project`	项目根目录的`.mcp.json`	单个项目（设计意图：检入Git版本控制）
用户	`--scope user`	`~/.claude.json`中的`$.mcpServers`	跨项目共享

示例：

# 添加本地范围的服务器（默认）
claude mcp add --transport http stripe https://mcp.stripe.com

# 明确指定本地范围
claude mcp add --transport http stripe --scope local https://mcp.stripe.com

# 添加项目范围的服务器
claude mcp add --transport http paypal --scope project https://mcp.paypal.com/mcp

# 添加用户服务器
claude mcp add --transport http hubspot --scope user https://mcp.hubspot.com/anthropic

.mcp.json 文件遵循标准化格式：

{
  "mcpServers": {
    "shared-server": {
      "command": "/path/to/server",
      "args": [],
      "env": {}
    }
  }
}

MCP Server安装方式

根据您的需求，MCP 服务器可以通过三种不同的方式进行配置：

选项 1：添加远程 HTTP 服务器

HTTP 服务器是连接到远程 MCP 服务器的推荐选项。这是云服务最广泛支持的传输方式。

# 基本语法
claude mcp add --transport http <name> <url>

# 真实示例：连接到 Notion
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 带有 Bearer 令牌的示例
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

选项 2：添加远程 SSE 服务器

SSE（服务器发送事件）传输已弃用。请在可用时使用 HTTP 服务器。

# 基本语法
claude mcp add --transport sse <name> <url>

# 真实示例：连接到 Asana
claude mcp add --transport sse asana https://mcp.asana.com/sse

# 带有身份验证标头的示例
claude mcp add --transport sse private-api https://api.company.com/sse \
  --header "X-API-Key: your-key-here"

选项 3：添加本地 stdio 服务器

Stdio 服务器作为本地进程在您的机器上运行。它们非常适合需要直接系统访问或自定义脚本的工具。

# 基本语法
claude mcp add --transport stdio <name> <command> [args...]

# 真实示例：添加 Airtable 服务器
claude mcp add --transport stdio airtable --env AIRTABLE_API_KEY=YOUR_KEY \
  -- npx -y airtable-mcp-server

显式使用

引用 MCP Resource

@servername:resourceurl，示例：

您能分析 @github:issue://123 并建议修复吗？

执行 MCP Prompt

/mcp__servername__promptname [args]，示例：

/mcp__github__pr_review 456

CLAUDE.md 项目配置

什么是 CLAUDE.md？

CLAUDE.md 是 Claude Code 的项目配置文件，会在会话启动时自动注入到 system prompt 中。它是一种将项目特定知识持久化到 context 的机制，避免每次对话都需要重复说明项目规范。

关于 AGENTS.md 标准

目前业界正在推动 AGENTS.md 作为跨工具的统一标准，已被 OpenAI Codex、Google Jules、Cursor、Amp 等 20,000+ 开源项目采用。相比 CLAUDE.md，AGENTS.md 的优势在于：

跨工具兼容：一个文件适配所有 AI 编程助手
团队协作友好：团队成员可使用不同工具而无需维护多份配置
生态标准化：减少工具切换时的迁移成本

Claude Code 社区已有 Feature Request 要求支持 AGENTS.md（获得 895+ 赞同），但截至当前版本尚未实现。如果你的项目需要跨工具协作，可以考虑：

同时维护 CLAUDE.md 和 AGENTS.md（通过符号链接减少重复）
优先使用 AGENTS.md 并配置其他工具读取该文件
等待 Claude Code 官方支持后迁移

本文后续内容仍以 CLAUDE.md 为准，因其是当前 Claude Code 的原生支持格式。

实现原理

Context 自动注入机制

Claude Code 在会话初始化时会按照以下顺序搜索并加载 CLAUDE.md 文件：

全局配置：~/.claude/CLAUDE.md（应用于所有项目）
父目录配置：从当前工作目录向上遍历，加载所有父目录中的 CLAUDE.md
当前目录配置：工作目录下的 CLAUDE.md 或 CLAUDE.local.md
子目录配置：当处理子目录中的文件时，按需加载该子目录的 CLAUDE.md

所有匹配的文件内容会被合并注入到 system prompt 的特定位置，成为模型推理的一部分。这种多层级加载机制特别适合 monorepo 场景，既可以在根目录定义通用规范，又能在子项目中补充专属配置。

文件命名规则

CLAUDE.md：建议提交到 Git，供团队共享
CLAUDE.local.md：本地配置（应添加到 .gitignore），用于个人偏好设置

Claude Code 优先加载 CLAUDE.local.md，如果不存在则加载 CLAUDE.md。

适用场景

CLAUDE.md 适合存放项目级别的静态知识，包括：

常用命令：构建、测试、部署等 bash 命令及其用途
代码规范：命名约定、代码风格、import 顺序等
关键文件：核心 utility 类、配置文件位置
工作流程：提交规范、分支策略、code review 流程
环境配置：依赖的编译器、工具链、环境变量
已知问题：项目特有的 workarounds、技术债务说明

不适合存放频繁变化的内容（如当前任务列表、临时笔记），这类信息应通过对话动态传递。

内容组织最佳实践

保持简洁性

CLAUDE.md 会占用 context window，应当精炼内容。遵循 80/20 原则：记录 20% 最常用的信息来覆盖 80% 的场景。

示例：

# 构建命令
- npm run build: 构建生产版本
- npm run dev: 启动开发服务器（端口 3000）
- npm run typecheck: 运行类型检查（提交前必须执行）

# 代码风格
- 使用 ES modules (import/export)，禁用 CommonJS (require)
- 优先使用解构导入：import { foo } from 'bar'
- 异步函数使用 async/await，避免 Promise.then()

# 重要约定
- 修改 schema.prisma 后必须运行 prisma generate
- API routes 放在 src/app/api/，不要放在 pages/api/

迭代优化

将 CLAUDE.md 视为 prompt engineering 的一部分，通过以下方式持续优化：

观察模型行为：当 Claude 频繁违反某个规范时，检查 CLAUDE.md 中的描述是否清晰
增强强调：对关键规则使用 **IMPORTANT** 或 **YOU MUST** 提高遵守度
添加示例：抽象规则不如具体示例有效，补充实际代码片段
删除冗余：移除从未被用到的信息

管理方式

手动编辑

直接创建和修改文件：

# 创建全局配置
mkdir -p ~/.claude
vim ~/.claude/CLAUDE.md

# 创建项目配置
vim CLAUDE.md

通过交互式会话添加

在对话中按 # 键，Claude 会将你输入的内容自动合并到相应的 CLAUDE.md 中。许多工程师在编码时频繁使用 # 记录命令、文件路径和规范，然后将 CLAUDE.md 的变更提交到 Git。

使用 /init 命令初始化

在新项目中运行 /init，Claude 会自动分析项目结构并生成初始的 CLAUDE.md 文件。

使用 /memory 命令编辑

运行 /memory 命令会打开编辑器来修改当前生效的 CLAUDE.md 文件。

Todo 功能

Todo 功能是 Claude Code 内置的任务跟踪工具。当用户提出复杂任务时，Claude Code 会自动创建任务列表，将大任务拆解为多个步骤，并在执行过程中实时更新状态。

实现原理

Claude Code 内部提供了 TodoWrite 工具来实现 Todo 功能。

TodoWrite 工具

用于创建或更新任务列表。

入参结构：

{
  todos: [
    {
      content: string;      // 祈使句："运行测试"
      status: "pending" | "in_progress" | "completed";
      activeForm: string;   // 进行时态："正在运行测试"
    }
  ]
}

调用时机：

检测到复杂任务时创建初始任务列表
完成一个任务后更新状态（标记为 completed，下一个切换为 in_progress）
执行过程中发现新步骤时动态添加任务

运行机制

触发条件

Claude Code 在以下情况自动启用 Todo 功能：

任务包含 3 个以上明确步骤
用户提供多个任务（逗号分隔、编号列表）
检测到非平凡的复杂任务
用户明确要求（如"列出计划"）

执行规则

串行执行：同一时刻仅一个任务为 in_progress，其余为 pending 或 completed
即时更新：每完成一个任务立即标记为 completed，同时将下一个任务切换为 in_progress
动态调整：执行中发现新步骤时动态添加到任务列表
任务粒度：拆解为具体可执行的操作，避免过细（如"打开文件"）或过粗（如"完成功能"）

使用示例

用户请求：

> 添加暗黑模式切换到应用设置，完成后运行测试和构建

Claude Code 生成的任务列表：

{
  todos: [
    {
      content: "创建暗黑模式切换组件",
      status: "in_progress",
      activeForm: "正在创建暗黑模式切换组件"
    },
    {
      content: "添加暗黑模式状态管理",
      status: "pending",
      activeForm: "正在添加暗黑模式状态管理"
    },
    {
      content: "实现 CSS 暗黑主题样式",
      status: "pending",
      activeForm: "正在实现 CSS 暗黑主题样式"
    },
    {
      content: "更新现有组件支持主题切换",
      status: "pending",
      activeForm: "正在更新现有组件支持主题切换"
    },
    {
      content: "运行测试和构建流程",
      status: "pending",
      activeForm: "正在运行测试和构建流程"
    }
  ]
}

用户如何利用

清晰表述需求：明确说明任务目标，Claude Code 会自动拆解为步骤并展示执行计划
追踪执行进度：通过 Todo 状态了解当前进展，便于中断或调整方向
批量任务处理：提供多个需求时（如"实现登录功能，添加用户管理，编写测试"），Claude Code 会统一规划并按序执行

Hooks

个人感觉Hooks的使用场景比较局限，不是一个核心的功能。我只想到可以用于进行埋点统计上报。

但是很能够体现Claude Code开放的态度。Cursor最新版本也有这个功能。

hooks 的示例用例包括：

通知：自定义当 Claude Code 等待您的输入或运行某些内容的权限时如何获得通知。
自动格式化：在每次文件编辑后对 .ts 文件运行 prettier，对 .go 文件运行 gofmt 等。
日志记录：跟踪和计算所有执行的命令以进行合规性检查或调试。
反馈：当 Claude Code 生成不符合您代码库约定的代码时提供自动反馈。
自定义权限：阻止对生产文件或敏感目录的修改。

Claude Code 提供了几个在工作流程不同点运行的 hook 事件：

PreToolUse：在工具调用之前运行（可以阻止它们）
PostToolUse：在工具调用完成后运行
UserPromptSubmit：当用户提交提示时运行，在 Claude 处理之前
Notification：当 Claude Code 发送通知时运行
Stop：当 Claude Code 完成响应时运行
SubagentStop：当子代理任务完成时运行
PreCompact：在 Claude Code 即将运行压缩操作之前运行
SessionStart：当 Claude Code 开始新会话或恢复现有会话时运行
SessionEnd：当 Claude Code 会话结束时运行

每个事件接收不同的数据，并可以以不同的方式控制 Claude 的行为。

Output Styles

和Hooks一样，用处不大

Claude Code的output styles是一种允许您将Claude Code用作任何类型代理的功能，同时保留其核心能力，如运行本地脚本、读写文件和跟踪TODO

Claude Code允许用户自定义output styles。

内置的Output Styles

Claude Code提供三种内置的output styles：

Default：现有的系统提示，专为高效完成软件工程任务而设计
Explanatory：在帮助您完成软件工程任务的同时提供教育性的"Insights"，帮助您理解实现选择和代码库模式
Learning：协作式的边做边学模式，Claude不仅会在编码时分享"Insights"，还会要求您自己贡献小的、战略性的代码片段。Claude Code会在您的代码中添加TODO(human)标记供您实现

实践案例：创建Java单元测试助手

本节通过一个实际案例，演示如何结合 Subagent 和 Command 功能，构建一个自动化的 Java 单元测试生成工具链。

场景说明

目标是创建一个专门的 Java 单元测试专家 subagent，并通过自定义 command 实现快速调用。工作流程如下：

用户通过 command 指定要测试的 Java 类
Command 将任务委派给专业的测试专家 subagent
Subagent 根据规范生成符合标准的单元测试代码

这种方式的优势在于任务分工明确，测试规范统一，且易于维护和扩展。

步骤1：创建测试专家 Subagent

在 ~/.claude/agents/ 目录下创建 java-test-expert.md 文件：

---
name: java-test-expert
description: 为Java类生成符合规范的JUnit 5单元测试
model: inherit
---

你是一位Java单元测试专家，专注于为Java类生成高质量的单元测试代码。

## 测试规范

### 命名规范
- 测试类名：`[被测类名]Test`
- 测试方法名：`test[方法名]`或`test[方法名]_[场景]`
- 测试类和方法都使用包私有（不加public修饰符）

### 技术栈
使用 JUnit 5 (org.junit.jupiter):
``
import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;
``

### 测试覆盖
每个方法至少覆盖以下场景：
- **正常情况**：典型输入的执行路径
- **边界情况**：空值、null、边界值
- **异常情况**：无效输入和异常抛出

### 测试结构
``
class StringUtilsTest {
    @Test
    void testIsEmpty() {
        assertTrue(StringUtils.isEmpty(""));
        assertTrue(StringUtils.isEmpty(null));
        assertFalse(StringUtils.isEmpty("text"));
    }
}
``

## 工作流程

1. 读取被测试的类文件
2. 识别测试文件应存放的位置（遵循Maven标准目录结构）
3. 为每个公共方法生成测试用例
4. 确保测试代码可编译通过

步骤2：创建快捷 Command

在 ~/.claude/commands/ 目录下创建 test.md 文件：

---
description: 为指定的Java类生成单元测试
---

请使用 java-test-expert subagent 生成完整的单元测试：$ARGUMENTS

步骤3：使用示例

假设项目中有一个工具类 src/main/java/com/example/util/StringUtils.java：

package com.example.util;

public class StringUtils {
    public static boolean isEmpty(String str) {
        return str == null || str.length() == 0;
    }
    
    public static String capitalize(String str) {
        if (isEmpty(str)) {
            return str;
        }
        return str.substring(0, 1).toUpperCase() + str.substring(1);
    }
}

在 Claude Code 中执行：

> /test StringUtils

执行流程：

主 Agent 接收到 /test StringUtils 命令
主 Agent 根据 command 配置，调用内置 Task 工具
Task 工具将任务委派给 java-test-expert subagent
Subagent 读取 StringUtils.java 源码
Subagent 生成测试文件 src/test/java/com/example/util/StringUtilsTest.java

生成的测试代码示例：

package com.example.util;

import org.junit.jupiter.api.Test;
import static org.junit.jupiter.api.Assertions.*;

class StringUtilsTest {
  
    @Test
    void testIsEmpty() {
        assertTrue(StringUtils.isEmpty(null));
        assertTrue(StringUtils.isEmpty(""));
        assertFalse(StringUtils.isEmpty("text"));
    }
  
    @Test
    void testIsEmpty_withWhitespace() {
        assertFalse(StringUtils.isEmpty(" "));
    }
  
    @Test
    void testCapitalize() {
        assertEquals("Hello", StringUtils.capitalize("hello"));
        assertEquals("A", StringUtils.capitalize("a"));
    }
  
    @Test
    void testCapitalize_emptyString() {
        assertEquals("", StringUtils.capitalize(""));
        assertNull(StringUtils.capitalize(null));
    }
}

附：Claude Code内置命令

命令	用途
/add-dir	添加额外的工作目录
/agents	管理用于专门任务的自定义AI子代理
/bug	报告错误（将对话发送给Anthropic）
/clear	清除对话历史
/compact [instructions]	压缩对话，可选择性地提供焦点指令
/config	打开设置界面（配置选项卡）
/cost	显示Tokens使用统计（有关订阅特定详细信息，请参阅成本跟踪指南）
/doctor	检查您的Claude Code安装的健康状况
/help	获取使用帮助
/init	使用CLAUDE.md指南初始化项目
/login	切换Anthropic账户
/logout	从您的Anthropic账户注销
/mcp	管理MCP服务器连接和OAuth身份验证
/memory	编辑CLAUDE.md内存文件
/model	选择或更改AI模型
/permissions	查看或更新权限
/pr_comments	查看拉取请求评论
/review	请求代码审查
/rewind	回退对话和/或代码
/status	打开设置界面（状态选项卡），显示版本、模型、账户和连接性
/terminal-setup	安装Shift+Enter键绑定用于换行（仅限iTerm2和VSCode）
/usage	显示计划使用限制和速率限制状态（仅限订阅计划）
/vim	进入vim模式，用于交替插入和命令模式

附：Claude Code内置工具

工具	描述	需要权限
Bash	在您的环境中执行 shell 命令	是
Edit	对特定文件进行有针对性的编辑	是
Glob	基于模式匹配查找文件	否
Grep	在文件内容中搜索模式	否
NotebookEdit	修改 Jupyter notebook 单元格	是
NotebookRead	读取和显示 Jupyter notebook 内容	否
Read	读取文件内容	否
SlashCommand	运行自定义斜杠命令	是
Task	运行子代理来处理复杂的多步骤任务	否
TodoWrite	创建和管理结构化任务列表	否
WebFetch	从指定 URL 获取内容	是
WebSearch	执行带有域过滤的网络搜索	是
Write	创建或覆盖文件	是