Claude Code 构建完全指南：十大核心功能深度解析

王小酱
22 阅读28分钟

一、创建自定义子代理（Subagents）

1. 是什么

子代理是运行在独立上下文窗口中的专用 AI 助手。每个子代理拥有自己的系统提示、工具访问权限和权限设置。当 Claude 遇到与某个子代理描述匹配的任务时，会自动将任务委派给该子代理，子代理独立工作并返回结果。Claude Code 内置了 Explore（只读代码搜索，使用 Haiku 模型）、Plan（计划模式研究代理）和 general-purpose（全工具通用代理）等子代理，用户也可以创建自定义子代理。

2. 怎么用

创建子代理最简单的方式是在 Claude Code 中运行 /agents 命令，进入交互式界面选择"Create new agent"，然后选择作用域（用户级或项目级），输入描述后由 Claude 自动生成配置。也可以手动创建 Markdown 文件，放在 .claude/agents/（项目级）或 ~/.claude/agents/（用户级）目录中：

---
name: code-reviewer
description: Reviews code for quality and best practices
tools: Read, Glob, Grep
model: sonnet
---
You are a code reviewer. Analyze the code and provide actionable feedback.

还可以通过 CLI 标志以 JSON 传递临时子代理：

claude --agents '{ "code-reviewer": { "description": "Expert code reviewer.", "prompt": "Focus on code quality and security.", "tools": ["Read","Grep","Glob","Bash"], "model": "sonnet" } }'

3. 使用场景与痛点

子代理解决的核心痛点是主对话上下文膨胀和工具权限失控。典型场景包括：运行测试套件时大量输出占用上下文（委派给子代理后只返回摘要）、需要对代码库进行并行研究（多个子代理同时探索不同模块）、需要强制只读权限（如代码审查只允许读不允许写）、多步骤工作流的链式委派（先审查再优化），以及通过路由到 Haiku 模型来控制 Token 成本。

4. 使用示例

入门示例——只读代码审查器：

---
name: code-reviewer
description: Expert code review specialist. Use immediately after writing or modifying code.
tools: Read, Grep, Glob, Bash
model: inherit
---
You are a senior code reviewer. Run git diff, focus on modified files, check for readability, error handling, security, and test coverage. Organize feedback by priority: Critical, Warnings, Suggestions.

使用时只需说："Use the code-reviewer subagent to look at my recent changes."

进阶示例——带持久化记忆的调试器：

---
name: debugger
description: Debugging specialist for errors, test failures, and unexpected behavior. Use proactively when encountering any issues.
tools: Read, Edit, Bash, Grep, Glob
memory: user
---
You are an expert debugger. Capture error messages, identify reproduction steps, isolate failure location, implement minimal fix, verify solution. Before starting, consult your memory for patterns you've seen before. After fixing, save what you learned.

记忆功能使调试器跨会话积累知识——它会记住之前遇到的 bug 模式和修复策略，随着使用越来越高效。

高级最佳实践——带 Hook 验证的数据库查询代理：

---
name: db-reader
description: Execute read-only database queries. Use when analyzing data or generating reports.
tools: Bash
hooks:
  PreToolUse:
    - matcher: "Bash"
      hooks:
        - type: command
          command: "./scripts/validate-readonly-query.sh"
---
You are a database analyst with read-only access. Execute SELECT queries only.

配合验证脚本，通过 Hook 在每个 Bash 命令执行前检查是否包含 INSERT/UPDATE/DELETE 等写操作，退出码 2 阻止执行。这是"工具级允许、操作级限制"的精细控制模式。其他高级实践包括：使用 skills 字段预加载团队编码规范、用 isolation: worktree 在独立 git worktree 中运行子代理避免影响主分支、用 Task(worker, researcher) 语法限制主代理只能生成特定子代理。

5. 适用角色

个人开发者： 创建用户级子代理（~/.claude/agents/）用于个人常用任务，如代码审查、调试、日志分析。推荐从 /agents 交互式界面入手，用 Haiku 模型的 Explore 子代理快速搜索代码库以节省成本。

团队开发者： 创建项目级子代理（.claude/agents/）并提交到版本控制。统一团队的代码审查标准、API 开发规范。使用 skills 字段预加载团队编码规范，确保每个成员使用的子代理行为一致。

Tech Lead / 架构师： 设计子代理体系——为不同任务领域（前端、后端、数据库、安全）创建专门的子代理，使用权限模式和工具限制确保安全边界。利用 memory: project 让子代理积累项目架构知识。

DevOps / CI 工程师： 通过 --agents CLI 标志在自动化脚本和 CI/CD 流水线中动态定义子代理，用于自动化测试、代码扫描、构建验证等。结合 bypassPermissions 模式实现全自动化执行。

二、运行代理团队（Agent Teams）

1. 是什么

代理团队是一项实验性功能，允许多个独立的 Claude Code 实例协同工作。一个会话充当"团队负责人"（Lead），协调工作、分配任务和综合结果；其他"团队成员"（Teammates）各自拥有独立的上下文窗口，可以直接相互通信、挑战彼此的发现。与子代理的关键区别是：子代理只能向主代理报告结果，而代理团队成员之间可以直接发送消息和协作。

2. 怎么用

首先需要启用实验性功能，在 settings.json 中添加：

{ "env": { "CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS": "1" } }

然后用自然语言告诉 Claude 创建团队：

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage

Claude 会创建团队、生成共享任务列表、生成成员并协调工作。在进程内模式中用 Shift+Down 切换成员；在分屏模式中（需 tmux 或 iTerm2）每个成员有独立窗格。用 Ctrl+T 切换任务列表视图。

3. 使用场景与痛点

代理团队解决的核心痛点是单一会话的线性工作模式无法高效处理需要并行探索的复杂任务。最强场景包括：并行代码审查（安全、性能、测试覆盖各一个审查员，避免单个审查员的视角偏见）、竞争假设调试（多个成员调查不同理论并相互辩论反驳，避免锚定效应）、新功能多模块开发（每个成员负责一个独立模块不会冲突）以及跨层协调（前端、后端、测试各由不同成员负责）。

