第四阶段：专家工作流

第四阶段：专家工作流 🏆

目标：能设计团队级 AI 效能体系，最大化 AI 投资回报 预计时间：持续进化（无终点）

本阶段学习地图

4.1 Token 预算精细化管理
    ↓
4.2 知识演化体系构建
    ↓
4.3 复杂任务模板
    ↓
4.4 自定义 Skills 开发
    ↓
4.5 团队 AI 效能体系设计
    ↓
4.6 实战练习
    ↓
4.7 高级调试技巧（性能分析/代码审查/故障响应）

文件结构

# 第四阶段：专家工作流/
├── 本文件（阶段导航）
├── Token 预算优化
├── 知识演化体系
├── 复杂任务模板
├── 自定义 Skills 开发
├── 团队 AI 效能体系
├── 实战练习
└── 高级调试技巧

核心理念

从"用 AI"到"管理 AI 团队"

专家阶段不只是更熟练地使用 Claude Code，而是设计整个团队如何通过 AI 实现持续效能提升：

• 每个问题的解决都沉淀为知识
• 知识的积累降低下一次的成本
• 形成正向飞轮，效能持续提升

阶段完成标准

• 能通过 token 优化策略将同等任务的成本降低 30%+
• 建立了一个有效的团队知识演化流程
• 为团队创建了至少一个自定义 Skill
• 能设计完整的团队 AI 工作流方案
• 持续回写经验，知识库在增长

---

常见问题 FAQ

Q1：执行了 /team-learn，但知识库里的内容没有实际复用价值

根本原因：/team-learn 提取的知识质量取决于会话内容的质量。如果会话只是"完成了 XX 功能"，提取不出有价值的知识。

提高知识质量的方法：在任务结束时，主动引导 Claude 提取：

> 我们这次解决了一个 token 刷新的并发问题。
  在执行 /team-learn 前，先回答：
  1. 这个问题的根因是什么？（非直觉的部分）
  2. 解决方案的核心思路是什么？
  3. 类似的问题下次如何快速识别？
/team-learn

这样引导后，提取的知识质量会高得多。

---

Q2：团队成员都配置了 CLAUDE.md，但大家的行为不一致

原因：各自的 CLAUDE.md 内容不同，或者 shared-config 同步不及时。

解决方案：

# 检查共享配置版本
cat ~/Documents/git/team-knowledge/shared-config/CLAUDE.md | head -3
# 应该能看到版本号，如：# 版本: 2.1.1 | 更新: 2026-03-23

# 如果版本不一致，手动同步
cd ~/Documents/git/team-knowledge && git pull

# 让 TL 定期检查
/team-ai-report  # 会显示各成员的配置版本

---

Q3：token 消耗降不下去，每个任务还是很贵

诊断步骤：

1. 记录最近 5 个任务的 token 消耗（/status 或 /cost）
2. 找出消耗最高的任务
3. 分析这些任务的对话日志：
   - 是否有大量文件读取？（用 Grep + offset/limit 代替）
   - 对话是否超过 30 轮没有 compact？
   - 是否在主会话做了大量探索性工作？（应该委派子 Agent）

最容易被忽视的消耗：CLAUDE.md 太长。每次对话都要注入，500 行 CLAUDE.md 每轮消耗约 2000 tokens。

---

Q4：自定义 Skill 写好了，但触发后 Claude 不按 Skill 的步骤走

可能原因：

1. Skill 文件存放位置不对
2. Skill 名称与触发命令不匹配
3. Claude 没有识别到这是一个 Skill 调用

检查 Skill 文件位置：

ls ~/.claude/skills/
# 应该看到你的 skill 目录
# 如：~/.claude/skills/my-skill/skill.md

触发方式：

# 方式一：斜杠命令（最可靠）
/my-skill

# 方式二：描述触发（依赖 Skill 文件中的触发条件描述）
> 执行 XX 检查

---

Q5：/team-distill 蒸馏后，domains/ 里的内容和代码不一致

这是知识库腐烂的典型症状。

立即处理：

/team-validate
# 会自动对比知识库与代码，找出不一致项

预防措施：

• 代码变更后，主动更新相关知识
• 月度执行 /team-validate
• 重大重构后立即执行 /team-distill diff

---

Q6：如何判断自己已经从"高级"升到"专家"？

关键区分：

高级（会用工具）	专家（会设计体系）
遇到问题时调用 Skill	会根据场景选择最合适的 Skill
使用 MCP 工具	知道何时 MCP 比 Grep 更高效
执行 /team-learn	主动引导提取高质量知识
用 /compact 管理上下文	提前规划任务边界避免上下文爆炸
跟着步骤做	能预判下一步，甚至优化 Skill 设计

最直观的判断：你能给别人讲清楚为什么要这样做，而不只是"这样做有效"。

4.1 Token 预算精细化管理

Token 就是 AI 的"燃料"，精细化管理意味着把每一滴燃料用在刀刃上。

理解 Token 成本

每次对话的 token 构成：

输入 token（你付费）：
├── CLAUDE.md 内容（每轮都有）
├── 对话历史（越来越长）
├── 当前消息内容
└── 工具调用结果（Grep/Read 的输出）

输出 token（你也付费）：
├── Claude 的回答
└── 工具调用（工具的参数）

关键洞察：长对话中，对话历史的 token 可能占总成本的 50%+。

自动委派规则

应该用子 Agent（Sonnet）的任务

