Claude Code 进阶工具搭建文档

By - niubadomi
Posted on 4 7 月, 20264 7 月, 2026
Posted in Ubuntu

Claude Code 进阶工具搭建文档

搭建日期：2026-07-04
Claude Code 版本：2.1.179
目标项目：/opt/project/ai_tools

1. 需求规划

1.1 背景

Claude Code 原生提供了强大的扩展能力——Agent 体系、Skill 引擎、Hooks 系统——但这些能力需要主动配置才能发挥最大效用。本次搭建的目标是：零外部依赖，纯用 Claude Code 原生机制，构建一套开箱即用的进阶工具链。

1.2 目标拆解

序号	需求	目标	优先级
1	Custom Agents	创建 3 个专业 Agent，覆盖代码审查、Bug 搜索、测试生成	P0
2	Tmux Hooks	实现 Claude Code 与 tmux 的事件联动（状态显示、完成通知、权限告警）	P1
3	安全规则	用 hookify 插件创建文件编辑和命令执行的安全拦截规则	P1

1.3 选型理由

方案	为什么选它	为什么不选替代方案
Custom Agent（原生）	零安装、零配置、YAML 即可定义、Claude 自动识别触发	Hermes Agent 需要独立部署、维护成本高、功能重叠 80%
Hooks + 手写脚本	完全可控、无插件依赖、直接操作 tmux	hookify 只能做规则匹配，无法做复杂的状态通知逻辑
Hookify 规则	声明式配置、即时生效、无需重启	手写 PreToolUse hooks 也能实现，但 hookify 更简洁

2. 原理说明

2.1 Custom Agent 工作原理

用户输入 prompt
       │
       ▼
┌──────────────────┐
│  Claude Code     │  扫描所有注册的 Agent 的 description 字段
│  主进程          │  判断是否匹配当前用户意图
└──────┬───────────┘
       │ 匹配成功
       ▼
┌──────────────────┐
│  Subagent 进程    │  独立上下文，加载该 Agent 的 system prompt
│  (model: inherit) │  只拥有 tools 字段声明的工具
└──────┬───────────┘
       │
       ▼
  返回结果给主进程

关键机制：