不适合的场景：顺序任务、同文件编辑、依赖关系多的工作——这些情况下单会话或子代理更高效。

4. 使用示例

入门示例——并行代码审查：

Create an agent team to review PR #142. Spawn three reviewers:
- One focused on security implications
- One checking performance impact
- One validating test coverage
Have them each review and report findings.

每个审查员从不同角度审查同一个 PR，Lead 综合所有发现。

进阶示例——竞争假设调试：

Users report the app exits after one message instead of staying connected.
Spawn 5 agent teammates to investigate different hypotheses.
Have them talk to each other to try to disprove each other's theories,
like a scientific debate. Update the findings doc with whatever consensus emerges.

辩论式结构是关键——多个独立调查者主动尝试推翻对方的理论，幸存的理论更可能是真正的根因。

高级最佳实践：

要求成员在实施前提交计划审批：

Spawn an architect teammate to refactor the authentication module.
Require plan approval before they make any changes.

成员以只读计划模式工作，提交计划后由 Lead 审批或驳回。可以通过提示影响 Lead 的判断标准，如"只批准包含测试覆盖的计划"。其他高级实践包括：使用 TeammateIdle 和 TaskCompleted Hook 实施质量门禁、保持 3-5 个成员和每人 5-6 个任务的最佳比例、给成员充足的上下文（spawn 提示中包含具体的任务细节而非依赖继承）。

5. 适用角色

个人开发者： 从研究和审查任务开始尝试——审查一个 PR、研究一个库、调查一个 bug。这些任务展示并行探索的价值，又没有并行实施的协调挑战。

团队 Lead / 项目经理： 用代理团队进行全方位的代码审查、架构评估和技术方案论证。通过设定审批流程（require plan approval）控制实施质量。

高级工程师： 用于复杂调试（竞争假设模式）、跨模块重构（每个成员负责一个模块）和大规模代码迁移（并行处理不同组件）。注意 Token 消耗——代理团队的成本随成员数线性增长。

注意： 代理团队目前是实验性功能，不建议在关键生产流程中使用。已知限制包括不支持进程内成员的会话恢复、任务状态可能滞后、每个会话只能管理一个团队。

三、创建插件（Plugins）

1. 是什么

插件是 Claude Code 的打包扩展机制，将技能、代理、钩子、MCP 服务器和 LSP 服务器封装成可分发的单元。每个插件有一个 .claude-plugin/plugin.json 清单文件定义元数据，以及按功能组织的目录结构。插件的技能使用命名空间（/plugin-name:skill-name）来避免多插件之间的冲突。

与独立配置（.claude/ 目录中的文件）相比，插件更适合需要跨项目、跨团队共享的场景——独立配置适合个人实验和项目专属定制，插件适合版本化发布和市场分发。

2. 怎么用

创建插件的步骤：

# 1. 创建插件目录和清单
mkdir -p my-plugin/.claude-plugin
# 2. 编写 plugin.json
cat > my-plugin/.claude-plugin/plugin.json << 'EOF'
{ "name": "my-plugin", "description": "My extension", "version": "1.0.0" }
EOF
# 3. 添加技能
mkdir -p my-plugin/skills/hello
cat > my-plugin/skills/hello/SKILL.md << 'EOF'
---
description: Greet the user with a friendly message
---
Greet the user warmly and ask how you can help.
EOF
# 4. 本地测试
claude --plugin-dir ./my-plugin

在 Claude Code 中运行 /my-plugin:hello 即可使用。可以用 --plugin-dir 标志同时加载多个插件进行测试。

3. 使用场景与痛点

插件解决的核心痛点是扩展功能的碎片化和不可共享。典型场景包括：团队统一工具链（所有成员通过安装同一插件获得相同的代码审查代理、提交工作流和格式化钩子）、社区分享（将自己开发的有用扩展发布到市场让其他人安装）、跨项目复用（一套检查规则不需要在每个项目中重新配置）、以及版本化管理（通过语义化版本号追踪发布和更新）。

4. 使用示例

入门示例——包含一个技能的插件：

创建一个 greeting 插件，包含一个 hello 技能。目录结构：greeting/.claude-plugin/plugin.json + greeting/skills/hello/SKILL.md。使用 claude --plugin-dir ./greeting 加载，然后运行 /greeting:hello Alex 测试。

进阶示例——包含代理、钩子和 LSP 的完整插件：

my-team-plugin/
├── .claude-plugin/
│   └── plugin.json
├── agents/
│   └── security-reviewer.md      # 安全审查代理
├── skills/
│   └── code-review/
│       └── SKILL.md               # 代码审查技能
├── hooks/
│   └── hooks.json                 # PostToolUse 自动格式化
├── .mcp.json                      # 集成 GitHub MCP 服务器
├── .lsp.json                      # TypeScript LSP 配置
└── settings.json                  # 默认设置 {"agent": "security-reviewer"}

设置 settings.json 中的 agent 字段可以让插件在启用时自动激活指定代理作为默认行为。

高级最佳实践：

从独立配置迁移到插件：将 .claude/commands/、.claude/agents/ 和 .claude/skills/ 的文件复制到插件目录，将 settings.json 中的 hooks 迁移到 hooks/hooks.json，然后用 --plugin-dir 验证一切正常。发布前为插件添加 README.md，使用语义化版本号。注意：不要把 commands/、agents/ 等目录放在 .claude-plugin/ 里面——只有 plugin.json 放在 .claude-plugin/ 中，其他目录在插件根目录。

5. 适用角色

个人开发者： 先用 .claude/ 目录中的独立配置快速实验，等稳定后再转为插件以跨项目复用。适合创建个人的提交工作流、代码模板等。

团队 Lead / 平台工程师： 为团队创建统一的插件，包含编码规范技能、代码审查代理和自动格式化钩子。通过项目的 .claude/settings.json 配置团队市场，让新成员加入时自动获取团队插件。

