bookworm-smart-assistant/docs/zhihu-01-50-tips.md

# Claude Code 的 50 个隐藏技巧：用 Bookworm 路由系统释放全部潜力

---

## 开篇：你的 AI 助手为什么总感觉差点意思？

你是否遇到过这样的场景：

- 问 Claude Code "帮我优化这个 SQL 查询"，得到一段能跑但没考虑索引的代码
- 报一个 React 报错，收到一堆关于"可能原因"的猜测，但没有系统的排查步骤
- 说"帮我检查一下 API 安全性"，结果只收到几条通用建议

问题不在于 Claude Code 不够聪明，而在于它默认以"通用模式"回答每一个问题。就像你去问一位"什么都懂一点"的朋友，和去问一位深耕十年的领域专家，得到的答案质量是完全不同的。

**Bookworm Smart Assistant v5.6** 解决的正是这个问题。它在 Claude Code 原生能力之上，构建了一个由 **50 个专家技能 + 10 个智能体 + 17 个钩子**组成的语义路由系统。你用自然语言描述需求，系统自动识别意图，将你的请求路由到最合适的领域专家——而不是一个万金油。

这篇文章整理了 50 个真实可用的技巧，对应 50 个技能的核心使用场景，帮助你从"会用 Claude Code"进阶到"真正驾驭它"。

---

## Part 1：基础技巧（技巧 1-15）— 日常开发提效

### 技巧 1：让前端代码获得 React 19 级别的专家回答

**场景**：实现一个带加载态的数据获取组件

**普通问法**（通用模式）：
```
帮我写一个用户列表组件
```

**专家路由问法**（触发 `frontend-expert`）：
```
用 React 19 Server Components + Next.js 15 App Router 实现用户列表页，
包含骨架屏加载态和空状态处理
```

路由系统识别到 `React 19`、`Server Components`、`Next.js 15` 关键词，自动路由到 `frontend-expert`。这个技能深度集成了 React 19 的 Server Components、Actions 和 Compiler 最新范式，输出的代码不是"能跑"，而是"生产可用"：

```typescript
// app/users/page.tsx (Server Component — 服务端直接查库)
export default async function UsersPage() {
  const users = await db.user.findMany({ take: 20, orderBy: { createdAt: 'desc' } });

  if (users.length === 0) {
    return <EmptyState message="暂无用户数据" />;
  }

  return <UserList users={users} />;
}

// 骨架屏 (loading.tsx — Next.js 15 约定式)
export default function Loading() {
  return (
    <div className="space-y-3">
      {Array.from({ length: 5 }).map((_, i) => (
        <div key={i} className="h-16 bg-muted animate-pulse rounded-lg" />
      ))}
    </div>
  );
}
```

关键差异：专家知道 Next.js 15 有 `loading.tsx` 约定，无需手动管理加载状态。

---

### 技巧 2：区分"组件 Bug"和"前端 Bug"——正确触发调试模式

**核心消歧规则**：`React + Bug` → 路由到 `debugger-expert`，而非 `frontend-expert`

这是 Bookworm 27 条消歧规则之一。当你说"React 组件报错"时，系统优先判断这是一个**问题排查任务**，而不是开发任务：

```
# 触发 debugger-expert（推荐）
我的 useEffect 一直触发无限循环，控制台报 Warning: Maximum update depth exceeded

# 触发 frontend-expert（不推荐）
帮我写一个 useEffect
```

`debugger-expert` 使用六步排查方法论：复现 → 收集 → 缩小 → 假设 → 验证 → 根因。面对这个报错，它会直接告诉你根因：

```typescript
// ❌ 触发无限循环：依赖数组包含对象引用
useEffect(() => {
  fetchData(options);
}, [options]); // options 每次渲染都是新对象

// ✅ 修复：用 useMemo 稳定引用，或只依赖原始值
const stableOptions = useMemo(() => options, [options.page, options.size]);

useEffect(() => {
  fetchData(stableOptions);
}, [stableOptions]);
```

---

### 技巧 3：API 报错，别让安全问题被当成普通 Bug

**消歧规则**：`API + 安全` → 路由到 `security-expert`

```
# 这句话触发 security-expert，不是 backend-builder
我的 API 有 CORS 问题，同时想检查一下有没有安全漏洞
```