探索类任务 → 子 Agent
├── 在代码库中搜索某个函数
├── 读取 3 个以上文件理解逻辑
├── 查询文档/配置
├── 生成 commit message 或注释
└── 格式转换、批量重命名

特征：
- 主要是"信息收集"，不需要推理
- 失败影响小（重跑即可）
- 速度比质量更重要

必须在主会话（Opus）中的任务

编码类任务 → 主会话
├── 编写核心业务逻辑
├── 架构设计和技术方案
├── 复杂 bug 的根因分析
├── 代码安全审查
└── 复杂的代码重构

特征：
- 需要深度推理
- 错误代价高
- 质量比速度重要

文件读取的正确姿势

策略：先定位再精读

# 步骤 1: Grep 定位（快速，低成本）
> 找一下 validateToken 函数在哪个文件的哪一行

# 步骤 2: 精确读取（只读必要内容）
> 读一下那个文件的第 80-130 行

# 错误做法（高成本）：
> @src/auth/authService.ts 分析这个文件  ← 可能读取 1000+ 行

实际节省估算

文件大小：500 行
直接读取：500 行 × 4 token/行 = 2000 tokens

先 Grep 后精确读取：
- Grep 结果：20 行 × 4 = 80 tokens
- Read 精确：50 行 × 4 = 200 tokens
- 总计：280 tokens

节省：86%

文档优先原则

每次问"这个项目里 X 是怎么实现的"，先查文档和历史笔记，不是先读代码：

查询成本对比：

有历史记录（README / 笔记 / 注释）：
→ 一次 Grep + Read = 约 500 tokens

从代码探索：
→ 多次 Grep + Read 多文件 = 约 5000+ tokens

节省：90%

建议的查询顺序：

1. 项目 README 和 CLAUDE.md
2. docs/ 目录下的文档
3. 代码注释和测试文件
4. 直接读取实现代码（最后手段）

CLAUDE.md 的 Token 成本

CLAUDE.md 每次对话都会被注入，要控制它的大小：

CLAUDE.md 优化建议：

✅ 保留：
- 绝对禁止的行为（高价值，必须每次提醒）
- 技术栈声明（Claude 每次需要知道）
- 验证命令（每次都需要）

❌ 删除或移到外部引用文件：
- 详细的 API 文档（按需引用）
- 完整的设计规范（按需引用）
- 历史记录或日志

长对话优化

超过 20 轮：/compact
超过 40 轮：考虑 /clear + 新开话题
超过 60 轮：这个话题应该被拆分为多个独立会话

合理的单次会话长度：
- 简单问答：1-5 轮
- 单个 bug 修复：5-15 轮
- 完整功能开发：15-30 轮（用 /compact 维护）
- 大型重构：拆为多个阶段会话

Token 使用监控

# 查看本次会话 token 用量
/status

# 查看费用估算
/cost

高频节省技巧汇总

技巧一：读文件前先确认行号

# 坏习惯：直接读整个文件
> @src/services/OrderService.java 分析 processOrder 方法

# 好习惯：先定位行号，再精确读取
> Grep 一下 processOrder 方法在 OrderService.java 的哪一行
（Claude 找到：第 87 行）
> 读一下 OrderService.java 第 80-130 行

技巧二：结构探索用 Glob 不用 Read

# 了解目录结构（低成本）
> src/payment/ 目录下有哪些文件？
（Claude 用 Glob，只返回文件名列表）

# 不要这样（高成本）
> @src/payment/ 这个目录有什么内容？
（引用整个目录，读取所有文件内容）

技巧三：跨文件任务写清楚范围再开始

# 任务开始前明确范围，避免中途反复读文件
> 我需要把 OrderService 里的分页逻辑改成 cursor-based。
  涉及的文件：src/services/OrderService.java、src/api/OrderController.java、
  src/types/OrderTypes.ts。
  先分析这三个文件，给我一个改动方案，不要直接动手。

这样 Claude 一次性读完所有需要的文件，不会在实现过程中反复重新读取。

---

成本优化 Checklist

在开始一个新任务前，问自己：

• 这个任务需要读多少文件？能先 Grep 定位吗？
• 项目文档里有没有相关信息？（先查再探索）
• 这个子任务需要 Opus 的能力吗？（还是 Sonnet 够用）
• 上下文是否已经很长了？（要不要先 /compact）
• 这个任务能否分成独立的阶段，减少单次会话长度？
• 我有没有在用 @目录 引用大量文件？（改用 Grep + 精确 Read）

4.2 知识演化体系

知识演化体系是专家阶段最核心的能力——让每次解决问题都沉淀为未来的速度。

知识飞轮

什么是知识飞轮：解决问题 → 记录经验 → 下次遇到类似问题时直接查记录，速度更快 → 节省下来的时间用来积累更多经验 → 越来越快，形成正向循环。

"蒸馏"的意思是：把零散的经验笔记整理成结构化文档，从"某次遇到了 XX 问题，我这样解了"升华为"遇到 XX 类问题，标准解法是..."，让知识从个人经验变成团队可复用的规律。

解决一个问题
    ↓
提取经验（写入知识库）
    ↓
写入 learnings/（个人经验）
    ↓
定期蒸馏为结构化文档
    ↓
写入 domains/（团队知识）
    ↓
下次遇到类似问题，直接复用
    ↓
解决得更快 → 有更多时间积累知识
    ↓
回到顶部，飞轮加速

知识分层结构