开源 / 社区贡献者： 创建通用插件（如 commit-commands、pr-review-toolkit）并发布到市场，供社区使用。遵循清晰的目录结构和版本号规范。

企业 IT 管理员： 通过托管设置（managed settings）部署组织级插件，确保合规性审查工具和安全检查在所有项目中强制启用。

四、发现和安装预构建插件

1. 是什么

插件市场（Marketplace）是帮助用户发现和安装 Claude Code 扩展的目录。市场本质上是一个包含 .claude-plugin/marketplace.json 的仓库或文件，列出了可供安装的插件集合。Anthropic 官方市场（claude-plugins-official）自动可用，包含代码智能（LSP）、外部集成（GitHub/Slack/Jira 等）、开发工作流和输出风格等类别的插件。用户也可以添加第三方市场或创建团队私有市场。

2. 怎么用

# 浏览官方市场
/plugin                             # 打开插件管理器，进入 Discover 标签

# 安装插件
/plugin install typescript-lsp@claude-plugins-official

# 添加第三方市场
/plugin marketplace add anthropics/claude-code        # GitHub 仓库
/plugin marketplace add https://gitlab.com/company/plugins.git  # Git URL
/plugin marketplace add ./my-marketplace              # 本地路径

# 管理插件
/plugin disable plugin-name@marketplace-name          # 禁用
/plugin enable plugin-name@marketplace-name           # 启用
/plugin uninstall plugin-name@marketplace-name        # 卸载

# 管理市场
/plugin marketplace list                              # 列出所有市场
/plugin marketplace update marketplace-name           # 刷新
/plugin marketplace remove marketplace-name           # 移除（会卸载其中的插件）

插件安装有三种作用域：用户（跨所有项目）、项目（通过 .claude/settings.json 共享给协作者）和本地（仅当前用户当前仓库）。

3. 使用场景与痛点

插件市场解决的核心痛点是手动配置外部工具的复杂性和团队配置不一致。安装代码智能插件后，Claude 在每次编辑后自动获得类型错误、缺失导入等诊断反馈，无需手动运行编译器。安装外部集成插件（GitHub、Jira、Slack）后，Claude 可以直接与这些服务交互，无需手动配置 MCP 服务器。团队管理员可以在 .claude/settings.json 中配置 extraKnownMarketplaces 和 enabledPlugins，让团队成员信任仓库后自动安装指定市场和插件。

4. 使用示例

入门示例——安装代码智能插件：

/plugin install typescript-lsp@claude-plugins-official

安装后，Claude 在编辑 TypeScript 文件时自动获得类型检查——如果引入错误会立即发现并在同一轮修复。按 Ctrl+O 可以内联查看诊断信息。前提：系统需安装对应的语言服务器二进制文件（如 typescript-language-server）。

进阶示例——添加外部集成和工作流插件：

# 安装 GitHub 集成
/plugin install github@claude-plugins-official
# 安装提交工作流
/plugin install commit-commands@claude-plugins-official

之后可以直接说"Review PR #456 and suggest improvements"或使用 /commit-commands:commit 一键暂存、生成消息、创建提交。

高级最佳实践：

配置团队市场自动安装：在项目的 .claude/settings.json 中添加 extraKnownMarketplaces 和 enabledPlugins，让团队成员加入项目时自动获取。启用自动更新以保持插件版本最新（官方市场默认启用，第三方默认禁用）。如果需要禁用 Claude Code 自动更新但保持插件更新，可设置 DISABLE_AUTOUPDATER=true 和 FORCE_AUTOUPDATE_PLUGINS=true。

5. 适用角色

所有开发者： 安装代码智能插件是最基础的增强——给 Claude 实时的类型错误和语法问题反馈，减少编辑后需要手动编译验证的次数。

全栈开发者： 安装外部集成插件（GitHub、Slack、Figma、数据库），让 Claude 能直接从 issue 描述实现功能、集成设计稿、查询数据库。

团队管理员： 配置团队市场，确保所有成员使用相同的插件和版本。通过项目级安装（--scope project）将插件配置提交到版本控制。

初学者： 从 Discover 标签浏览可用插件，安装 learning-output-style 或 explanatory-output-style 获得更好的学习体验。

五、使用技能扩展 Claude（Skills）

1. 是什么

技能（Skills）是通过 SKILL.md 文件为 Claude 添加的指令和能力扩展。技能遵循 Agent Skills 开放标准，可以是参考知识（编码规范、API 文档），也可以是具体任务（部署流程、提交规范）。Claude 可以根据任务上下文自动加载相关技能，用户也可以通过 /skill-name 直接调用。

技能与子代理的区别：技能默认在主对话上下文中运行（共享上下文），子代理在隔离的上下文中运行。技能适合需要共享对话历史的场景，子代理适合需要隔离的场景。

2. 怎么用

创建技能目录和 SKILL.md 文件：

mkdir -p ~/.claude/skills/explain-code

编写 ~/.claude/skills/explain-code/SKILL.md：

---
name: explain-code
description: Explains code with visual diagrams and analogies. Use when explaining how code works.
---
When explaining code, always include:
1. **Start with an analogy**: Compare the code to something from everyday life
2. **Draw a diagram**: Use ASCII art to show the flow
3. **Walk through the code**: Explain step-by-step
4. **Highlight a gotcha**: What's a common mistake?

两种使用方式：让 Claude 自动识别（"How does this code work?"）或直接调用（/explain-code src/auth/login.ts）。

3. 使用场景与痛点

技能解决的核心痛点是重复的指令输入和行为不一致。没有技能时，每次需要 Claude 按特定方式工作都要重新描述需求；有了技能，一次编写，反复使用。典型场景包括：团队编码规范强制执行（API 设计模式、错误处理模式作为参考技能自动加载）、标准化操作流程（部署、提交、PR 创建作为任务技能由用户触发）、自定义代码生成模板（组件创建、测试编写遵循固定结构），以及跨项目知识复用（个人级技能在所有项目中可用）。

4. 使用示例

入门示例——参考型技能（API 规范）：

