本文将详细介绍 Agent Teams 的启用方式、使用方法、最佳实践以及与 Subagents 的区别。

Agent Teams 概述

什么是 Agent Teams

Agent Teams 是一组并行工作的 Claude Code 实例，通过共享任务列表协调工作。每个队友都是完整的、独立的 Claude Code 会话，拥有自己的 context window。

核心组件：

与 Subagents 的区别

Agent Teams 和 Subagents 都支持并行工作，但运作方式不同：

架构对比图：

最佳用例

Agent Teams 最适合并行探索能增加真实价值的任务：

• 研究和审查：多个队友同时调查问题的不同方面，然后分享和质疑彼此的发现
• 新模块或功能：队友各自拥有独立的部分，不会相互干扰
• 使用竞争假设进行调试：队友并行测试不同的理论，更快收敛到答案
• 跨层协调：跨越前端、后端和测试的更改，每个由不同的队友负责

启用 Agent Teams

启用实验性功能

Agent Teams 默认禁用，需要通过环境变量启用：

方式一：设置环境变量

1
2
3
4
5

# Linux/macOS
export CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

# Windows PowerShell
$env:CLAUDE_CODE_EXPERIMENTAL_AGENT_TEAMS=1

方式二：在 settings.json 中配置

1
2
3
4
5

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

启动与控制 Agent Team

启动第一个 Agent Team

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

1
2

Create an agent team to review this PR. One teammate should focus on
security issues, another on performance, and a third on test coverage.

这个例子效果很好，因为三个角色是独立的，可以并行探索问题。

选择显示模式

Agent Teams 支持两种显示模式：

配置显示模式：

1
2
3
4
5
6
7
8

// settings.json
{
  "teammateMode": "auto"    // 自动选择：tmux 会话中用分割窗格，否则用 in-process
  // 或
  "teammateMode": "tmux"   // 强制使用分割窗格（需要 tmux 或 iTerm2）
  // 或
  "teammateMode": "in-process"  // 强制使用 in-process 模式
}

In-process 模式操作：

• Shift+Down：循环浏览队友
• Enter：查看队友会话
• Escape：中断队友当前轮次
• Ctrl+T：切换任务列表

Split-pane 模式要求：

• tmux：通过系统包管理器安装
• iTerm2：安装 it2 CLI，启用 iTerm2 → Settings → General → Magic → Enable Python API

指定队友和模型

可以明确指定团队结构：

1
2
3
4

Create a team with 3 teammates:
- A security reviewer using Opus
- A performance analyzer using Sonnet
- A test coverage checker using Haiku

要求计划批准

对于复杂或有风险的任务，要求队友在实施前进行规划：

1
2
3

Create a team to refactor the authentication system. Each teammate
should plan their approach first and wait for approval before
implementing changes.

队友在只读计划模式下工作，直到负责人批准。

直接与队友交谈

每个队友都是完整的独立会话：

• In-process 模式：用 Shift+Down 循环到队友，然后输入消息
• Split-pane 模式：点击队友窗格直接交互

任务分配与认领

共享任务列表协调整个团队：

任务状态：

• 待处理（Pending）
• 进行中（In Progress）
• 已完成（Completed）

任务依赖：
具有未解决依赖关系的待处理任务在这些依赖关系完成之前无法被认领。

分配方式：

• 负责人分配：告诉负责人将哪个任务分配给哪个队友
• 自我认领：完成任务后，队友自己选择下一个未分配的任务

关闭队友与清理团队

关闭特定队友：

1

Close the security-reviewer teammate

清理整个团队：

1

Clean up the team

使用 Hooks 强制质量门

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

// settings.json
{
  "hooks": {
    "TeammateIdle": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "scripts/check-work-quality.sh" }]
      }
    ],
    "TaskCompleted": [
      {
        "matcher": "",
        "hooks": [{ "type": "command", "command": "scripts/validate-completion.sh" }]
      }
    ]
  }
}

• TeammateIdle：队友即将空闲时运行。以代码 2 退出可发送反馈并保持队友工作
• TaskCompleted：任务被标记完成时运行。以代码 2 退出可阻止完成并发送反馈

Agent Teams 工作原理

启动方式

方式一：你请求一个团队
给 Claude 一个受益于并行工作的任务，并明确要求创建 agent team。