`security-expert` 的 OWASP Top 10 视角：

```python
# CORS 配置安全版本（避免通配符 origins）
from fastapi.middleware.cors import CORSMiddleware

ALLOWED_ORIGINS = [
    "https://yourdomain.com",
    "https://app.yourdomain.com",
]

app.add_middleware(
    CORSMiddleware,
    allow_origins=ALLOWED_ORIGINS,  # ❌ 不要用 ["*"]
    allow_credentials=True,
    allow_methods=["GET", "POST", "PUT", "DELETE"],
    allow_headers=["Authorization", "Content-Type"],
)
```

---

### 技巧 4：后端 API 开发，说明框架名自动匹配专家

触发 `backend-builder` 的关键词：`Node`、`Python`、`Go`、`REST`、`GraphQL`、`FastAPI`、`Express`

```
用 FastAPI 实现一个用户注册接口，需要参数校验和异步数据库操作
```

---

### 技巧 5：手机应用开发，跨平台框架自动识别

触发 `mobile-expert`：`React Native`、`Flutter`、`iOS`、`Android`、`移动端`

触发 `miniprogram-expert`：`微信小程序`、`支付宝小程序`、`Taro`、`uni-app`

系统会精确区分：说 `Flutter` 路由到 `mobile-expert`（精通 Dart 和原生集成），说 `微信小程序` 路由到 `miniprogram-expert`（了解微信审核规范和开放平台 API）。

---

### 技巧 6：第三方 API 对接，专用技能比通用更准确

触发 `api-integration-specialist`：`支付宝支付`、`微信支付`、`OAuth`、`Webhook`、`Stripe`

```
帮我实现微信支付的 JSAPI 下单，包含签名验证和回调处理
```

这个技能深度了解各平台的签名算法差异，不会把微信支付 v2 的 MD5 签名和 v3 的 HMAC-SHA256 混淆。

---

### 技巧 7：代码评审和 Bug 排查，一词之差路由到不同专家

**关键区别**：

| 你说的词 | 路由目标 | 专家模式 |
|---------|---------|---------|
| "帮我看看这段代码" | `reviewer-expert` | Code Review，关注可读性、技术债、重构建议 |
| "这段代码报错了" | `debugger-expert` | Bug 排查，关注根因和修复 |
| "上线前检查一下" | `project-audit-expert` | 全栈审计，覆盖安全/性能/可维护性 |

---

### 技巧 8：写单元测试，明确测试框架触发精确路由

触发 `tester-expert`：`Jest`、`Vitest`、`Playwright`、`pytest`、`TDD`、`单元测试`

```
用 Vitest 给这个 useAuth hook 写完整的单元测试，覆盖登录成功/失败/loading 三种状态
```

---

### 技巧 9：Git 操作不求人，专门的 Git 专家

触发 `git-operation-master`：`git rebase`、`merge conflict`、`分支管理`、`commit 规范`

```
# 这类操作不要问通用助手，容易得到错误建议
帮我解决这个 rebase conflict，我有 3 个文件冲突
```

`git-operation-master` 会给出安全的解决步骤，并解释每一步的意图，避免数据丢失。

---

### 技巧 10：正则表达式和 Shell 脚本，有专门的向导

触发 `regex-shell-wizard`：`正则`、`Shell`、`Awk`、`Sed`、`批量操作`

```
写一个 Shell 脚本，批量把 src/ 目录下所有 .js 文件的 console.log 替换为 logger.debug
```

这个技能擅长构造不会破坏代码结构的精确正则，还会处理特殊字符转义的边界情况。

---

### 技巧 11：写 API 文档，别让后端专家来干技术写作的活

**消歧规则**：`API + 文档/README` → 路由到 `tech-writer-expert`

```
# 触发 tech-writer-expert（正确）
帮我给这个 REST API 写 OpenAPI 3.0 文档，包含请求示例和错误码说明

# 触发 backend-builder（不推荐）
帮我实现这个 API
```

`tech-writer-expert` 了解文档结构规范，生成的 OpenAPI 文档包含完整的 `description`、`example`、`errorResponse` 字段，而不是只有端点列表。

---

### 技巧 12：项目管理和排期，产品经理级别的输出

触发 `product-manager-expert`：`PRD`、`需求文档`、`RICE`、`路线图`、`用户故事`