---
name: api-conventions
description: API design patterns for this codebase
---
When writing API endpoints:
- Use RESTful naming conventions
- Return consistent error formats: { "error": { "code": "...", "message": "..." } }
- Include request validation with Zod schemas
- Always add rate limiting middleware

Claude 在实现 API 时会自动加载这个技能，确保遵循团队约定。

进阶示例——带参数和动态上下文的任务技能：

---
name: fix-issue
description: Fix a GitHub issue
disable-model-invocation: true
---
Fix GitHub issue $ARGUMENTS following our coding standards.

## Issue context
- Issue details: !`gh issue view $0 --json title,body,labels`
- Recent commits: !`git log --oneline -5`

## Steps
1. Read the issue description
2. Implement the fix
3. Write tests
4. Create a commit

使用 /fix-issue 123 时，!command 语法预先执行 shell 命令获取实时数据，$0 替换为第一个参数。disable-model-invocation: true 确保只有用户手动触发。

高级最佳实践——在子代理中运行技能 + 可视化输出：

---
name: deep-research
description: Research a topic thoroughly
context: fork
agent: Explore
---
Research $ARGUMENTS thoroughly:
1. Find relevant files using Glob and Grep
2. Read and analyze the code
3. Summarize findings with specific file references

context: fork 使技能在隔离的 Explore 子代理中运行，不影响主对话。另一个强大模式是生成可视化输出——技能中捆绑 Python 脚本生成交互式 HTML 文件用于数据探索。其他高级实践：使用 allowed-tools 限制技能中 Claude 可用的工具、用 Skill(commit) / Skill(deploy *) 权限规则精细控制哪些技能 Claude 可以自动调用、SKILL.md 控制在 500 行内并将详细参考材料拆分到辅助文件中。

5. 适用角色

个人开发者： 创建用户级技能（~/.claude/skills/）封装个人工作习惯——自定义提交格式、代码解释风格、调试流程。用 disable-model-invocation: true 保护有副作用的操作（如部署）。

团队开发者： 创建项目级技能（.claude/skills/）并提交到版本控制，统一团队的 API 设计模式、错误处理方式、测试编写规范。新成员无需阅读长篇文档，Claude 自动遵循。

技术培训师 / 导师： 创建教学型技能（如 explain-code），让 Claude 始终用类比、图表和分步讲解的方式解释代码，帮助初级开发者学习。

平台工程师： 通过插件分发技能、通过企业托管设置强制加载组织级技能，确保合规性检查和安全扫描在所有项目中自动执行。

六、输出风格（Output Styles）

1. 是什么

输出风格直接修改 Claude Code 的系统提示，改变 Claude 的响应方式——包括格式、语调和结构。与 CLAUDE.md（作为附加的用户消息）和 --append-system-prompt（追加到系统提示末尾）不同，输出风格会关闭 Claude Code 默认系统提示中与软件工程相关的部分，用自定义指令替代。Claude Code 内置三种风格：默认（高效完成软件工程任务）、解释性（在工作中穿插教育性"洞察"）、学习（协作式学做模式，用 TODO(human) 标记让用户自己写代码）。

2. 怎么用

# 交互式选择
/output-style

# 直接切换到指定风格
/output-style explanatory
/output-style learning

创建自定义输出风格，保存为 Markdown 文件到 ~/.claude/output-styles/（用户级）或 .claude/output-styles/（项目级）：

---
name: My Custom Style
description: A brief description
keep-coding-instructions: false
---
# Custom Style Instructions
You are an interactive CLI tool that helps users with software engineering tasks.
[Your custom instructions...]

keep-coding-instructions: true 可以保留 Claude Code 默认的编码相关系统提示（如"用测试验证代码"）。

3. 使用场景与痛点

输出风格解决的核心痛点是 Claude 的响应方式与用户需求不匹配。有些人需要简洁的执行结果，有些人需要详细的解释以学习。典型场景包括：初学者学习模式（learning 风格让 Claude 不仅写代码还要求你自己实践）、教学演示（explanatory 风格在每个实现决策后插入背景知识）、非软件工程任务（关闭默认的编码指令，让 Claude 专注于写作、分析等）、团队统一输出格式（通过项目级输出风格确保所有人看到相同格式的响应）。

4. 使用示例

入门示例——切换到学习模式：

/output-style learning

切换后，Claude 在帮你完成任务时会添加 TODO(human) 标记，要求你自己实现关键部分，同时分享"洞察"帮助你理解为什么这样做。

进阶示例——创建自定义架构师风格：

---
name: architect
description: Respond with architecture-first thinking. Always discuss trade-offs before implementing.
keep-coding-instructions: true
---
# Architect Mode
Before writing any code:
1. Identify the architectural implications
2. List alternative approaches with trade-offs
3. Recommend an approach with justification
4. Only implement after the user approves

Always think about: scalability, maintainability, testability, and security.
Use diagrams (ASCII art) to illustrate architecture decisions.

高级最佳实践：

理解输出风格与其他扩展机制的区别非常重要：输出风格修改系统提示、始终生效；技能是按需加载的任务指令；CLAUDE.md 是始终存在的上下文补充。最佳实践是用输出风格控制"Claude 如何说"，用技能控制"Claude 做什么"，用 CLAUDE.md 提供"Claude 需要知道什么"。变更保存在 .claude/settings.local.json，也可直接编辑其他级别设置文件中的 outputStyle 字段。

5. 适用角色

初学者 / 学生： 使用 learning 风格，让 Claude 变成交互式编程导师——不仅帮你写代码，还要求你自己实践关键部分，加速学习。

经验开发者： 使用默认风格或创建极简自定义风格，获得简洁高效的输出，减少冗余解释。

技术 Lead / 导师： 使用 explanatory 风格或创建架构师风格，在代码审查和设计讨论时获得详细的决策背景和权衡分析。

非工程人员（产品、设计）： 创建自定义输出风格关闭编码指令，让 Claude 专注于文档编写、数据分析或项目管理任务。

七、使用钩子自动化工作流（Hooks）

1. 是什么