方式二：Claude 提议一个团队
如果 Claude 确定你的任务将受益于并行工作，它可能会建议创建一个团队，你在继续之前确认。

文件存储

配置文件包含 members 数组，其中有每个队友的名称、代理 ID 和代理类型。队友可以读取此文件发现其他团队成员。

权限

队友从负责人的权限设置开始。如果负责人使用 --dangerously-skip-permissions 运行，所有队友也会这样做。

生成后可以更改个别队友模式，但在生成时无法设置每个队友的模式。

Context 和通信

Context 加载：
队友生成时加载与常规会话相同的项目 context：

• CLAUDE.md
• MCP servers
• Skills
• 来自负责人的生成提示

注意：负责人的对话历史不会继承。

通信机制：

• 自动消息传递：消息自动传递给收件人，负责人不需要轮询更新
• 空闲通知：队友完成并停止时，自动通知负责人
• 共享任务列表：所有代理可看到任务状态并认领工作

消息类型：

• message：向特定队友发送消息
• broadcast：同时发送给所有队友（谨慎使用，成本随团队规模增加）

令牌使用

Agent Teams 使用明显更多的令牌。每个队友有自己的 context window，令牌使用量随活跃队友数量增加。

对于研究、审查和新功能工作，额外的令牌通常是值得的。对于日常任务，单个会话更具成本效益。

用例示例

并行代码审查

单个审查者往往一次只关注一种类型的问题。将审查标准分解为独立的域：

1
2
3
4
5
6
7

Create an agent team to review PR #42:
- Teammate 1: Focus exclusively on security vulnerabilities
- Teammate 2: Focus on performance issues and optimization opportunities
- Teammate 3: Focus on test coverage and test quality

Each teammate should review independently, then share findings
and critique each other's conclusions.

使用竞争假设进行调查

当根本原因不清楚时，让队友并行测试不同理论：

1
2
3
4
5
6
7
8
9

Create an agent team to investigate why users are experiencing
slow load times. Each teammate should pursue a different hypothesis:

- Teammate 1: Investigate database query performance
- Teammate 2: Investigate network latency and CDN issues
- Teammate 3: Investigate client-side rendering performance

Work in parallel, then share findings. Each teammate should also
try to disprove the others' hypotheses.

跨层功能开发

1
2
3
4
5
6

Create an agent team to implement the user profile feature:
- Teammate 1: Backend API endpoints and database schema
- Teammate 2: Frontend components and UI
- Teammate 3: Integration tests and documentation

Coordinate on the API contract first, then work in parallel.

最佳实践

给队友足够的 Context

队友不继承负责人的对话历史。在生成提示中包含特定于任务的详情：

1
2
3
4

Create a team to implement the payment flow.
Context: We're using Stripe API v2024, the checkout happens
in /src/checkout/, and we need to support both card and
bank transfer payments.

选择适当的团队规模

约束因素：

• 令牌成本线性增加
• 协调开销增加
• 收益递减

适当调整任务大小

等待队友完成

有时负责人开始自己实施任务而不是等待队友：

1
2

Wait for all teammates to finish their tasks before continuing.
Don't start implementing anything yourself.

从研究和审查开始

新手建议从不需要编写代码的任务开始：

• 审查 PR
• 研究库
• 调查错误

这些任务展示并行探索的价值，没有并行实施的协调挑战。

避免文件冲突

两个队友编辑同一文件会导致覆盖。分解工作使每个队友拥有不同的文件集：

1
2
3
4