knowledge/（团队共享仓库）
├── domains/                    ← 领域知识（团队共享）
│   ├── frontend.md             ← 前端架构模式、最佳实践
│   ├── backend.md              ← 后端设计模式、规范
│   ├── security.md             ← 安全规范、漏洞模式
│   └── devops.md               ← 部署、监控规范
│
├── projects.md                 ← 项目架构摘要（最常查）
│
└── members/
    └── {角色名}/
        └── learnings/          ← 经验积累（每个文件一个领域）
            ├── bugs.md         ← Bug 根因和解决方案
            ├── patterns.md     ← 可复用的代码模式
            └── gotchas.md      ← 容易踩坑的地方

经验回写的流程

何时应该记录经验

以下情况值得记录：
1. 发现了一个 bug 的非直觉根因
2. 找到了一个特别有效的代码模式
3. 解决了一个困扰已久的难题
4. 发现了某个框架/工具的使用坑
5. 设计了一个值得复用的架构决策

判断是否值得记录的三个问题：

1. 这个经验下次遇到类似问题能直接用吗？
2. 这是不直觉的发现（反常识/踩坑）吗？
3. 其他人会因为不知道这个而重复踩坑吗？

三个问题有 2 个"是"，就值得记录。

好的知识条目示例

# learnings/bugs.md

## JWT Token 竞态条件（2026-03）

**现象**：用户在高并发场景下偶发 401 错误

**根因**：token 刷新接口没有加锁，多个请求同时触发刷新，
         第一个请求刷新后其他请求拿到的 old token 已失效

**解决方案**：
1. 前端：使用请求队列确保 token 刷新串行执行
2. 后端：refresh token 接口加分布式锁

**参考代码**：src/api/interceptors.ts

差的知识条目（无法复用）

# ❌ 不好的示例
## 2026-03-27
完成了用户登录功能的开发

知识蒸馏

当 learnings/ 积累了足够多的条目后，定期整理为结构化文档：

蒸馏前后对比：

蒸馏前（learnings/bugs.md）：
- 20 个具体 bug 案例，各自独立

蒸馏后（domains/frontend.md 新增章节）：
## 常见并发问题模式

### Token 刷新竞态
场景：多个并发请求同时触发 token 刷新
解决模式：前端请求队列 + 后端分布式锁
参考实现：见 learnings/bugs.md 的 2026-03 案例

知识对账（防止腐烂）

代码在变，知识库不能停留在过去。定期对比知识库与实际代码是否一致：

# 手动方法：
# 1. 读取 domains/ 中的关键断言
# 2. Grep 验证代码中是否还有对应实现
# 3. 发现不一致时更新知识库

# 例如知识库说"分页使用 PageHelper"，验证：
grep -r "PageHelper" src/ -l

知识演化的节奏建议

每次完成任务：
└── 如有非直觉的发现，记录到 learnings/

每周：
└── 检查 learnings/ 新增了什么
└── 是否有需要升级到 domains/ 的模式

每月：
└── 全量蒸馏 learnings/ → domains/
└── 知识对账（验证知识库与代码一致）
└── 清理过时的知识条目

衡量知识演化是否有效