钩子（Hooks）是在 Claude Code 生命周期特定节点执行的用户定义 shell 命令，提供确定性的行为控制——确保某些操作始终发生，而非依赖 LLM 的判断。钩子支持丰富的事件类型：SessionStart（会话开始/恢复/压缩后）、PreToolUse（工具执行前，可阻止）、PostToolUse（工具执行后）、Notification（通知时）、Stop（Claude 完成响应时）、ConfigChange（配置变更时）等。除了命令型钩子外，还有提示型（type: "prompt"，使用 Claude 模型判断）和代理型（type: "agent"，生成子代理验证条件）。

2. 怎么用

最快的方式是运行 /hooks 进入交互式菜单，选择事件、配置匹配器和命令。也可以直接在配置文件中编写：

{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit|Write",
        "hooks": [
          {
            "type": "command",
            "command": "jq -r '.tool_input.file_path' | xargs npx prettier --write"
          }
        ]
      }
    ]
  }
}

钩子通过 stdin 接收 JSON 事件数据，通过退出码控制行为：0 = 继续，2 = 阻止（stderr 内容反馈给 Claude），其他 = 继续但记录。配置文件位置：~/.claude/settings.json（所有项目）、.claude/settings.json（单项目共享）、.claude/settings.local.json（单项目私有）。

3. 使用场景与痛点

钩子解决的核心痛点是手动重复操作和依赖 LLM 判断的不可靠性。典型场景包括：每次编辑后自动格式化（PostToolUse + Edit|Write 匹配器 + Prettier）、保护敏感文件不被修改（PreToolUse 检查文件路径拒绝 .env、package-lock.json）、桌面通知（Notification 事件触发 osascript/notify-send）、压缩后重新注入关键上下文（SessionStart + compact 匹配器）、审计配置变更（ConfigChange 事件记录到日志文件）。

4. 使用示例

入门示例——桌面通知：

macOS:

{
  "hooks": {
    "Notification": [
      {
        "matcher": "",
        "hooks": [
          {
            "type": "command",
            "command": "osascript -e 'display notification \"Claude Code needs your attention\" with title \"Claude Code\"'"
          }
        ]
      }
    ]
  }
}

保存到 ~/.claude/settings.json，之后每次 Claude 等待输入时都会收到系统通知。

进阶示例——保护敏感文件 + 自动格式化：

创建 .claude/hooks/protect-files.sh 脚本，从 stdin 读取 JSON，用 jq 提取 tool_input.file_path，检查是否匹配 .env、package-lock.json、.git/ 等受保护模式，匹配则 exit 2 阻止。同时配置 PostToolUse 钩子在每次 Edit/Write 后自动运行 Prettier。这样实现了"阻止 + 后处理"的双层自动化。

高级最佳实践——提示型和代理型钩子：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "prompt",
            "prompt": "Check if all tasks are complete. If not, respond with {\"ok\": false, \"reason\": \"what remains to be done\"}."
          }
        ]
      }
    ]
  }
}

提示型钩子（type: "prompt"）默认使用 Haiku 模型做单轮判断，返回 "ok": true 继续或 "ok": false 阻止并给出原因。代理型钩子（type: "agent"）则生成一个可以读取文件、运行命令的子代理来验证条件，适合需要检查实际代码状态的场景（如验证测试是否通过后才允许 Claude 停止）：

{
  "hooks": {
    "Stop": [
      {
        "hooks": [
          {
            "type": "agent",
            "prompt": "Verify that all unit tests pass. Run the test suite and check the results. $ARGUMENTS",
            "timeout": 120
          }
        ]
      }
    ]
  }
}

其他高级实践：使用结构化 JSON 输出实现更精细的 PreToolUse 控制（permissionDecision 支持 allow / deny / ask 三种行为）、防止 Stop 钩子无限循环（检查 stop_hook_active 字段）、注意 shell profile 中的 echo 语句会污染 JSON 输出（用 [[ $- == *i* ]] 包裹只在交互式 shell 执行的输出）。

5. 适用角色

个人开发者： 从通知钩子和自动格式化钩子开始。把 Notification 钩子保存到 ~/.claude/settings.json 让所有项目都能收到桌面提醒；把 PostToolUse 格式化钩子放到项目的 .claude/settings.json 确保代码风格一致。

团队开发者： 创建项目级钩子保护关键文件（.env、lock 文件、配置文件），防止 Claude 意外修改。将钩子脚本（如 protect-files.sh）提交到版本控制，团队成员自动获得相同的保护规则。

Tech Lead / 质量工程师： 使用提示型和代理型钩子实施质量门禁——Stop 钩子验证所有任务是否完成、测试是否通过。使用 PreToolUse 钩子对 Bash 命令进行安全审查（如阻止 rm -rf、DROP TABLE 等危险操作）。

DevOps 工程师： 在 CI/CD 环境中使用 SessionStart 钩子注入环境上下文（当前分支、最近提交、部署目标）。使用 ConfigChange 钩子记录配置变更审计日志满足合规要求。注意：PermissionRequest 钩子在非交互模式（-p）下不会触发，自动化场景需用 PreToolUse 替代。

八、程序化使用（Programmatic Usage / Agent SDK）

1. 是什么

Agent SDK 将 Claude Code 的全部能力——工具调用、代理循环和上下文管理——封装为可编程的接口。通过 CLI 的 -p（--print）标志可以非交互式运行 Claude Code，也有 Python 和 TypeScript 的 SDK 包提供结构化输出、工具审批回调和原生消息对象。这使得 Claude Code 可以嵌入到脚本、CI/CD 流水线和自动化工作流中。

2. 怎么用

基本用法——传入 -p 标志和提示：

claude -p "What does the auth module do?"

核心 CLI 选项：

# 结构化 JSON 输出（包含 result、session_id、metadata）
claude -p "Summarize this project" --output-format json

# 符合特定 schema 的结构化输出
claude -p "Extract function names from auth.py" \
  --output-format json \
  --json-schema '{"type":"object","properties":{"functions":{"type":"array","items":{"type":"string"}}}}'