Assign distinct file sets to each teammate:
- Teammate 1: src/api/* only
- Teammate 2: src/components/* only
- Teammate 3: tests/* only

监控和指导

检查队友进度，重定向不起作用的方法，综合发现。让团队无人值守运行太长时间增加浪费风险。

故障排除

队友未出现

可能原因和解决方案：

过多权限提示

队友权限请求会传递到负责人。预批准常见操作减少中断：

1
2
3
4
5
6

// settings.json
{
  "permissions": {
    "allow": ["Read(**)", "Bash(npm run:*)", "Bash(git status:*)"]
  }
}

队友在错误时停止

使用 Shift+Down（in-process）或点击窗格（分割模式）检查输出：

• 直接给予额外指示
• 生成替代队友继续工作

负责人过早关闭

告诉负责人继续：

1

Continue. Wait for all teammates to complete before closing the team.

孤立的 tmux 会话

列出并杀死由团队创建的会话：

1
2

tmux list-sessions
tmux kill-session -t <session-name>

当前限制

Agent Teams 是实验性功能，存在以下限制：

总结

Agent Teams 是 Claude Code 的高级特性，适合需要并行协作的复杂任务：

核心优势：

• 队友可以直接相互通信和协作
• 通过共享任务列表自我协调
• 并行探索增加真实价值

与 Subagents 选择指南：

最佳实践总结：

1. 从研究和审查任务开始熟悉 Agent Teams
2. 控制团队规模（2-4 队友最佳）
3. 给队友足够的任务 context
4. 避免文件冲突，分配不同的文件集
5. 监控进度，及时指导
6. 使用 hooks 强制质量门

通过合理使用 Agent Teams，可以让多个 Claude 实例像真正的团队一样协作，大幅提升复杂任务的效率。

本文将从创建方法、使用场景和最佳实践三个维度，全面介绍 Claude Code Sub-Agents 的使用。

如何创建 Sub-Agent

使用 /agents 命令（推荐方式）

/agents 命令提供了交互式界面来管理 subagents，这是推荐的创建方式：

1

/agents

在交互界面中可以：

• 查看所有可用的 subagents（内置、用户、项目和插件）
• 使用引导式设置或 Claude 生成创建新的 subagents
• 编辑现有 subagent 配置和工具访问权限
• 删除自定义 subagents

创建步骤示例：

1. 选择 Create new agent

2. 选择范围：User-level（用户级）或 Project-level（项目级）

3. 选择 Generate with Claude 让 Claude 自动生成配置

4. 描述你的 subagent，例如：

   1 2	A code improvement agent that scans files and suggests improvements for readability, performance, and best practices.

5. 选择工具权限（只读审查者只需选择 Read-only tools）

6. 选择模型（Sonnet 平衡能力和速度，Haiku 更快更便宜）

7. 保存后立即可用，无需重启

手动创建 YAML Frontmatter 文件

Subagent 文件使用 YAML frontmatter 进行配置，后跟 Markdown 格式的系统提示：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39

---
name: code-reviewer
description: Expert code reviewer. Use proactively after code changes.
model: sonnet
tools:
  - Read
  - Grep
  - Glob
  - Bash
---

You are a senior code reviewer with expertise in software best practices.

Your responsibilities:

1. Review code for quality, security, and maintainability
2. Identify potential bugs and performance issues
3. Suggest improvements with clear explanations

When reviewing:

- Focus on meaningful issues, not style nitpicks
- Explain WHY something is an issue
- Provide concrete suggestions for improvement
- Consider the context and purpose of the code

Format your output as:

## Summary

[Brief overview of changes reviewed]

## Issues Found

[List of issues with severity and location]

## Suggestions

[Actionable improvement recommendations]

文件存储位置与优先级

项目级 subagents（.claude/agents/）适合特定于代码库的 subagents，建议提交到版本控制让团队协作使用。

用户级 subagents（~/.claude/agents/）适合个人在所有项目中复用的 subagents。

完整配置字段说明

以下是 YAML frontmatter 支持的所有字段：

模型选择策略

• Haiku：快速、低延迟，适合只读探索、代码搜索
• Sonnet：平衡能力和速度，适合大多数分析任务
• Opus：最强能力，适合复杂推理任务
• inherit：继承主对话的模型（默认）

工具控制

使用 tools 字段（白名单）：

1
2
3
4
5

tools:
  - Read
  - Grep
  - Glob
  - Bash

使用 disallowedTools 字段（黑名单）：

1
2
3

disallowedTools:
  - Write
  - Edit

优先级：先应用 disallowedTools，再解析 tools。

持久化内存

通过 memory 字段启用跨会话的知识积累：

1

memory: project

Sub-Agent 使用场景

内置 Subagents

Claude Code 包含以下内置 subagents：

Explore Agent

• 模型：Haiku（快速、低延迟）
• 工具：只读工具（拒绝 Write 和 Edit）
• 用途：文件发现、代码搜索、代码库探索
• 调用方式：Claude 自动委托，支持三种彻底程度：quick、medium、very thorough

Plan Agent

• 模型：继承主对话
• 工具：只读工具
• 用途：Plan mode 下收集上下文的研究代理

General-purpose Agent

• 模型：继承主对话
• 工具：所有工具
• 用途：复杂研究、多步骤操作、代码修改

典型使用场景

隔离大量输出的操作

运行测试、获取文档、处理日志文件等操作会产生大量输出，消耗大量上下文。通过委托给 subagent，冗长的输出保留在 subagent 的上下文中，只有相关摘要返回到主对话。

1

Run the test suite in the background and report any failures

并行研究

对于独立的调查任务，可以同时启动多个 subagents：

1
2
3
4

In parallel:
1. Use the explore agent to find all API endpoint definitions
2. Use the explore agent to find all database schema files
3. Then compare them for consistency

链式工作流

对于多步骤工作流，可以按顺序使用 subagents：

1
2
3

1. Use code-reviewer to review the changes in src/auth/
2. Based on the review, implement the suggested improvements
3. Run tests to verify the fixes work

强制执行约束

通过限制 subagent 可用的工具来强制执行特定约束：

1
2
3
4
5
6
7
8

---
name: read-only-analyzer
description: Analyzes code without making any changes
tools:
  - Read
  - Grep
  - Glob
---

成本控制

将任务路由到更快、更便宜的模型：

1
2
3
4
5
6
7
8

---
name: quick-search
description: Fast code search using Haiku
model: haiku
tools:
  - Grep
  - Glob
---

调用方式

自动委托

Claude 根据任务描述和 subagent 的 description 字段自动决定是否委托。在描述中包含 “use proactively” 等短语可鼓励主动委托。

自然语言调用

1

Use the code-reviewer agent to review this PR

@-mention 调用

1

@code-reviewer review the changes in src/

会话级启动

1

claude --agent code-reviewer

或在 .claude/settings.json 中设置默认：

1
2
3

{
  "agent": "code-reviewer"
}

前台与后台运行

• 前台 subagents：阻塞主对话直到完成，权限提示和澄清问题会传递给你
• 后台 subagents：并发运行，你可以继续工作

启动后台任务的方式：

• 请求 Claude “run this in the background”
• 按 Ctrl+B 将运行中的任务放入后台

最佳实践

编写清晰的描述

Claude 使用 description 字段决定何时委托任务。描述应该清晰、具体：

1
2
3
4
5

# 好的描述
description: Expert code reviewer for security vulnerabilities. Use proactively after code changes to check for SQL injection, XSS, and other OWASP Top 10 issues.

# 差的描述
description: Reviews code

选择合适的范围

• 项目级：特定于代码库的 subagents，如了解项目架构的审查者
• 用户级：跨项目复用的通用 subagents，如通用的代码风格审查者
• CLI 定义：快速测试或自动化脚本

限制工具访问

遵循最小权限原则：

1
2
3
4
5
6
7
8
9
10
11
12
13

# 只读审查者
tools:
  - Read
  - Grep
  - Glob

# 允许修复的调试者
tools:
  - Read
  - Grep
  - Glob
  - Edit
  - Bash

利用持久化内存

在 subagent 的系统提示中包含内存维护指令：

1
2
3
4
5
6
7
8
9
10
11
12
13

---
name: project-expert
memory: project
---

Before starting any task, check your memory in .claude/agent-memory/project-expert/
for relevant patterns and architectural decisions.

After completing work, save important learnings to MEMORY.md:

- Code patterns discovered
- Common pitfalls identified
- Architectural decisions made

使用 Hooks 进行条件验证

当需要比 tools 字段更细粒度的控制时，使用 PreToolUse hooks：

1
2
3
4
5
6
7
8
9

---
name: db-query-validator
hooks:
  PreToolUse:
    - matcher: Bash
      hooks:
        - type: command
          command: scripts/validate-sql-readonly.sh
---

验证脚本示例：

1
2
3
4
5
6
7
8
9
10
11

#!/bin/bash
# 只允许只读 SQL 查询

COMMAND="$TOOL_INPUT_COMMAND"

if echo "$COMMAND" | grep -qiE "(INSERT|UPDATE|DELETE|DROP|CREATE|ALTER|TRUNCATE)"; then
  echo "Error: Only read-only SQL queries are allowed"
  exit 2  # 阻止操作
fi

exit 0  # 允许操作

选择模型的经济性

何时使用 Subagent vs 主对话

使用主对话：

• 任务需要频繁的来回交互或迭代优化
• 多个阶段共享大量上下文（规划 → 实现 → 测试）
• 做快速、针对性的更改
• 延迟很重要（subagents 需要时间收集上下文）

使用 Subagent：

• 任务产生大量你不需要在主上下文中的输出
• 想强制执行特定的工具限制或权限
• 工作是独立的，可以返回摘要

禁用特定 Subagents

在 settings.json 中：

1
2
3
4
5

{
  "permissions": {
    "deny": ["Agent(explore-agent)"]
  }
}

示例 Subagents

代码审查者

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36

---
name: code-reviewer
description: Expert code reviewer. Use proactively after code changes to review for quality, security, and best practices.
model: sonnet
tools:
  - Read
  - Grep
  - Glob
---

You are a senior code reviewer with 15 years of experience.

Review code for:

1. **Security**: SQL injection, XSS, auth issues, secrets in code
2. **Performance**: N+1 queries, inefficient algorithms, memory leaks
3. **Maintainability**: Code smell, complexity, naming conventions
4. **Best Practices**: SOLID principles, DRY, error handling

Output format:

## Summary

[Brief overview]

## Critical Issues

[Security vulnerabilities, bugs]

## Suggestions

[Improvement recommendations]

## Nitpicks

[Minor style suggestions]

调试者

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22

---
name: debugger
description: Debug agent that analyzes and fixes issues. Use when encountering bugs or errors.
model: sonnet
tools:
  - Read
  - Grep
  - Glob
  - Edit
  - Bash
---

You are a debugging specialist.

Workflow:

1. **Reproduce**: Understand the error and how to trigger it
2. **Analyze**: Use logs, stack traces, and code inspection to find root cause
3. **Fix**: Implement minimal, targeted fix
4. **Verify**: Run tests or reproduction steps to confirm fix

Always explain your reasoning before making changes.

数据科学家

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21

---
name: data-scientist
description: Data analysis specialist for CSV, JSON, and database queries. Use for data exploration, statistics, and visualization tasks.
model: sonnet
tools:
  - Read
  - Write
  - Bash
---

You are a data scientist with expertise in Python, SQL, and data analysis.

Capabilities:

- Analyze CSV, JSON, and structured data
- Write SQL queries for data extraction
- Create statistical summaries and visualizations
- Identify patterns and anomalies in data

Use Python with pandas, numpy, and matplotlib for analysis.
Output both findings and the code used to generate them.

总结

Subagents 是 Claude Code 的强大特性，通过以下方式提升开发效率：

1. 上下文隔离：将探索和实现保持在主对话之外，保留宝贵的上下文空间
2. 约束执行：通过限制工具访问强制执行安全边界
3. 配置复用：通过用户级 subagents 跨项目共享配置
4. 行为专业化：为特定领域使用专注的系统提示
5. 成本控制：将任务路由到更便宜的模型如 Haiku

创建 subagent 时，记住：

• 编写清晰的 description 让 Claude 知道何时使用
• 根据任务选择合适的工具权限
• 利用 memory 字段实现跨会话学习
• 使用 hooks 实现细粒度的条件控制

通过合理使用 subagents，你可以让 Claude Code 成为一个更加高效、安全的编程助手。

什么是 Skills？
Skills 是 Claude Code 的扩展机制，让你可以创建、管理和分享自定义能力。每个 Skill 是一个包含 SKILL.md 文件的目录，Claude 会将其添加到工具箱中。

核心价值：

• 自动化重复任务
• 添加领域专业知识
• 强制执行代码标准和最佳实践
• 加速项目脚手架和代码生成

文件结构

1
2
3
4
5
6

~/.claude/skills/<skill-name>/
├── SKILL.md          # 必需，主指令文件
├── templates/        # 可选，模板文件
├── examples/         # 可选，示例输出
├── scripts/          # 可选，脚本文件
└── docs/             # 可选，详细参考文档

Skills 存储位置：

SKILL.md 文件格式

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17

---
name: my-skill
description: 这个 skill 的用途说明
argument-hint: [参数提示]
disable-model-invocation: false
user-invocable: true
allowed-tools:
  - Read
  - Glob
model: claude-sonnet-4-20250514
context: fork
agent: Explore
---

# Skill 内容

这里是 Claude 执行的具体指令...

Frontmatter 字段说明：

Skill 类型

参考型（Reference Content）

• 添加知识供 Claude 应用
• 如：约定、模式、风格指南、领域知识
• 在对话上下文中内联运行

任务型（Task Content）

• 提供特定操作的步骤指令
• 如：部署、提交、代码生成
• 通常设置 disable-model-invocation: true 仅手动触发

参数传递

1
2
3
4
5
6
7
8
9
10
11

# 使用 $ARGUMENTS 接收所有参数

修复 GitHub issue $ARGUMENTS...

# 使用索引访问特定参数

修复组件 $ARGUMENTS[0]，从 $ARGUMENTS[1] 迁移到 $ARGUMENTS[2]

# 简写形式

修复组件 $0，从 $1 迁移到 $2

可用变量：

• $ARGUMENTS - 所有参数
• $ARGUMENTS[N] 或 $N - 第 N 个参数
• ${CLAUDE_SESSION_ID} - 当前会话 ID
• ${CLAUDE_SKILL_DIR} - Skill 目录路径

进阶模式

动态上下文注入

1
2
3
4
5
6
7
8

---
name: pr-summary
---

!gh pr diff $ARGUMENTS
!gh pr view $ARGUMENTS --json title,body

请总结以上 PR 内容...

!command 语法先执行 shell 命令，输出替换占位符。

子代理运行

1
2
3
4

---
context: fork
agent: Explore
---

• 创建隔离上下文
• Skill 内容成为子代理的 prompt
• 适合大规模代码库探索

视觉输出生成

• Skill 可捆绑运行 Python 等脚本
• 生成交互式 HTML 文件
• 如：依赖图、测试覆盖率报告、代码库可视化

内置 Bundled Skills

权限控制

禁用所有 Skills：

1

/permissions deny Skill

允许/拒绝特定 Skills：

1
2

/permissions allow Skill(review)
/permissions deny Skill(deploy *)

隐藏单个 Skill：

1

disable-model-invocation: true

常见问题排查

最佳实践

1. 清晰命名 - 使用描述性的 skill 名称
2. 精确描述 - description 决定 Claude 何时自动加载
3. 分离关注点 - 复杂 skill 用支持文件保持 SKILL.md 简洁
4. 版本控制 - 项目级 skills 提交到 .claude/skills/
5. 渐进增强 - 从 5-10 个 skills 开始，按需添加

实用示例

代码解释 Skill

创建 ~/.claude/skills/explain-code/SKILL.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35

---
name: explain-code
description: 使用可视化图表和类比解释代码工作原理
---

当用户询问某段代码如何工作时：

1. 首先用简单的语言解释代码的核心目的
2. 使用类比将概念与日常事物联系起来
3. 创建一个 ASCII 图表展示数据流和控制流
4. 标注关键的决策点和数据转换
5. 提供一个具体的使用场景示例

格式：

## 概述

[一句话描述]

## 类比

[将代码比作日常事物]

## 流程图

[ASCII 图表]

## 关键点

- [要点1]
- [要点2]

## 示例场景

[具体场景描述]

Git 提交 Skill

创建 ~/.claude/skills/git-commit/SKILL.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24

---
name: commit
description: 生成符合规范的 Git 提交信息
argument-hint: [可选的提交类型]
disable-model-invocation: true
---

根据当前暂存的更改生成提交信息：

1. 运行 `git diff --staged` 查看更改
2. 分析更改类型（feat/fix/docs/style/refactor/test/chore）
3. 生成符合 Conventional Commits 规范的提交信息

提交信息格式：

```
<type>(<scope>): <subject>

<body>

<footer>
```

$ARGUMENTS

代码审查 Skill

创建 ~/.claude/skills/code-review/SKILL.md：

1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61

---
name: review
description: 对代码进行全面审查，检查安全、性能和最佳实践
allowed-tools:
  - Read
  - Glob
  - Grep
---

对指定的代码进行审查：

## 审查维度

### 安全性

- SQL 注入风险
- XSS 漏洞
- 敏感信息泄露
- 输入验证

### 性能

- 不必要的循环
- 内存泄漏风险
- N+1 查询问题
- 缓存机会

### 代码质量

- 命名规范
- 代码复杂度
- 重复代码
- 注释完整性

### 最佳实践

- 设计模式应用
- 错误处理
- 测试覆盖

## 输出格式

```
## 审查报告：[文件名]

### 发现的问题

| 级别  | 位置    | 问题 | 建议 |
| ----- | ------- | ---- | ---- |
| ERROR | line:42 | ...  | ...  |
| WARN  | line:58 | ...  | ...  |

### 优点

- ...

### 总体评分：X/10

```

$ARGUMENTS

资源链接

官方资源：

• 官方文档：https://code.claude.com/docs/en/skills
• 最佳实践：https://platform.claude.com/docs/en/agents-and-tools/agent-skills/best-practices

社区资源：

• Claude Code Tresor：https://github.com/alirezarezvani/claude-code-tresor（开箱即用）
• Claude Skills Library：https://github.com/alirezarezvani/claude-skills（领域专家包）
• Skill Factory：https://github.com/alirezarezvani/claude-code-skill-factory（自定义构建）

现象

我们先看下下面这段代码

1
2
3
4
5

public static void main(String[] args) {
    RateLimiter rateLimiter = RateLimiter.create(10.0D);
    double rate = rateLimiter.getRate();
    System.out.println(rate);
}

直觉上最终会输出 10.0，实际最终也是输出了 10.0。

可是如果我们将上述代码中的 10.0D 变为 15.0D，结果会输出什么呢？

1
2
3
4
5

public static void main(String[] args) {
    RateLimiter rateLimiter = RateLimiter.create(15.0D);
    double rate = rateLimiter.getRate();
    System.out.println(rate);
}

执行后输出的值竟然是 14.999999999999998。看到这个结果我觉得非常的奇怪，毕竟直觉告诉我应该输出 15.0 才对。

刨根问底

看到这样的现象，我们首先就要从源码上分析一下，看一下 Guava 内部是如何处理的。

打开 RateLimiter.getRate() 方法，发现其返回的是抽象方法 doGetRate() 的值。

1
2
3
4
5

public final double getRate() {
    synchronized (mutex()) {
        return doGetRate();
    }
}

我们创建 RateLimiter 的实例时默认创建的是类型为 SmoothBursty 的对象，该类的 doGetRate() 方法实现如下：

1
2
3
4

@Override
final double doGetRate() {
    return SECONDS.toMicros(1L) / stableIntervalMicros;
}

这里竟然不是直接返回我们创建 RateLimiter 时设置的值，而是通过除法运算得来的。

继续分析 stableIntervalMicros 是怎么设值的。

1
2
3
4
5
6
7
8
9
10

/**
 * 该方法是创建 RateLimiter 时调用的方法
**/
@Override
final void doSetRate(double permitsPerSecond, long nowMicros) {
    resync(nowMicros);
    double stableIntervalMicros = SECONDS.toMicros(1L) / permitsPerSecond;
    this.stableIntervalMicros = stableIntervalMicros;
    doSetRate(permitsPerSecond, stableIntervalMicros);
}

至此结论已经非常清晰了：由于在创建 RateLimiter 时成员变量 stableIntervalMicros 便是通过简单的除法运算得来的，当 1000000 微秒（1 秒）不能够被传入的限流值除尽时 stableIntervalMicros 就已经丢失了精度，从而导致在这种情况下调用 doGetRate() 是不能够得到我们创建 RateLimiter 时传入的原始值的。

发散

Guava 为什么不在创建 RateLimiter 时把我们传入的原始值保存在一个成员变量里，调用 doGetRate() 方法时直接返回该成员变量的值呢？

我个人的理解可以从变量和方法命名上去分析，RateLimiter.create(double permitsPerSecond) 方法的变量名 permitsPerSecond 其含义是每秒产生多少令牌。而 RateLimiter.getRate() 从方法名以及 Guava 的注释上来看该方法的含义更倾向于提供产生令牌的实际速率。

总结

在使用一些三方的库甚至是 Java 本身提供的一些方法时要弄清楚其使用场景，尽量多验证一下各种边界值、特殊值的情况，不能盲目相信自己的直觉。