```
帮我写一个用户登录功能的 PRD，包含验收标准和边界场景
```

---

### 技巧 13：CI/CD 流水线，DevOps 专家比通用更了解最佳实践

触发 `devops-expert`：`CI/CD`、`GitHub Actions`、`Docker`、`Nginx`、`云服务`

注意与 `cloud-native-expert` 的区分：
- `Docker + CI/CD` → `devops-expert`
- `K8s + 部署` → `cloud-native-expert`

---

### 技巧 14：用 `/skill-name` 显式调用，绕过自动路由

这是 Bookworm 路由优先级最高的机制。当你明确知道需要哪个技能时：

```
/frontend-expert 帮我实现一个虚拟滚动列表组件
/security-expert 审查这段 JWT 验证代码
/architect-expert 帮我设计这个微服务的数据流
```

显式调用的优先级高于所有自动路由规则，即使输入关键词模糊也会直接执行。

---

### 技巧 15：通用编程问题不用费心路由，有兜底专家

当问题无法明确分类（如"帮我解释这段算法"、"这个 Python 语法对吗"），系统自动回退到 `developer-expert`。这是设计上的安全网，确保任何问题都有合理响应。

---

## Part 2：进阶技巧（技巧 16-30）— 专业领域深挖

### 技巧 16：性能优化，"加载慢"比"前端优化"更能触发正确路由

**消歧规则**：`性能优化/慢/卡顿/内存泄漏` → 优先路由到 `performance-expert`

即使你说的是"React 页面加载慢"，系统也会选择 `performance-expert` 而非 `frontend-expert`，因为性能分析是一个独立的专业方向：

```
# 触发 performance-expert
我的 Next.js 页面 LCP 超过 4 秒，Lighthouse 评分只有 52
```

`performance-expert` 的输出包含：
1. 用 Chrome DevTools 的 Performance 面板定位瓶颈
2. 代码级别的优化方案（代码分割、图片格式、缓存策略）
3. 预期优化效果的量化估算

---

### 技巧 17："测试"这个词路由到 5 个不同技能

这是 Bookworm 消歧规则最有价值的体现之一。同样含有"测试"的输入，根据上下文路由到完全不同的专家：

| 输入示例 | 路由目标 | 原因 |
|---------|---------|------|
| "写单元测试" + "Jest/Vitest" | `tester-expert` | 测试工程任务 |
| "A/B 测试" + "数据分析/pandas" | `data-analyst-expert` | 数据科学任务 |
| "渗透测试" + "漏洞/安全审计" | `security-expert` | 安全任务 |
| "可用性测试" + "用户访谈/Persona" | `ux-researcher` | UX 研究任务 |
| "A/B 测试" + "增长/AARRR/裂变" | `growth-hacker` | 增长营销任务 |

测试这个消歧效果很简单——加上不同的上下文关键词，观察路由结果的变化。

---

### 技巧 18：数据库问题，区分"优化"和"架构"

- `数据库 + 慢查询/索引/EXPLAIN` → `database-tuning-expert`
- `数据库 + 架构设计/分库分表/选型` → `architect-expert`

```
# 触发 database-tuning-expert
这条 SQL 执行超过 3 秒，帮我分析 EXPLAIN 的输出并优化

# 触发 architect-expert
我们的订单表预计 3 年后有 10 亿条数据，如何做分库分表设计
```

`database-tuning-expert` 的输出会包含索引类型选择（B-Tree vs Hash vs GiST）、覆盖索引、避免隐式类型转换等细节，远比通用回答更有针对性。

---

### 技巧 19-30（简要列举）

| 技巧 | 路由/能力 | 核心价值 |
|------|----------|---------|
| 19. 安全审计分层 | 单文件→security-expert，全项目→project-audit-expert | 粒度匹配 |
| 20. K8s 三路由 | 部署→cloud-native，架构→architect，CI/CD→devops | 场景细分 |
| 21. 微服务 gRPC | 微服务+gRPC→backend-builder | 实现层非架构层 |
| 22. SRE 监控 | SLI/SLO/事故响应→sre-expert | 四个黄金信号 |
| 23. DevSecOps | SAST/DAST/容器安全→devsecops-expert | 安全左移 |
| 24. Edge Computing | Workers/Vercel Edge→edge-computing-expert | 边缘限制感知 |
| 25. 影响分析 | 变更影响/依赖分析→impact-analyst | 爆炸半径评估 |
| 26. 架构图代码化 | Mermaid/PlantUML→diagram-as-code-expert | 图表即代码 |
| 27. 零缺陷重构 | Pinning Test→zero-defect-guardian | 行为保护 |
| 28. 浏览器自动化 | Playwright/RPA→browser-automation-expert | 纯自动化场景 |
| 29. SSH 远程操作 | ssh+服务器→devops-expert | 防误路由 |
| 30. Shell 输出识别 | PowerShell 提示符→devops-expert | 环境自动适配 |