# 流式输出（实时 token 流）
claude -p "Explain recursion" --output-format stream-json --verbose --include-partial-messages

# 自动批准工具
claude -p "Run tests and fix failures" --allowedTools "Bash,Read,Edit"

# 自定义系统提示
gh pr diff "$1" | claude -p --append-system-prompt "You are a security engineer. Review for vulnerabilities." --output-format json

# 继续对话
claude -p "Review this codebase for performance issues"
claude -p "Now focus on database queries" --continue

# 恢复特定会话
session_id=$(claude -p "Start a review" --output-format json | jq -r '.session_id')
claude -p "Continue that review" --resume "$session_id"

3. 使用场景与痛点

程序化使用解决的核心痛点是 Claude Code 只能通过交互式终端使用的局限性。典型场景包括：CI/CD 中的自动代码审查（PR 提交时自动运行 Claude 审查并输出 JSON 结果）、自动化测试修复（检测到测试失败后自动运行 Claude 修复）、批量代码分析（脚本遍历多个仓库执行分析）、自动提交（审查暂存变更并生成提交消息）、与其他工具集成（将 Claude 输出通过管道传递给 jq、grep 等工具）。

--allowedTools 使用权限规则语法支持前缀匹配（如 Bash(git diff *) 允许所有以 git diff 开头的命令），--append-system-prompt 追加指令保留默认行为，--system-prompt 完全替换系统提示。注意：用户调用的技能（如 /commit）和内置命令只在交互模式可用，-p 模式需直接描述任务。

4. 使用示例

入门示例——自动生成提交：

claude -p "Look at my staged changes and create an appropriate commit" \
  --allowedTools "Bash(git diff *),Bash(git log *),Bash(git status *),Bash(git commit *)"

Claude 审查暂存变更，生成提交消息并创建提交。Bash(git diff *) 中的 * 前有空格，确保只匹配 git diff 开头的命令而不匹配 git diff-index。

进阶示例——CI/CD 中的安全审查：

#!/bin/bash
# .github/scripts/security-review.sh
PR_NUMBER=$1
REVIEW=$(gh pr diff "$PR_NUMBER" | claude -p \
  --append-system-prompt "You are a security engineer. Review for vulnerabilities. Output severity ratings." \
  --output-format json \
  --allowedTools "Read,Grep,Glob")

# 提取结果并发布评论
RESULT=$(echo "$REVIEW" | jq -r '.result')
gh pr comment "$PR_NUMBER" --body "## Security Review\n$RESULT"

高级最佳实践——流式输出 + 会话链 + Schema 约束：

# 流式显示 token（用于实时界面）
claude -p "Write a poem" --output-format stream-json --verbose --include-partial-messages | \
  jq -rj 'select(.type == "stream_event" and .event.delta.type? == "text_delta") | .event.delta.text'

# 会话链：捕获 session_id 实现多轮自动化
session_id=$(claude -p "Analyze the auth module" --output-format json | jq -r '.session_id')
claude -p "Now suggest improvements" --resume "$session_id" --output-format json
claude -p "Implement the top 3 improvements" --resume "$session_id" --allowedTools "Read,Edit,Bash"

# Schema 约束输出（结果在 structured_output 字段）
claude -p "Analyze code complexity" --output-format json \
  --json-schema '{"type":"object","properties":{"files":{"type":"array","items":{"type":"object","properties":{"path":{"type":"string"},"complexity":{"type":"number"},"issues":{"type":"array","items":{"type":"string"}}}}}}}'

对于更复杂的需求（结构化输出、工具审批回调、原生消息对象），使用 Python 或 TypeScript SDK 包而非 CLI。

5. 适用角色

DevOps / CI 工程师： 这是最核心的目标用户群。在 GitHub Actions、GitLab CI/CD 中集成 Claude Code 实现自动代码审查、测试修复、安全扫描。使用 --output-format json 和 --json-schema 获得可解析的结构化输出以供流水线消费。

脚本自动化工程师： 用 shell 脚本或 Python/TypeScript SDK 构建批量处理工具——遍历多个仓库执行代码分析、生成报告、批量重构。使用 --continue 和 --resume 管理多轮对话。

平台工程师： 构建内部开发工具时将 Claude Code 作为后端服务集成。使用 TypeScript/Python SDK 获得更好的编程控制（工具审批回调、消息流处理）。

个人开发者： 将常用的 Claude Code 操作封装为 shell alias 或脚本——一键审查、一键提交、一键修复测试。例如：alias review='claude -p "Review my recent changes" --allowedTools "Read,Grep,Glob,Bash"'。

九、通过 MCP 连接外部工具

1. 是什么

Model Context Protocol（MCP）是一个开源标准协议，让 Claude Code 能够连接到外部的工具、数据库和 API。MCP 服务器作为中间层，将外部服务的能力暴露为 Claude 可以调用的工具。这意味着 Claude 不再局限于本地文件和终端操作，可以直接与 GitHub、Jira、Slack、数据库、监控系统等交互。Claude Code 本身也可以作为 MCP 服务器被其他应用连接。

2. 怎么用

三种添加 MCP 服务器的方式：

# 方式1：HTTP 远程服务器（推荐）
claude mcp add --transport http notion https://mcp.notion.com/mcp

# 带认证头
claude mcp add --transport http secure-api https://api.example.com/mcp \
  --header "Authorization: Bearer your-token"

# 方式2：SSE 远程服务器（已弃用，优先用 HTTP）
claude mcp add --transport sse asana https://mcp.asana.com/sse

# 方式3：stdio 本地服务器
claude mcp add --transport stdio --env AIRTABLE_API_KEY=YOUR_KEY airtable \
  -- npx -y airtable-mcp-server

# 管理服务器
claude mcp list                    # 列出所有
claude mcp get github              # 查看详情
claude mcp remove github           # 删除
/mcp                               # 在 Claude Code 内查看状态和认证

三种作用域：local（默认，当前项目当前用户）、project（通过 .mcp.json 共享给团队）、user（跨所有项目）。使用 --scope 标志指定。

3. 使用场景与痛点