Agent 注册：.claude/agents/*.md 目录下的所有 .md 文件被自动发现和注册
触发匹配：description 字段是唯一的触发判断依据——Claude Code 将其加载到上下文，用 LLM 判断是否匹配当前任务
模型继承：model: inherit 表示使用与父进程相同的模型，不额外消耗
工具隔离：tools 字段做最小权限——如 bug-hunter 只有 [Read, Grep, Glob, Bash]，不允许写文件

2.2 Hooks 系统原理

Claude Code 生命周期事件
       │
       ├── SessionStart    → 会话开始
       ├── UserPromptSubmit → 用户提交 prompt  ──→ tmux-status.sh（设置 working）
       ├── PreToolUse      → 工具调用前（可拦截）
       ├── PostToolUse     → 工具调用后
       ├── Notification    → 权限确认弹窗      ──→ tmux-permission-alert.sh（告警）
       ├── Stop            → 回复完成          ──→ tmux-notify.sh（通知 + 设置 idle）
       ├── StopFailure     → 回复失败
       └── SessionEnd      → 会话结束

关键机制：

Hooks 是同步阻塞的——脚本不退出，Claude Code 就卡住等待
因此所有脚本开头都有快速退出路径（if [[ -z "$TMUX" ]]; then exit 0; fi）
settings.json 中配置的 hooks 在会话启动时加载，修改后需要新开会话才生效
项目级 settings.json 优先级高于用户级 ~/.claude/settings.json

2.3 Hookify 规则原理

Claude Code PreToolUse 事件触发
       │
       ▼
┌──────────────────┐
│  Hookify 插件     │  读取所有 .claude/hookify.*.local.md
│  PreToolUse Hook │  逐条匹配 pattern / conditions
└──────┬───────────┘
       │ 匹配成功
       ▼
┌──────────────────┐
│  动作执行         │
│  · warn: 显示消息 │  → 消息追加到 Claude 上下文，LLM 看到警告
│  · block: 阻止    │  → 直接拒绝工具调用
└──────────────────┘

关键机制：

Hookify 是官方插件，已安装在你的系统中
规则文件的 event 字段决定了挂载到哪个 Hook 事件
规则文件修改后即时生效（下次工具调用时重新读取），不需要重启
action: warn 是温和模式：消息注入 Claude 上下文，LLM 自行决定是否继续
action: block 是强制模式：直接返回错误，操作被阻止

3. 具体实施

3.1 目录结构初始化

mkdir -p /opt/project/ai_tools/.claude/agents
mkdir -p /opt/project/ai_tools/.claude/hooks

创建了三个目录：

agents/ —— Agent 定义文件
hooks/ —— Hook 执行脚本
项目根 .claude/ —— Hookify 规则文件和 settings.json

3.2 创建 3 个 Custom Agent

3.2.1 bug-hunter（对抗性 Bug 搜索）

文件：.claude/agents/bug-hunter.md

设计思路：与其他 Agent 不同，这个 Agent 采用对抗性思维——假设代码有 bug，目标是把它们找出来。它不是风格审查工具，只报告有具体复现路径的实际 bug。

核心配置：

字段	值	理由
`model`	`inherit`	跟随主进程模型
`color`	`red`	红色 = 安全/危险相关
`tools`	`[Read, Grep, Glob, Bash]`	只读 + Bash（用于运行测试验证），不允许写文件

System Prompt 要点：

按严重程度分级：critical（数据丢失/安全）> high（崩溃/结果错误）> medium（边界条件错误）> low（表面但错误）
必须提供具体复现路径——不接受”可能”或”也许”
覆盖 12 类边界条件：null、空值、负数、溢出、并发、网络故障、注入字符串等

触发条件（description 中的匹配短语）：

“find bugs” / “hunt bugs” / “audit for bugs”
“adversarial review” / “break this code”
“edge case check” / “find edge cases”
主动触发：重大代码变更后自动审查

3.2.2 test-writer（测试自动生成）

文件：.claude/agents/test-writer.md

设计思路：测试应该验证行为而非实现细节。Agent 会先检测项目使用的测试框架，匹配现有风格，再生成测试。

核心配置：

字段	值	理由
`model`	`inherit`	跟随主进程模型
`color`	`green`	绿色 = 建设性/通过
`tools`	`[Read, Write, Grep, Glob, Bash]`	需要 Write 创建测试文件，Bash 运行测试验证

System Prompt 要点：

第一步：自动检测测试框架（jest/pytest/go test/等）
第二步：读取现有测试文件，匹配命名风格和断言模式
测试覆盖矩阵：正常路径 → 错误路径 → 边界值 → 状态序列 → 并发
“测试行为而非实现”——重构不应破坏测试
对外部依赖（API、数据库、文件系统）使用 Mock

触发条件：

“write tests” / “add tests” / “generate tests”
“test this” / “add unit tests”
主动触发：新函数/类/模块创建后无测试时自动建议

3.2.3 code-reviewer（代码质量 + 安全审查）

文件：.claude/agents/code-reviewer.md

设计思路：不是挑刺工具，而是建设性审查——每个问题都附带具体修复方案。审查维度覆盖正确性、安全性、可维护性、项目规范。

核心配置：

字段	值	理由
`model`	`inherit`	跟随主进程模型
`color`	`blue`	蓝色 = 分析/审查
`tools`	`[Read, Grep, Glob, Bash]`	只读分析，Bash 用于运行现有测试

System Prompt 要点：

四阶段审查流程：理解变更 → 读上下文 → 正确性检查 → 安全性检查 → 可维护性检查 → 规范检查
四个严重级别：Critical（安全/数据丢失，立即修）> High（结果错误，合并前修）> Medium（可维护性，强烈建议）> Low（风格，可选）
输出包含 Praise 部分——好代码同样值得标注
“匹配项目已有的风格，不要强加你的偏好”

触发条件：

“review code” / “code review” / “review this”
“check my code” / “CR this”
主动触发：非平凡代码变更后自动审查

3.3 Tmux 安装与配置

Tmux 是本项目中唯一的非 Claude Code 原生依赖，用于多窗格管理、会话持久化和状态栏集成。

sudo apt install -y tmux   # 安装（本环境：tmux 3.0a）

完整配置、快捷键说明和练习见 Tmux 高效配置。

设计要点：前缀键 Ctrl+a，主力快捷键全部 Alt 免前缀（Alt+h/v 分屏、Alt+方向键 移动窗格、Alt+Shift+方向键 调整大小、Alt+e 重命名、Alt+r 重载）。状态栏深灰底白字，右侧集成 Claude Code 状态指示器（通过 @claude-status 选项通信，5 秒刷新间隔）。

3.4 配置 Tmux Hooks

3.4.1 Hook 脚本

hooks/tmux-status.sh（挂载到 UserPromptSubmit）：

# 当用户提交 prompt 时触发
# 设置 tmux 用户选项 @claude-status = "working"
# 状态栏可以读取该选项显示工作状态

hooks/tmux-notify.sh（挂载到 Stop）：

# 当 Claude 完成回复时触发
# 1. 弹出 tmux display-message 通知（持续 3 秒）
# 2. 设置 @claude-status = "idle"

hooks/tmux-permission-alert.sh（挂载到 Notification）：

# 当 Claude 需要用户确认时触发
# 弹出 tmux display-message 警告（持续 5 秒）
# 设置 @claude-status = "needs_approval"

3.4.2 settings.json 配置

文件：.claude/settings.json

{
  "hooks": {
    "UserPromptSubmit": [{ "matcher": "", "hooks": [{
      "type": "command",
      "command": "/opt/project/ai_tools/.claude/hooks/tmux-status.sh"
    }]}],
    "Stop": [{ "matcher": "", "hooks": [{
      "type": "command",
      "command": "/opt/project/ai_tools/.claude/hooks/tmux-notify.sh"
    }]}],
    "Notification": [{ "matcher": "", "hooks": [{
      "type": "command",
      "command": "/opt/project/ai_tools/.claude/hooks/tmux-permission-alert.sh"
    }]}]
  }
}

设计要点：

所有 matcher 为空字符串——不筛选，所有触发都执行该 Hook
脚本使用绝对路径——避免工作目录变化的坑
每个事件配置为独立数组元素——可独立增删

3.5 创建 Hookify 安全规则

3.5.1 dangerous-commands（危险命令拦截）

文件：.claude/hookify.dangerous-commands.local.md

拦截模式：

rm\s+-rf        → rm -rf / rm  -rf
sudo\s+rm       → sudo rm ...
chmod\s+777     → chmod 777（世界可写）
chown\s+-R      → chown -R（递归改所有者）
dd\s+if=        → dd if=...（磁盘操作）
mkfs\.          → mkfs.ext4 等（格式化）
>\/dev\/sd      → 直接写入块设备

动作：warn（警告但不阻止——用户确认后可继续）

3.5.2 debug-statements（调试语句检查）

文件：.claude/hookify.debug-statements.local.md

拦截模式（conditions 双条件匹配——文件编辑 + 内容正则）：

console\.log\(        → JavaScript/TypeScript
console\.debug\(      → JavaScript/TypeScript
debugger\s*;          → JavaScript 断点
System\.out\.println  → Java
fmt\.Println          → Go
dump\(|dd\(           → PHP Laravel/Symfony

动作：warn

3.5.3 sensitive-files（敏感文件保护）

文件：.claude/hookify.sensitive-files.local.md

拦截模式（conditions 双条件匹配——文件路径 + 敏感文件名）：

\.env$        → .env
\.env\.       → .env.production / .env.local
credentials   → credentials.json / google-credentials.json
\.pem$        → private-key.pem
\.key$        → server.key
id_rsa        → SSH 私钥
\.secret      → .secret / app.secret
secrets\.ya?ml → secrets.yml / secrets.yaml
\.htpasswd    → Apache 密码文件

动作：warn

4. 使用说明

4.1 Custom Agent 使用

Agent 无需手动启动——Claude Code 自动在合适的时机调用。你只需要在对话中使用自然的语言：

bug-hunter 触发示例

你: "这段代码可能有 bug，帮我找一下"
你: "帮我做一次 adversarial review"
你: "我刚改了 auth.ts，帮我找找有没有引进新 bug"

输出格式示例：

### [Critical] SQL Injection in login handler
**File:** src/auth/login.ts:42
**Reproduction:** 发送 POST /login?user=admin'--
**Expected:** 拒绝非法用户名
**Actual:** SQL 注入，绕过了认证
**Root Cause:** user 参数直接拼接到 SQL
**Fix:** 使用参数化查询 `db.query('SELECT ... WHERE user = ?', [user])`

test-writer 触发示例

你: "帮我给这个函数写几个测试"
你: "刚才写的代码没有测试，补一下"
你: "这个 bug 修了，帮我写个回归测试防止复发"

输出格式示例：

检测到测试框架：jest (ts-jest)
测试风格：describe/it、AAA pattern

创建文件：src/utils/__tests__/formatDate.test.ts
共 8 个测试：
  ✓ 正常日期格式
  ✓ null 参数返回错误
  ✓ 空字符串返回错误
  ✓ 边界：Unix 时间戳为 0
  ✓ 边界：未来日期
  ✓ 时区处理
  ✓ 无效日期字符串
  ✓ 年份 9999 溢出

全部通过 ✅

code-reviewer 触发示例

你: "review 一下我刚才的改动"
你: "帮我 code review 这个 PR"
你: "这段代码能合并吗？"

输出格式示例：

## Code Review: src/api/users.ts

### Summary
新增用户 API 端点。整体结构清晰，错误处理基本到位。发现 1 个严重问题和 2 个建议。

### Issues Found
#### [Critical] Missing authentication on DELETE /users/:id
- **File:** src/api/users.ts:89
- **Problem:** 删除端点没有任何认证检查，任何人可以删除任意用户
- **Fix:** 添加 `authMiddleware` 并验证操作用户权限

#### [Medium] Repeated query logic
- **File:** src/api/users.ts:42, src/api/users.ts:78
- **Problem:** `SELECT * FROM users WHERE id = ?` 出现两次，逻辑重复
- **Fix:** 抽取为 `getUserById()` 辅助函数

### Highlights
- 错误处理非常完善，所有 Promise 都有 catch
- 输入验证使用了 zod schema，类型安全

### Verdict
❌ Changes requested — Critical issue must be fixed before merge

4.2 Tmux 使用

完整快捷键速查、会话管理和练习见 Tmux 高效配置。

常用操作速览：Alt+h/Alt+v 分屏、Alt+方向键 切窗格、Alt+c 新窗口、Alt+e 重命名、Alt+d 分离、Alt+r 重载配置。状态栏右侧显示 Claude Code 工作状态（🤖 工作中 / ✅ 空闲 / 🔔 需确认）。

4.3 Hookify 规则使用

日常行为

规则在后台静默工作——只有匹配时才会发送消息到 Claude 上下文：

# 例：你让 Claude 编辑 .env 文件
Claude（编辑 .env 前）:
⚠️ 检测到 .env 文件编辑...（Hookify 警告消息注入上下文）
我注意到这是敏感文件，让我确认它在 .gitignore 中...（Claude 读到警告并做出反应）

临时禁用某个规则

如果某条规则误报太频繁：

# 编辑对应文件，把 enabled: true 改为 enabled: false
# 即时生效，无需重启

---
name: warn-dangerous-commands
enabled: false   # ← 改为 false
event: bash
pattern: ...
---

添加新规则

复制模板创建新文件：

# 创建新规则文件
touch /opt/project/ai_tools/.claude/hookify.my-rule.local.md

模板：

---
name: my-rule-name
enabled: true
event: bash          # bash | file | stop | prompt | all
pattern: your_regex  # 或使用 conditions 列表
action: warn         # warn | block
---

你的提示消息（支持 Markdown）

保存后即时生效。

5. 注意点

5.1 通用注意事项

注意点	说明
Agent 不跨项目	Agent 文件在项目 `.claude/agents/` 下，只在该项目生效。要全局使用，复制到 `~/.claude/agents/`
Hooks 需新会话	`settings.json` 修改后，需要退出 Claude Code 并重新启动才会加载新配置
Hookify 即时生效	与 Hooks 不同，Hookify 规则在下次工具调用时即刻生效，无需重启
脚本必须可执行	Hook 脚本需要 `chmod +x`，否则会被跳过
绝对路径	Hook 脚本的 command 字段建议使用绝对路径，避免工作目录变化导致找不到脚本

5.2 Agent 注意事项

注意点	说明
description 是唯一的触发依据	LLM 通过 `description` 判断是否匹配。描述要具体，包含多种触发短语的同义表达
underrrigger > overtrigger	Agent 倾向于不触发（保守）。description 要”略带侵略性”，主动声明匹配场景
Agent 不继承对话历史	Subagent 是干净上下文，不会看到你的对话历史。如果它需要上下文，在 prompt 中说明
model: inherit 不保证同一模型	继承的是启动时的模型，如果主进程切换模型，已在运行的 Agent 不受影响
并发限制	同一时间运行的 Agent 数量有上限（通常 ≤10），超出会排队
Tools 最小权限	不给 Agent 不需要的工具。审查类 Agent 不需要 Write 权限

5.3 Tmux Hooks 注意事项

注意点	说明
不在 tmux 中时静默退出	使用 `${TMUX:-}` 引用变量；`set -u` 下用 `${TMUX:-}` 安全返回空字符串
`set -euo pipefail` 的影响	脚本启用严格模式，所有 tmux 变量引用必须用 `${VAR:-}` 兜底
Hook 脚本是阻塞的	脚本运行期间 Claude Code 等待其退出，所有脚本毫秒级完成
多 Session 互不干扰	每个 tmux session 有独立的 `@claude-status` 选项

5.4 Tmux 使用注意事项

详见Tmux 高效配置。

5.5 Hookify 规则注意事项

注意点	说明
warn 不是强制阻止	`action: warn` 只是把消息注入 Claude 上下文——LLM 仍有可能忽略警告继续执行
block 影响体验	`action: block` 完全阻止操作，可能打断工作流。建议只对高危操作（`rm -rf`）使用
正则表现	pattern 使用 Python 正则语法。在 YAML 中不需要引号时直接写，需要引号时注意转义
conditions 是 AND 关系	多条 conditions 必须全部满足才触发。不能表达”满足 A 或 B”的逻辑（需要写两条规则）
规则文件命名	必须以 `hookify.` 开头、`.local.md` 结尾，放在项目 `.claude/` 目录下
不要提交到 Git	`.local.md` 文件是本地配置。已创建 `.claude/.gitignore` 排除它们

5.6 性能影响

组件	性能影响
Custom Agents	可忽略。`description` 字段在 LLM 上下文中约 100 词，匹配失败时不启动 Agent 进程
Tmux Hooks	可忽略。每个脚本执行时间 < 10ms，在 Claude Code 的响应延迟中不可感知
Hookify 规则	极低。每条规则的正则匹配是微秒级别的。即使有 50+ 条规则也不影响性能

6. 附录：文件清单

新建文件

文件	用途	大小
`.claude/agents/bug-hunter.md`	对抗性 Bug 搜索 Agent	~3KB
`.claude/agents/code-reviewer.md`	代码质量 + 安全审查 Agent	~4KB
`.claude/agents/test-writer.md`	自动测试生成 Agent	~3KB
`.claude/hooks/tmux-notify.sh`	Stop 事件：完成通知 + 状态更新	~1.4KB
`.claude/hooks/tmux-status.sh`	UserPromptSubmit 事件：设置工作状态	~0.4KB
`.claude/hooks/tmux-permission-alert.sh`	Notification 事件：权限告警	~0.7KB
`.claude/settings.json`	Hook 配置（UserPromptSubmit / Stop / Notification）
`.claude/hookify.dangerous-commands.local.md`	危险命令警告规则
`.claude/hookify.debug-statements.local.md`	调试语句警告规则
`.claude/hookify.sensitive-files.local.md`	敏感文件编辑警告规则
`.claude/.gitignore`	排除 `*.local.md` 和 `settings.local.json`

用户目录（/home/user/）：

文件	用途
`~/.tmux.conf`	tmux 配置（鼠标、快捷键、Claude 状态栏、256 色）

修改文件

无。所有修改均为新增文件，未改动项目现有代码。

Agent 触发速查表

你想做什么	这样说
找 Bug	“帮我找 bug” / “adversarial review” / “edge case check”
代码审查	“review 一下” / “code review” / “帮我看下这段代码”
写测试	“帮我写测试” / “add tests” / “生成测试用例”

Hook 事件速查表

事件	脚本	效果	状态栏
`UserPromptSubmit`	`tmux-status.sh`	用户发送消息	`🤖 工作中`
`Stop`	`tmux-notify.sh`	Claude 完成回复，弹出 3 秒通知	`✅ 空闲`
`Notification`	`tmux-permission-alert.sh`	Claude 需要确认，弹出 5 秒告警	`🔔 需确认`

Tmux 快捷键速查表

完整速查和练习见 Tmux 高效配置。

Hookify 规则速查表

规则	拦截	动作
`dangerous-commands`	rm -rf, chmod 777, dd, mkfs	警告
`debug-statements`	console.log, debugger, fmt.Println, dump()	警告
`sensitive-files`	.env, .pem, credentials, id_rsa, secrets.yml	警告

Domi Zone

Claude Code 进阶工具搭建文档

目录

1. 需求规划

1.1 背景

1.2 目标拆解

1.3 选型理由

2. 原理说明

2.1 Custom Agent 工作原理

2.2 Hooks 系统原理

2.3 Hookify 规则原理

3. 具体实施

3.1 目录结构初始化

3.2 创建 3 个 Custom Agent

3.2.1 bug-hunter（对抗性 Bug 搜索）

3.2.2 test-writer（测试自动生成）

3.2.3 code-reviewer（代码质量 + 安全审查）

3.3 Tmux 安装与配置

3.4 配置 Tmux Hooks

3.4.1 Hook 脚本

3.4.2 settings.json 配置

3.5 创建 Hookify 安全规则

3.5.1 dangerous-commands（危险命令拦截）

3.5.2 debug-statements（调试语句检查）

3.5.3 sensitive-files（敏感文件保护）

4. 使用说明

4.1 Custom Agent 使用

bug-hunter 触发示例

test-writer 触发示例

code-reviewer 触发示例

4.2 Tmux 使用

4.3 Hookify 规则使用

日常行为

临时禁用某个规则

添加新规则

5. 注意点

5.1 通用注意事项

5.2 Agent 注意事项

5.3 Tmux Hooks 注意事项

5.4 Tmux 使用注意事项

5.5 Hookify 规则注意事项

5.6 性能影响

6. 附录：文件清单

新建文件

修改文件

Agent 触发速查表

Hook 事件速查表

Tmux 快捷键速查表

Hookify 规则速查表

Previous Article

Next Article