---

## Part 3：高级技巧（技巧 31-40）— 多技能协作

### 技巧 31：让 Orchestrator 接管复杂任务

触发 `orchestrator` Agent 的关键词：`从零开发`、`全面优化`、`端到端实现`、`帮我搭建`

```
帮我从零搭建一个 SaaS 用户管理后台，包含认证、权限管理、用户 CRUD 和操作日志
```

Orchestrator 的工作流：
```
1. 目标分解 → 识别需要的技能（architect + backend + frontend + security + tester）
2. 依赖排序 → 先架构设计，再后端接口，再前端集成，最后测试
3. 并行调度 → 独立任务并行执行
4. 质量门控 → 每个阶段输出经过 quality-gate 验证
5. 交付报告 → 完整的实现总结和后续建议
```

---

### 技巧 32：理解技能链推荐，让协作更顺畅

Bookworm 的 composable 系统会根据当前技能自动推荐协作技能：

```yaml
frontend-expert:
  enhances: [designer-expert, ux-researcher]

performance-expert:
  enhances: [sre-expert, database-tuning-expert, frontend-expert]

security-expert:
  enhances: [devsecops-expert, reviewer-expert]
```

当你在 `frontend-expert` 模式下工作时，系统会提示"需要设计审查吗？可以切换到 designer-expert"。

---

### 技巧 33-40（简要列举）

| 技巧 | 工具/Agent | 核心能力 |
|------|-----------|---------|
| 33. 从零建项目 | genesis-engine (Skill) | 项目脚手架一气呵成 |
| 34. 技术调研 | research-analyst (Agent) | 只读分析+决策矩阵 |
| 35. 深度代码审查 | code-reviewer (Opus Agent) | 多维度正式 Review |
| 36. 自动化验收 | quality-gate (Agent) | TypeScript/Lint/测试/构建 |
| 37. 部署前检查 | pre-deploy-checker (Agent) | 环境变量/密钥/迁移兼容 |
| 38. UI 设计输出 | canvas-ui-designer (Agent) | 组件规范+WCAG+Token |
| 39. 实时文档 | context7 MCP | `use context7` 触发 |
| 40. 结构化推理 | sequential-thinking MCP | 复杂问题推理链 |

---

## Part 4：自进化技巧（技巧 41-50）— 系统自我优化

### 技巧 41：路由不准确时，直接纠正，系统会学习

当系统路由到错误的技能时，你可以反馈：

```
你刚才路由到了 frontend-expert，但我需要的是 performance-expert
```

这个反馈会被记录，通过指数衰减权重学习（5 天半衰期），同类输入在未来会更准确地路由。权重范围限制在 [-0.5, +0.5]，防止单次反馈过度影响系统。

---

### 技巧 42-50（简要列举）

| 技巧 | 机制 | 说明 |
|------|------|------|
| 42. 隐式反馈 | implicit-feedback.js | 5分钟内行为自动收集 |
| 43. 系统健康检查 | self-auditor | 8 维审计 |
| 44. 10 维健康评分 | health-check.js | 量化系统状态（当前 99/100） |
| 45. 配置漂移感知 | drift-detector | SHA256 + 自动修复 |
| 46. 路由合规门控 | compliance-gate | 防止技能滥用 |
| 47. 管道检测 | detectPipeline | 12 种测试框架汇总行 |
| 48. A/B 实验框架 | 内置实验分组 | 路由策略持续改进 |
| 49. 完整性签名 | SHA256 + HMAC | 24 文件机器绑定签名 |
| 50. 进化日志 | evolution-log.jsonl | 每次自愈完整轨迹 |

---