MCP 解决的核心痛点是 Claude Code 与外部服务的割裂。没有 MCP 时，你需要手动在 Claude Code 和其他工具之间来回切换——打开 Jira 看需求、打开 GitHub 提 PR、打开 Sentry 查错误。有了 MCP，这些操作都可以在 Claude Code 内自然语言完成。具体场景举例：从 Jira issue 描述直接实现功能并在 GitHub 创建 PR、查询 Sentry 监控数据和 Statsig 使用统计来分析特性表现、直接查询 PostgreSQL 数据库找到符合条件的用户、根据 Figma 设计稿更新邮件模板、为反馈会议创建 Gmail 邀请草稿。

4. 使用示例

入门示例——连接 GitHub：

# 添加 GitHub MCP 服务器
claude mcp add --transport http github https://api.githubcopilot.com/mcp/

# 在 Claude Code 中认证
> /mcp     # 选择 "Authenticate" for GitHub

# 开始使用
> "Review PR #456 and suggest improvements"
> "Create a new issue for the bug we just found"
> "Show me all open PRs assigned to me"

进阶示例——连接数据库 + 项目级共享配置：

# 添加 PostgreSQL（项目级共享）
claude mcp add --transport stdio --scope project db \
  -- npx -y @bytebase/dbhub \
  --dsn "postgresql://readonly:pass@prod.db.com:5432/analytics"

这会在项目根目录创建 .mcp.json 文件，提交到版本控制后团队成员自动获得数据库访问。之后可以自然语言查询："What's our total revenue this month?" "Find customers who haven't purchased in 90 days."

.mcp.json 支持环境变量扩展，可以避免硬编码敏感信息：

{
  "mcpServers": {
    "api-server": {
      "type": "http",
      "url": "${API_BASE_URL:-https://api.example.com}/mcp",
      "headers": { "Authorization": "Bearer ${API_KEY}" }
    }
  }
}

高级最佳实践——MCP Tool Search + 企业管控 + OAuth 预配置：

当配置了大量 MCP 服务器时，工具定义可能占用超过 10% 的上下文窗口。MCP Tool Search 会自动启用按需加载——Claude 使用搜索工具发现相关 MCP 工具，只加载实际需要的工具。可通过 ENABLE_TOOL_SEARCH 环境变量控制（auto / auto:5 / true / false）。

对于需要预配置 OAuth 凭据的服务器：

claude mcp add --transport http \
  --client-id your-client-id --client-secret --callback-port 8080 \
  my-server https://mcp.example.com/mcp

企业管控方面，IT 管理员可以通过 managed-mcp.json（部署在系统目录）实现独占控制，或通过 allowedMcpServers / deniedMcpServers 策略实现灵活的允许/拒绝列表控制。支持按服务器名称、命令和 URL 模式三种方式匹配。

5. 适用角色

全栈开发者： 安装 GitHub、数据库、Figma 等常用 MCP 服务器，让 Claude 直接在编码过程中查询需求、提交 PR、查看设计稿，消除上下文切换。优先使用官方市场中的预配置 MCP 插件（如 /plugin install github@claude-plugins-official）而非手动配置。

数据工程师 / 分析师： 连接 PostgreSQL、BigQuery 等数据库 MCP 服务器，用自然语言查询数据、生成报告。配合数据科学子代理使用效果更佳。

团队 Lead： 使用项目级 .mcp.json 配置团队共享的 MCP 服务器（Jira、Slack、GitHub）。确保敏感凭据通过环境变量注入而非硬编码。使用 --scope project 时 Claude Code 会自动提示团队成员确认是否信任。

企业 IT 管理员： 通过 managed-mcp.json 部署组织批准的 MCP 服务器集合，使用 allowedMcpServers 白名单限制用户只能添加批准的服务器，使用 deniedMcpServers 黑名单阻止特定危险服务器。注意拒绝列表优先级高于允许列表。

MCP 服务器开发者： 利用 MCP Tool Search 的特性，为你的服务器编写清晰的 server instructions，帮助 Claude 理解何时搜索你的工具。Claude Code 也可以通过 claude mcp serve 作为 MCP 服务器被其他应用（如 Claude Desktop）连接。

十、故障排除（Troubleshooting）

1. 是什么

故障排除是 Claude Code 提供的系统诊断和问题解决指南，涵盖安装问题、认证与权限问题、性能与稳定性问题以及 IDE 集成问题。Claude Code 内置了 /doctor 诊断命令，可以检查安装状态、搜索功能、自动更新、配置文件有效性、MCP 服务器状态、上下文使用量等多项指标。

2. 怎么用

首要诊断工具：

# 运行内置诊断
/doctor

# 调试模式启动（显示详细执行信息）
claude --debug

# 查看版本
claude --version

# 报告 bug（直接提交给 Anthropic）
/bug

# 切换详细模式查看钩子输出
Ctrl+O

常见安装修复：

# PATH 问题修复（macOS/Linux）
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 检查冲突安装
which -a claude

# 检查目录权限
test -w ~/.local/bin && echo "writable" || echo "not writable"

# 检查缺失的共享库（Linux）
ldd $(which claude) | grep "not found"

# 低内存服务器添加 swap
sudo fallocate -l 2G /swapfile
sudo chmod 600 /swapfile && sudo mkswap /swapfile && sudo swapon /swapfile

# 搜索功能修复
brew install ripgrep   # macOS
sudo apt install ripgrep   # Ubuntu/Debian

认证修复：

# 重新认证
/logout
# 关闭 Claude Code，重新启动
claude

# WSL2 中浏览器无法打开时设置 BROWSER
export BROWSER="/mnt/c/Program Files/Google/Chrome/Application/chrome.exe"

# 企业代理 TLS 问题
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

3. 使用场景与痛点

故障排除解决的核心痛点是安装和配置过程中遇到的各种环境差异问题。最常见的痛点包括：

