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

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

1. 是什么

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

2. 怎么用

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

yaml 复制代码

---
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 传递临时子代理：

bash 复制代码

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. 使用示例

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

yaml 复制代码

---
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."

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

yaml 复制代码

---
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 验证的数据库查询代理：

yaml 复制代码

---
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 中添加：

json 复制代码

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

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

sql 复制代码

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. 使用示例

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

sql 复制代码

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 综合所有发现。

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

vbnet 复制代码

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.

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

高级最佳实践：

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

arduino 复制代码

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. 怎么用

创建插件的步骤：

bash 复制代码

# 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 的完整插件：

perl 复制代码

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. 怎么用

bash 复制代码

# 浏览官方市场
/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. 使用示例

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

bash 复制代码

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

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

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

bash 复制代码

# 安装 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 文件：

bash 复制代码

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

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

yaml 复制代码

---
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 规范）：

yaml 复制代码

---
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 时会自动加载这个技能，确保遵循团队约定。

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

yaml 复制代码

---
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 确保只有用户手动触发。

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

yaml 复制代码

---
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. 怎么用

bash 复制代码

# 交互式选择
/output-style

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

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

yaml 复制代码

---
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. 使用示例

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

bash 复制代码

/output-style learning

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

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

yaml 复制代码

---
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 进入交互式菜单，选择事件、配置匹配器和命令。也可以直接在配置文件中编写：

json 复制代码

{
  "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:

json 复制代码

{
  "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。这样实现了"阻止 + 后处理"的双层自动化。

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

json 复制代码

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