## 技术原理简介（5 分钟读懂路由引擎）

### BM25 + 上下文融合评分

Bookworm 不是简单的关键词匹配，而是一个多维评分系统：

```
综合得分 = BM25基础分(0.6) + 会话上下文(0.2) + 项目类型(0.1) + 工作流模式(0.1)
```

**BM25** 是信息检索领域的经典算法，相比 TF-IDF 更好地处理关键词频率的边际效益（词出现多次，增益递减）。系统对 50 个技能 × 2393 个加权关键词建立索引，每个关键词按三层权重标注：

```
core      权重最高  — 技能最核心的触发词（如 React → frontend-expert）
strong    次高      — 强相关词（如 Hook → frontend-expert）
extended  基础      — 弱相关词（如 组件 → 多个技能竞争）
```

### 7 层流水线架构

```
用户输入
  ↓
L1 路由层 — Neural Gateway: BM25 + TF-IDF + 上下文融合 → [BWR] 指令
  ↓
L2 门控层 — 5 个 PreToolUse 钩子: 文件保护 / 危险拦截 / 合规校验
  ↓
L3 执行层 — 50 专家技能 + 10 智能体 + 6 MCP 服务
  ↓
L4 后处理层 — 变更感知 / 构建追踪 / 活动日志
  ↓
L5 会话结束 — 合规审计 + 磁盘清理
  ↓
L6 学习闭环 — 显式纠正 + 隐式反馈 → 权重回注 L1
  ↓
L7 自进化 — 感知 → 审计 → 修复 → 记录（无人值守）
```

### 自适应学习闭环

学习安全设计的四道约束：

| 约束机制 | 作用 |
|---------|------|
| 技能名白名单校验 | 防止学习系统记录虚构技能名 |
| 权重限幅 [-0.5, +0.5] | 防止单一反馈暴走影响全局 |
| 5 天半衰期指数衰减 | 旧反馈自然退出，避免历史偏见 |
| Holdout 验证集 | 用保留数据集评估学习效果，防止过拟合 |

---

## 快速开始

### 前提条件

- Claude Code 已安装（`claude` CLI 可用）
- Node.js 18+

### 安装步骤

```bash
# 1. 克隆仓库到 ~/.claude 目录
# https://github.com/huakoh/bookworm-smart-assistant

# 2. 确认技能索引已生成
ls ~/.claude/skills-index.json

# 3. 验证钩子已注册
cat ~/.claude/settings.json | grep hooks

# 4. 运行健康检查
claude -p "帮我运行 health-check 查看系统健康评分"
```

### 5 分钟体验路由魔法

打开 Claude Code，依次输入以下三个请求，观察路由差异：

```bash
# 请求 1：应该路由到 debugger-expert
我的 useEffect 导致无限渲染，控制台报 Warning: Maximum update depth exceeded

# 请求 2：应该路由到 security-expert（不是 backend-builder）
帮我检查这个 API 的认证逻辑有没有安全漏洞

# 请求 3：应该触发 orchestrator（复杂任务）
从零帮我搭建一个带用户认证的 Todo 应用，包含前端、后端和数据库
```

在每次响应中，你可以看到系统注入的 `[BWR:<id>]` 路由指令，以及实际调用的技能名称。这个透明度设计是刻意为之——路由决策不是黑盒，用户可以随时看到和干预。

---

## 写在最后

Bookworm 最核心的设计理念，用一句话概括就是：**普通 AI 助手让用户适应 AI，Bookworm 让 AI 适应用户。**

这 50 个技能覆盖了从前端到后端、从开发到运维、从架构到产品、从技术到商业的全部工作流。但路由不是目的，路由的目的是让你每次交互都能得到**领域专家级别**的回答——不是泛化的建议，而是有具体代码、有行业最佳实践、有边界情况处理的专业输出。

系统正在不断进化。每一次你纠正路由错误，每一次你在技能推荐中选择了更合适的专家，都在让这个系统对你更了解。

项目地址：**[Bookworm Smart Assistant](https://github.com/huakoh/bookworm-smart-assistant)**

---

*Bookworm Smart Assistant v5.6 | 健康评分 99/100 | 1371/1371 测试全绿*

---

> 知乎推荐话题：`Claude Code` `AI编程` `开发者工具` `人工智能` `编程效率`