指标：
1. 同类问题的解决时间是否在缩短？
2. 知识库的 domains/*.md 是否在增长？
3. 新成员上手时，知识库帮助了多少？
4. 有多少次"查知识库 → 直接解决"而不需要读代码？

---

知识演化的常见误区

误区一：记了太多，但都没有复用价值

症状：learnings/ 里有很多条目，但每次遇到问题还是要读代码。

原因：记录的是"做了什么"，而不是"非直觉的发现"。

❌ 没有复用价值的记录：
完成了商品列表页的开发，使用了 React + TypeScript

✅ 有复用价值的记录：
## React 列表页性能陷阱（2026-03）
现象：列表渲染时 taxRateMap 每次渲染都重新创建，导致 LCP 3.8s
根因：初始化代码写在组件内部，每次渲染都执行
解决：将 taxRateMap 移到组件外部（模块级），只初始化一次
参考：src/pages/ProductList.tsx 的 taxRateMap 处理方式

---

误区二：只记录个人经验，没有沉淀到团队

个人 learnings/ 的内容只有自己能用。真正有价值的发现需要升级到团队 domains/：

个人发现 → learnings/bugs.md  （私有，快速记录）
    ↓（当该模式被验证为普遍规律时）
团队知识 → domains/frontend.md （共享，结构化）

判断是否该升级：其他人也会遇到这个问题吗？ 如果是，就应该放到 domains/。

---

误区三：知识库更新后没人知道

在团队 CLAUDE.md 的变更记录里记录知识库的重大更新：

## 知识库更新记录
- 2026-03-27: domains/frontend.md 新增"React 列表渲染性能陷阱"章节
- 2026-03-20: domains/backend.md 新增"分布式锁使用规范"

这样其他成员下次启动 Claude 时，SessionStart Hook 同步后就能看到更新提示。

4.3 复杂任务模板

针对不同类型的复杂任务，这里提供经过验证的执行模板。

模板一：大型功能开发

适用场景：超过 5 个文件的新功能，预计 2+ 天工作量

阶段一：需求理解（独立会话）
├── 阅读需求文档
├── 澄清边界和不确定点
└── 输出：需求澄清文档，确认功能边界

阶段二：代码探索（独立会话）
├── 创建规划文件（.claude/plans/）
├── 子 Agent 并行探索相关模块
│   ├── 探索：现有同类功能的实现方式
│   ├── 探索：涉及的 API 接口定义
│   └── 探索：数据流和状态管理
└── 输出：findings.md 更新

阶段三：方案设计 [门控]（主会话）
├── 基于探索结果设计技术方案
├── 输出：task_plan.md（含文件清单、改动说明）
└── 等待用户确认后进入下一阶段

阶段四：分批实现（1-3 次会话）
├── 每批：实现 2-3 个文件
├── 每批后：运行验证命令
└── 遇到问题：不跳步，先分析根因

阶段五：质量审查
├── 代码审查（多维度）
└── 修复发现的问题

阶段六：闭环
├── 执行完整验证（单测 + 集成测试）
└── /commit 生成规范提交

模板二：性能问题排查与优化

适用场景：页面加载慢、接口响应慢、内存/CPU 高

阶段一：问题定性
├── 查询监控数据，确认问题范围
└── 输出：问题描述文档（页面/接口/时间段）

阶段二：数据采集（Chrome DevTools MCP）
├── 录制性能 trace
├── 采集 LCP/INP/FCP/CLS 指标
└── 生成火焰图

阶段三：根因分析
├── 分析火焰图中的热点函数（看最宽的 Task 块 → 向下找最宽的函数帧 → 那就是热点）
├── 用 ide_call_hierarchy 追踪慢函数调用链
├── 定位性能瓶颈（渲染阻塞/重复计算/接口慢等）
└── [门控] 确认根因

阶段四：优化实施
├── 针对根因制定优化方案
├── 实施优化（代码层面）
└── 验证：前后性能对比

阶段五：闭环
├── 截图/数据对比，记录优化效果
└── /commit 生成规范提交

模板三：依赖库升级迁移

适用场景：批量将旧依赖/组件替换为新版本

阶段一：扫描
├── Grep 搜索所有使用旧依赖的文件
├── 生成替换清单（文件 + 使用位置 + 行号）
└── 评估工作量和风险

阶段二：批量替换
├── 按模块/文件为单位执行替换
├── 每个文件替换后运行类型检查
└── 生成替换报告

阶段三：验证
├── 静态分析：类型检查、lint
├── 功能验证：运行测试套件
└── 视觉验证（如有 UI 改动）：Chrome DevTools 截图对比

阶段四：闭环
├── 修复验收中发现的问题
└── /commit（一个模块一个 commit，便于回滚）

模板四：Bug 快速响应（生产环境）

适用场景：线上 bug，需要快速定位和修复

分钟 0-5：信息收集
├── 获取：错误日志、影响用户数
├── 获取：最近的发布记录（什么时候开始出现？）
└── 初步判断：前端/后端/配置问题？

分钟 5-15：根因定位
├── 提供症状、日志、最近变更，请 Claude 分析
└── [门控] 确认根因

分钟 15-30：修复
├── 实施最小改动的修复（先止血，不追求完美）
├── 运行测试验证修复有效
└── 同时记录：根因、临时修复、永久修复计划

修复后
├── 观察监控确认问题消失
└── 记录 bug 根因和处理模式（写入 learnings/）

模板五：代码架构重构

适用场景：大规模代码组织调整，非功能性改动

原则：
- 每次重构只做一件事（不混入功能修改）
- 重构后必须通过所有现有测试
- 小步前进，每步可回滚

流程：
1. 用 ide_type_hierarchy + ide_call_hierarchy 理解现有结构
2. 设计目标架构，输出对比图
3. [门控] 确认架构方向
4. 拆分为独立的重构步骤（每步不超过 3 个文件）
5. 每个步骤：改动 → 测试 → commit
6. 全部完成后：全量测试
7. 代码审查，确认架构意图清晰

---

如何选择合适的模板

任务是什么？
    │
    ├─ 线上故障 → 模板四（Bug 快速响应）
    │
    ├─ 本地 bug，不紧急 → 使用 /dev-fix-bug Skill
    │
    ├─ 新功能，5+ 文件 → 模板一（大型功能开发）
    │
    ├─ 新功能，1-3 文件 → 使用 /dev-implement Skill
    │
    ├─ 依赖库升级 → 模板三（依赖迁移）
    │
    ├─ 页面/接口慢 → 模板二（性能排查）
    │
    └─ 代码结构混乱 → 模板五（架构重构）

判断原则：改动越大、风险越高，越需要用模板拆分阶段、加门控。简单任务直接用自然语言或 Skill 即可，不必套模板。

4.4 自定义 Skills 开发

Skills 本质上是 Markdown 文件，可以自行创建来封装你团队的特定工作流。

Skills 文件存放位置

~/.claude/skills/
└── my-skill-name/
    ├── skill.md          ← 主技能文件（必须）
    └── templates/        ← 辅助模板（可选）
        └── report.md

skill.md 标准结构

# 技能名称

## 概述
一句话描述这个 Skill 做什么

## 触发条件
当用户说以下内容时触发：
- "xxx 检查"
- "帮我做 yyy"
- 关键词：abc、def

## 前置条件
执行前需要确认：
- 用户已提供 XX 信息
- 当前目录是 XX 项目

## 步骤

### Step 1: 信息收集
...具体操作...

### Step 2: 分析 [门控]
...分析操作...
**输出分析结果，等待用户确认 "继续" 后进入 Step 3**

### Step 3: 执行
...执行操作...

### Step 4: 验证
...验证操作...

### Step 5: 闭环
...收尾操作...

## 完成标准
- [ ] 验证命令已执行且通过
- [ ] 用户已确认结果正确

实例一：API 接口变更影响分析 Skill

场景：接口字段变更时，自动分析前后端影响范围

# API 变更影响分析

## 触发条件
当用户说：
- "分析这个接口变更的影响"
- "XX 接口加了一个字段"
- "/api-change-analysis"

## 步骤

### Step 1: 接收变更信息
请用户提供：
- 变更的接口路径（如 `/api/v1/orders`）
- 具体变更内容（新增/修改/删除哪些字段）

### Step 2: 后端影响分析
使用 Grep 查找：
1. 接口的 Controller 定义
2. 对应的 VO/DTO 类
3. 所有引用这些类的地方（Grep + ide_find_references）
输出影响的后端文件列表

### Step 3: 前端影响分析 [门控]
1. 查找前端的 API 定义文件（src/api/）
2. Grep 搜索接口路径的引用
3. 找出所有调用该接口的组件
输出前端影响文件列表，等待确认

### Step 4: 生成影响报告
汇总：
- 需要修改的后端文件
- 需要修改的前端文件
- 需要更新的测试用例
- 是否需要数据迁移

### Step 5: 闭环
记录此类接口变更的分析模式到 learnings/

实例二：代码提交自查 Skill

场景：提交代码前的快速自查

# 代码提交自查

## 触发条件
- "/pre-commit-check"
- "提交前检查"

## 步骤

### Step 1: 获取变更清单
执行 `git diff --name-only HEAD` 获取变更文件列表

### Step 2: 逐类检查 [门控]

**TypeScript 文件检查**：
- [ ] 是否有 any 类型
- [ ] 是否有未处理的 Promise
- [ ] 组件 Props 是否有类型定义

**API 调用检查**：
- [ ] 是否有统一的错误处理
- [ ] 是否有 loading 状态管理

**国际化检查**：
- [ ] 用户可见文字是否都用 i18n 包裹
- [ ] 是否有硬编码的文字

**安全检查**：
- [ ] 是否有 SQL 注入风险
- [ ] 是否有 XSS 风险
- [ ] 是否有敏感信息泄露（密钥、密码）

输出 Checklist 报告，标注通过✅、需注意⚠️、有问题❌

### Step 3: 建议行动
根据报告给出修复建议

## 完成标准
- [ ] 所有 ERROR 级别问题已修复
- [ ] lint 和 test 验证通过

实例三：开发环境诊断 Skill

# 开发环境诊断

## 触发条件
- "环境出问题了"
- "项目跑不起来"
- "/env-diagnose"

## 步骤

### Step 1: 自动采集信息
- Node.js 版本（node --version）
- 依赖安装状态（ls node_modules/.package-lock.json）
- 环境变量文件（ls .env*）
- 端口占用情况
- Git 状态（是否有未提交的配置文件）

### Step 2: 诊断 [门控]
基于采集信息，分析可能的问题原因，
输出诊断报告，等待确认

### Step 3: 修复建议
根据诊断结果，给出具体的修复命令

调试 Skill

问题：触发了命令但 Claude 没有按步骤走

# 1. 确认 Skill 文件位置正确
ls ~/.claude/skills/
# 应该看到：my-skill/skill.md

# 2. 确认文件名是否正确
ls ~/.claude/skills/my-skill/
# 必须有 skill.md，文件名不能错

# 3. 重新验证：明确说 Skill 名
> 执行 /my-skill
# 或者
> 请使用 my-skill Skill 执行 XX 任务

问题：Skill 中途停了，Claude 不继续

# Skill 在门控点等待你的指令
# 常见的继续方式：
> 确认，继续下一步
> 方案 A 没问题，执行
> 我确认根因分析正确，开始修复

问题：Skill 没有门控，Claude 一气呵成改了很多文件

这说明 skill.md 中的门控描述不够清晰。门控必须明确写出停止等待的指令：

# ✅ 有效的门控描述
**输出以上分析结果，等待用户输入"确认"后继续执行 Step 3**

# ❌ 无效的门控描述
确认后继续（太模糊，Claude 可能自动继续）

---

发布 Skill 到团队

# 1. 将 Skill 文件放入团队共享仓库
cp -r ~/.claude/skills/my-skill ~/path/to/shared-repo/skills/

# 2. 提交到仓库
cd ~/path/to/shared-repo
git add skills/
git commit -m "feat: 新增 XX Skill"
git push

# 3. 其他成员更新后自动获得
git pull

注意：Skill 发布后，其他人的机器上还需要确认 ~/.claude/skills/ 下有这个目录。如果团队通过 SessionStart Hook 同步共享仓库，更新后会自动同步。

Skill 开发原则

1. 每个 Skill 做一件事：不要把多个工作流塞进一个 Skill
2. 门控要放对位置：在"分析完成、用户需要确认方向"时放门控
3. 门控描述要明确：必须明确写出"等待用户说 XX 后才继续"
4. 明确完成标准：Skill 的最后要有可验证的完成标准
5. 闭环不能省略：一定要包含验证步骤
6. 从简单开始：先 3 步 + 1 个门控，验证有效后再扩展

4.5 团队 AI 效能体系设计

从个人高效使用到团队级效能提升，需要系统性设计。

体系架构

团队 AI 效能体系
├── 基础设施层
│   ├── 统一的 CLAUDE.md 配置
│   ├── MCP 服务器（全员统一安装）
│   └── Hooks（SessionStart 同步）
│
├── 知识层
│   ├── domains/ （领域知识，月度更新）
│   ├── projects.md （项目摘要，按需更新）
│   └── learnings/ （个人经验，持续积累）
│
├── 工作流层
│   ├── 标准化 Skills（团队内统一）
│   └── 任务模板（标准化执行路径）
│
└── 治理层
    ├── 月度知识库健康检查
    ├── AI 使用情况统计
    └── 知识贡献跟踪

新成员快速接入

# Step 1: 安装 Claude Code
npm install -g @anthropic-ai/claude-code

# Step 2: 获取团队配置仓库
git clone <shared-config-repo> ~/path/to/shared-config

# Step 3: 配置全局 CLAUDE.md
cat >> ~/.claude/CLAUDE.md << 'EOF'
# 团队共享配置
@~/path/to/shared-config/CLAUDE.md
EOF

# Step 4: 安装必要的 MCP 服务器
# 参考团队文档安装 IDE 插件和 Chrome DevTools MCP

# Step 5: 验证配置
claude
> 你了解我们团队的开发规范吗？

知识贡献文化

贡献激励体系

知识贡献等级：
🌱 Learner     - 1-5 条 learnings
⚡ Contributor - 6-20 条 learnings
🏆 Expert      - 21+ 条 learnings + domains 贡献

定期在团队中展示知识贡献排行，形成积极的积累文化。

团队 AI 使用监控

可以通过以下方式了解团队 AI 使用情况：

• 查看各成员的 /cost 和 /status 数据
• 统计 Skills 被触发的频次
• 追踪知识库的增长量

用途：

• 识别没有使用 Claude Code 的成员（需要培训）
• 发现高频使用场景（候选 Skill 化）
• 优化 token 预算分配

知识库治理

防止知识腐烂

代码在变，知识库不能停留在过去：

# 定期手动验证知识库中的关键断言
# 例如：知识库说"分页使用 PageHelper"，验证：
grep -r "PageHelper" src/ -l

# 发现不一致时及时更新知识库

知识分类管理

每条知识条目应该归类到正确的文件：
- learnings/bugs.md       ← bug 根因和解决方案
- learnings/patterns.md   ← 可复用的代码模式
- learnings/gotchas.md    ← 容易踩坑的地方

定期检查：
- 是否有跨角色共享的知识需要提升到 domains/
- 是否有已过时的条目需要删除

衡量体系成效

定量指标

速度指标：
- 同类 bug 的平均修复时间（前后对比）
- 功能开发的首次通过率
- 代码 review 轮次减少

成本指标：
- 平均每个任务的 token 消耗
- 知识库命中率（查知识库解决问题 vs 读代码）

质量指标：
- 生产环境 bug 数量趋势
- 代码审查发现的问题数量

定性指标

- 新成员上手速度（从入职到独立完成第一个 PR）
- 团队对 AI 工具的满意度
- 知识库的主动使用频率

常见问题与解决方案

问题	症状	解决方案
知识库不更新	每次都要从代码探索	建立任务完成后记录经验的习惯
配置不统一	不同成员行为不一致	统一 shared-config，SessionStart 自动同步
Skills 不好用	没人主动调用	收集反馈，改进 Skill 设计，加强宣导
token 超支	月末额度告急	分析高消耗场景，优化文件读取策略

---

体系推进的节奏建议

不要一次性推行所有东西，容易让团队感到负担过重。建议分阶段落地：

第一个月：基础统一
├── 统一 CLAUDE.md（共享规范）
├── 统一 settings.json（权限安全配置）
└── SessionStart Hook 自动同步配置
    目标：所有成员行为一致

第二个月：工具提效
├── 全员安装 IDE MCP
├── 前端成员安装 Chrome DevTools MCP
└── 推广 /commit 替代手写 commit message
    目标：日常操作提速

第三个月：工作流标准化
├── 引入 2-3 个高频 Skill（bug 修复、需求实现）
├── 举办一次实操培训
└── 收集反馈优化 Skill 设计
    目标：复杂任务有标准流程

第四个月起：知识积累
├── 建立 learnings/ 记录习惯
├── 月度知识蒸馏
└── 定期分享有价值的发现
    目标：知识飞轮开始运转

关键原则：每个阶段只解决一个核心问题，验证有效后再推进下一步。

4.6 实战练习

---

练习一：Token 消耗对比实验

目标：亲身感受优化前后的 token 消耗差异

步骤：

1. 选择一个你熟悉的代码库
2. 用"低效方式"完成一个探索任务：

   > @src/ 分析这个模块的架构
   

3. 记录消耗的 token 数（/status 查看）
4. /clear 重置会话
5. 用"高效方式"完成同样任务：

   > 先用 ls 列出这个模块的文件结构，
     然后 Grep 找出核心类，
     再精确读取关键文件
   

6. 对比两次的 token 消耗

验收：高效方式的 token 消耗减少 50%+ ✓

---

练习二：建立个人知识库

目标：完成一次完整的知识沉淀流程

步骤：

1. 解决一个真实的 bug 或完成一个有学习价值的功能
2. 会话结束后，手动总结并记录知识：
   • 创建 ~/Documents/git/team-knowledge/knowledge/learnings/bugs.md（如果不存在）
   • 写入本次发现：现象、根因、解决方案
3. 验证知识条目是否符合"可复用"标准

验收：

• 知识条目准确描述了解决的问题
• 包含：现象、根因、解决方案
• 下次遇到类似问题可以直接参考 ✓

---

练习三：设计一个团队 Skill

目标：为团队创建一个实用的自定义 Skill

步骤：

1. 识别一个团队中重复执行的工作流（例如：新页面创建、API 接口变更分析等）
2. 按照 skill.md 模板设计这个 Skill（见 phase-4-expert/04-custom-skills.md）
3. 至少包含 3 个步骤和 1 个门控
4. 让另一个人试用这个 Skill，收集反馈

验收：

• Skill 结构完整（步骤 + 门控 + 完成标准）
• 有人实际使用并认为有帮助 ✓

---

练习四：Token 预算优化分析

目标：分析并优化自己的 token 使用习惯

步骤：

1. 回顾最近 5 次使用 Claude Code 的任务
2. 用 /cost 查看各次会话的费用
3. 分析消耗最多 token 的会话：
   • 是否有大量文件读取（可以改用 Grep + 精确读取）？
   • 对话轮数是否过多（是否忘记 /compact）？
   • 是否重复读取同一文件？
4. 针对最大消耗场景，制定优化策略
5. 实施优化，对比效果

验收：找到至少一个可优化 30%+ 的场景并落地 ✓

---

综合挑战：建立团队知识飞轮

目标：一个月内建立可持续运转的知识演化体系

Week 1：基础建设

• 统一团队 CLAUDE.md 配置（所有成员用同一份）
• 确认所有成员 MCP 安装到位（IDE + Chrome DevTools）
• 设置 SessionStart 同步 Hook

Week 2：习惯建立

• 每次完成任务后记录非直觉的发现到 learnings/
• 每周检查 learnings/ 新增情况
• 发现并记录 3 个以上 bug 根因

Week 3：知识整合

• 整理 learnings/ 中的规律，蒸馏为 domains/ 中的模式
• 更新 domains/ 相关章节
• 验证知识库与代码一致

Week 4：复盘优化

• 分析一个月的 token 消耗，找出优化点
• 总结体系运转中的问题和改进点
• 为团队分享知识演化的实践经验

成功标准：

• domains/ 有实质性内容增加
• 至少有一次"查知识库直接解决"而不需要探索代码
• 团队成员都有过知识记录的行为

4.7 高级调试技巧

高级调试不是"多试几次"，而是系统化地定位问题根因，并用工具加速每一步。

---

一、性能问题诊断体系

1.1 前端性能指标速查

Core Web Vitals（核心指标）：
├── LCP（Largest Contentful Paint）
│   目标：< 2.5s  警告：2.5-4s  差：> 4s
│   含义：最大内容元素的渲染时间（用户感知的"页面加载好了"）
│
├── INP（Interaction to Next Paint）
│   目标：< 200ms  警告：200-500ms  差：> 500ms
│   含义：用户交互到页面响应的延迟（点按钮有没有反应）
│
└── CLS（Cumulative Layout Shift）
    目标：< 0.1  警告：0.1-0.25  差：> 0.25
    含义：页面布局稳定性（内容会不会突然跳动）

1.2 性能分析完整流程

Step 1：采集数据（Chrome DevTools MCP）

  > 对目标页面录制一次性能 trace，重点分析 LCP 和 INP

Step 2：定位瓶颈（从 trace 中分析）

  常见 LCP 慢的原因：
  ├── 资源加载慢（大图片、未压缩的 JS）
  ├── 渲染阻塞（同步 script、长任务阻塞主线程）
  └── 服务端响应慢（TTFB > 800ms）

  常见 INP 高的原因：
  ├── 事件处理函数耗时（> 50ms 的同步操作）
  ├── React 重渲染过重（大量不必要的子组件更新）
  └── 强制同步布局（读取 offsetHeight 后立即写 DOM）

Step 3：代码定位（IDE MCP + Grep）

  # 找到慢函数的调用链
  > 用 ide_call_hierarchy 分析 renderList 函数，
    找出所有触发它的入口，判断是否有不必要的调用

  # 搜索可能的性能陷阱
  > Grep 一下项目中所有使用 offsetHeight、scrollTop 等
    会强制重排的属性

Step 4：实施优化

  常用优化手段（按影响大小排序）：
  1. 图片优化（WebP + 懒加载）→ LCP 改善最明显
  2. 代码分割（路由级 lazy import）→ 首屏 JS 减少
  3. React.memo / useMemo 优化重渲染 → INP 改善
  4. 虚拟列表（长列表）→ 滚动流畅度

Step 5：验证（前后对比）

  # 再次录制 trace，对比关键指标
  > 对比优化前后的 LCP，截图两次 trace 的结果

1.3 火焰图阅读技巧

火焰图（Flame Chart）结构：
┌─────────────────────────────────────────┐
│  Task（任务）                            │  ← 越宽 = 越耗时
│  ├── Script Evaluation                  │
│  │   ├── renderApp                      │  ← 函数调用栈
│  │   │   ├── renderList (120ms)         │  ← 这里是热点！
│  │   │   │   ├── formatPrice (80ms)     │
│  │   │   │   └── renderItem (×100)      │
│  │   │   └── renderSidebar (10ms)       │
│  └── Layout (30ms)                      │
└─────────────────────────────────────────┘

阅读步骤：
1. 找最宽的 Task（Long Task > 50ms）
2. 向下展开，找最宽的函数帧
3. 这就是需要优化的热点函数

用 Claude 分析火焰图：
> 分析这段 trace，找出耗时最长的函数调用链，
  告诉我应该优先优化哪里

---

二、多维度代码审查

2.1 并行审查架构

让 Claude 并行启动多个专项审查 Agent：

> 对这次改动进行多维度审查，请并行分析：
  [1] 测试覆盖
      ↳ 测试覆盖率分析
      ↳ 测试场景是否覆盖边界条件
  [2] 安全漏洞
      ↳ XSS 风险
      ↳ SQL 注入
      ↳ 敏感信息硬编码
  [3] 代码行为
      ↳ TypeScript 类型安全
      ↳ 未处理的 Promise/async 错误
      ↳ React Hooks 规则合规
  [4] 代码规范
      ↳ 命名、结构、可读性

  各维度独立分析，最后汇总评分报告

2.2 审查报告的阅读策略

审查报告通常有很多问题，按以下优先级处理：

🔴 ERROR 级别（必须修复，否则不能合并）：
  - 类型错误、编译错误
  - 高危安全漏洞（XSS、SQL 注入）
  - 明显的逻辑错误

🟡 WARNING 级别（强烈建议修复）：
  - 未处理的 async 错误
  - 有风险的代码模式

🟢 INFO 级别（本次可不处理，记录到 TODO）：
  - 代码可读性建议
  - 测试覆盖不足但功能正常的场景

---

三、变更影响面分析

3.1 何时必须做影响分析

以下情况提交代码前，必须分析影响范围：
✓ 修改了 API 接口的请求/响应结构
✓ 修改了被多处引用的公共工具函数
✓ 修改了数据库 Schema 或 ORM 映射
✓ 修改了权限、认证相关的逻辑
✓ 修改了计算逻辑（价格、数量、状态等）

3.2 手动影响面分析流程

# 步骤 1：找到被修改的核心类/函数
> 这次改动修改了 OrderCalculator 类，
  用 ide_find_references 找出所有引用它的地方

# 步骤 2：追溯调用链
> 用 ide_call_hierarchy 分析 calculateTotal 方法，
  找出所有可能调用到它的入口（Controller/API 层）

# 步骤 3：生成影响报告
> 汇总以上分析，输出：
  - 影响的接口清单
  - 风险等级（高/中/低）
  - 需要重点测试的场景

3.3 风险等级定义

高风险（上线前必须人工确认）：
  - 涉及资金计算
  - 影响所有用户的核心功能
  - 数据迁移操作

中风险（需要充分测试）：
  - 影响部分用户的重要功能
  - 接口参数变更（可能影响调用方）
  - 权限逻辑变更

低风险（标准测试流程）：
  - UI/样式调整
  - 非关键路径的逻辑变更
  - 新增功能（不修改已有逻辑）

---

四、生产故障快速响应

4.1 故障分级响应

P0 故障（服务完全不可用）→ 5 分钟内开始排查
P1 故障（核心功能受影响）→ 15 分钟内开始排查
P2 故障（部分功能异常）  → 30 分钟内开始排查

4.2 故障排查步骤

分钟 0-2：确认影响范围
├── 看监控：错误率、响应时间、QPS 变化
└── 初步判断：前端/后端/配置问题？

分钟 2-10：采集诊断数据
├── 收集错误日志（最近 5-10 分钟的 ERROR 级别）
├── 收集监控数据（QPS、错误率时序）
└── 查看最近的发布记录（什么时候开始出现？）

分钟 10-20：根因分析
├── 将采集的数据提供给 Claude 分析
├── 重点关注：最近有什么变更？（git log / 发布记录）
└── [门控] 确认根因后再动手

分钟 20-30：止血
├── 快速修复（最小改动）或回滚
├── 执行验证命令
└── 观察监控恢复

4.3 提供诊断数据的格式

给 Claude 的故障诊断输入格式：

服务名：xx-service
故障现象：[描述症状]
开始时间：今天 14:30 开始
影响范围：约 XX 用户，XX 接口
错误日志：
  [14:30:15] ERROR: NullPointerException at OrderService.java:145
  [14:30:16] ERROR: ...（粘贴关键日志）
最近变更：
  - 14:05 上线了 XX 功能（提交 abc1234）
  - 昨天修改了 OrderService 的 calculate 方法

4.4 回滚决策树

确认根因后，先判断是否需要回滚：

能快速修复（< 10 分钟）且影响可控？
    → 直接修复，不回滚

无法快速定位根因 或 影响持续扩大？
    → 立即回滚上一次发布
    → 回滚后再慢慢排查

修复代价高（改动多、测试复杂）？
    → 回滚先止血，下班后再计划修复

关键原则：止血优先，完美修复其次

---

五、调试工具速查表

场景	工具	操作
前端性能分析	Chrome DevTools MCP	录制 performance trace
代码调用链	IDE MCP	ide_call_hierarchy
接口影响面	IDE MCP	ide_find_references
全面代码审查	并行 Agent	多维度并行分析
生产故障诊断	日志 + Claude	采集日志 → Claude 分析

---

六、调试案例：一次完整的性能优化

场景：列表页加载时间从 1.2s 劣化到 3.8s。

Step 1：确认问题时间节点
> 查询最近发布记录，找出 3.8s 劣化是什么时候开始的
发现：今天 14:05 有一次发布，改动了列表渲染逻辑

Step 2：录制 trace
（通过 Chrome DevTools MCP）
> 录制一次列表页的性能 trace

Step 3：分析火焰图
> 分析这个 trace，找出 LCP 慢的原因
输出：renderProductCard 函数在每次渲染时都重新创建 taxRateMap

Step 4：代码定位
> 用 ide_find_references 找出 taxRateMap 的创建位置
> 读取相关代码片段

Step 5：修复
> taxRateMap 初始化应该移到组件外部，只创建一次
（Claude 实施修复）

Step 6：验证
> 再录制一次 trace，对比 LCP
输出：LCP 从 3.8s 恢复到 1.1s ✓

Step 7：记录
将"组件内重复初始化昂贵对象"记录到 learnings/patterns.md