安装后 command not found——安装目录未加入 PATH，根据平台（macOS/Linux/Windows）使用不同的修复方法。安装脚本返回 HTML——通常是区域不可用或网络问题，可以用 Homebrew（macOS/Linux）或 WinGet（Windows）作为替代安装方式。TLS/SSL 错误——企业代理执行 TLS 检查导致证书链断裂，需设置 NODE_EXTRA_CA_CERTS。Linux 低内存服务器安装被 OOM Killer 终止——需至少 4GB RAM 或添加 swap 空间。WSL 中 Node.js 路径冲突——Windows 和 Linux 的 npm/node 安装互相干扰，需确保 nvm 正确加载。搜索工具不工作——需安装系统级 ripgrep 并设置 USE_BUILTIN_RIPGREP=0。

4. 使用示例

入门示例——安装后基础诊断：

# 1. 检查是否安装成功
claude --version

# 2. 如果 command not found，检查 PATH
echo $PATH | tr ':' '\n' | grep local/bin

# 3. 如果 PATH 缺失，添加
echo 'export PATH="$HOME/.local/bin:$PATH"' >> ~/.zshrc
source ~/.zshrc

# 4. 如果有多个安装，检查并清理
which -a claude
npm uninstall -g @anthropic-ai/claude-code   # 移除 npm 安装

进阶示例——企业网络环境排查：

# 1. 检查网络连通性
curl -sI https://storage.googleapis.com

# 2. 如果被防火墙阻止，配置代理
export HTTP_PROXY=http://proxy.example.com:8080
export HTTPS_PROXY=http://proxy.example.com:8080

# 3. 如果 TLS 证书问题，设置企业 CA 证书
export NODE_EXTRA_CA_CERTS=/path/to/corporate-ca.pem

# 4. 认证失败时完整重置
/logout
# 重启 Claude Code
claude

# 5. 如果 403 Forbidden，检查账户角色
# Console 用户需确认有 "Claude Code" 或 "Developer" 角色

高级最佳实践——全面诊断与配置重置：

# 运行完整诊断
/doctor
# 检查：安装类型/版本/搜索功能、自动更新状态、settings 文件有效性、
# MCP 服务器配置、快捷键配置、上下文使用警告、插件和代理加载错误

# 性能优化
/compact                          # 减少上下文大小
# 在 .gitignore 中排除大型构建目录

# 彻底重置（慎用）
rm ~/.claude.json                 # 重置全局状态
rm -rf ~/.claude/                 # 重置用户设置
rm -rf .claude/                   # 重置项目设置
rm .mcp.json                      # 重置项目 MCP 配置

# WSL2 JetBrains IDE 检测问题
# 方案1：配置防火墙
# 在 PowerShell(管理员) 中：
New-NetFirewallRule -DisplayName "Allow WSL2" -Direction Inbound -Protocol TCP -Action Allow -RemoteAddress 172.21.0.0/16

# 方案2：切换 WSL2 网络模式
# 在 .wslconfig 中添加：
[wsl2]
networkingMode=mirrored

# Docker 安装问题
# 设置 WORKDIR 避免扫描整个文件系统
WORKDIR /tmp
RUN curl -fsSL https://claude.ai/install.sh | bash

钩子调试：Stop 钩子无限循环时检查 stop_hook_active 字段；JSON 解析失败时检查 shell profile 中的无条件 echo 语句（用 [[ $- == *i* ]] 包裹）；使用 Ctrl+O 切换详细模式查看钩子输出。

5. 适用角色

所有用户（安装问题）： 安装是所有人都会遇到的第一道门槛。记住两个关键命令：claude --version 验证安装成功，/doctor 运行完整诊断。如果原生安装失败，Homebrew（macOS/Linux）和 WinGet（Windows）是可靠的替代方案。

企业用户 / VPN 环境用户： 最常遇到 TLS 错误和代理问题。向 IT 部门获取企业 CA 证书文件路径，设置 NODE_EXTRA_CA_CERTS 和 HTTPS_PROXY。如果使用 Console 账户，确认有正确的角色授权。

WSL 用户： 面临最多的兼容性问题——Node.js 路径冲突（确保 which npm 和 which node 指向 Linux 路径）、浏览器打开失败（设置 BROWSER 环境变量）、JetBrains IDE 检测问题（配置防火墙或切换 mirrored 网络模式）、sandbox 依赖缺失（安装 bubblewrap 和 socat）。WSL1 不支持 sandbox。

Linux 服务器管理员： 低内存服务器（<4GB）需要提前添加 swap 空间。Alpine Linux 等 musl 系统需安装 libgcc libstdc++ ripgrep。用 ldd /bin/ls 确认系统使用 glibc 还是 musl，避免二进制变体不匹配。ARM 服务器如果收到 x86 二进制文件会报 "Illegal instruction"，用 uname -m 确认架构。

Docker 用户： 安装时设置 WORKDIR /tmp 避免从根目录扫描导致挂起，Docker Desktop 构建时增加内存限制（docker build --memory=4g .）。

总结：功能对比与选择指南

功能核心定位最适合谁使用门槛
子代理隔离的专项任务执行所有开发者低（/agents 交互创建）
代理团队多实例并行协作高级工程师、Tech Lead高（实验性功能）
插件打包和分发扩展团队 Lead、平台工程师中
插件市场发现和安装扩展所有用户低（/plugin 浏览安装）
技能指令和知识扩展所有开发者低（创建 SKILL.md）
输出风格响应方式定制初学者、非工程人员低（/output-style 切换）
钩子确定性自动化DevOps、质量工程师中（需要 shell 脚本能力）
程序化使用CI/CD 和脚本集成DevOps、CI 工程师中（需要 CLI/SDK 经验）
MCP外部工具和数据连接全栈开发者、数据分析师中（需要配置服务器）
故障排除问题诊断和修复所有用户低（/doctor 一键诊断）

推荐的入门路径： 首先安装代码智能插件获得 LSP 增强 → 创建 1-2 个常用子代理（如代码审查器、调试器） → 配置桌面通知钩子和自动格式化钩子 → 连接常用 MCP 服务器（GitHub、数据库） → 根据团队需求将配置打包为插件共享。

avatar
文章
阅读
粉丝