Baji_Rtc_Toy/Claude Code插件高效运用指南.md

# Claude Code 插件高效运用指南

> 更新日期: 2026-04-13（新增 GSD 执行框架 + 完善工具链全景）
> 适用环境: macOS / Claude Code 2.1.79+ / ESP32 嵌入式开发

---

## 一、当前已安装资源总览

| 类别 | 数量 | 说明 |
|------|------|------|
| 官方插件 (claude-plugins-official) | 7 个 | Git 工作流、代码审查、功能开发、迭代循环、规则维护、Skill 创建 |
| 社区插件 (claude-code-settings) | 2 个 | 长时任务自主执行、规格驱动开发 |
| **GSD 执行框架** | **68 个 Skills** | 防上下文腐烂、任务编排、context monitor、原子提交 |
| 自定义 Skills (~/.claude/skills/) | 11 个 | ESP32 专用 6 个 + RK3588/Linux 驱动 4 个 + 硬件驱动工作流 1 个 |
| 第三方 Skills (~/.claude/skills/) | 5 个 | find-skills、tmux、summarize、tavily-research、embedded-systems |
| 内置 Skills | 6 个 | simplify、loop、claude-api、schedule、update-config、keybindings-help |

---

## 二、命令速查表

| 命令 | 来源 | 一句话说明 |
|------|------|-----------|
| `/commit` | commit-commands | 自动分析变更，生成提交信息并 commit |
| `/commit-push-pr` | commit-commands | 一键 commit → push → 创建 PR |
| `/clean_gone` | commit-commands | 清理远程已删除的本地分支 |
| `/code-review` | code-review | 4 个 Agent 并行审查，置信度过滤 |
| `/review-pr` | pr-review-toolkit | 6 个专业 Agent 综合 PR 审查 |
| `/feature-dev` | feature-dev | 7 阶段引导式功能开发 |
| `/ralph-loop` | ralph-loop | 迭代式自引用开发循环，持续直到任务完成 |
| `/cancel-ralph` | ralph-loop | 取消正在运行的 Ralph Loop |
| `/claude-md-improver` | claude-md-management | 审计 CLAUDE.md，检查与代码库一致性 |
| `/revise-claude-md` | claude-md-management | 从当前会话提取经验更新 CLAUDE.md |
| `/autonomous-skill` | autonomous-skill | 多会话长时任务自主执行 |
| `/spec-kit-skill` | spec-kit-skill | 7 阶段规格驱动开发工作流 |
| `/skill-creator` | skill-creator | **元技能**：交互式创建、测试、优化自定义 Skills |
| `/simplify` | 内置 | 审查代码复用性、质量和效率 |
| `/loop` | 内置 | 定时循环执行命令（如每 5 分钟检查一次） |
| `/schedule` | 内置 | 创建/管理定时远程 Agent（cron 定时任务） |
| `/update-config` | 内置 | 配置 settings.json 的 hooks 自动化行为 |
| `/keybindings-help` | 内置 | 自定义 Claude Code 键盘快捷键 |
| `/ralph-loop help` | ralph-loop | 查看 Ralph Loop 插件说明和可用命令 |

---


## 三、按场景分类的使用指南

### 场景 1：日常编码提交（每天用）

#### `/commit` — 智能提交

**何时用**：写完代码，需要提交时

**使用方式**：
```
你：/commit
```
Claude 会自动：
1. 运行 `git diff` 分析所有变更
2. 理解变更内容和意图
3. 生成符合项目风格的提交信息
4. 执行 `git commit`

**对比手动提交的优势**：
- 不用自己写 commit message
- 自动识别变更类型（feat/fix/refactor）
- 遵循项目已有的提交风格

---

#### `/commit-push-pr` — 一键发布

**何时用**：功能开发完成，需要提交 + 推送 + 创建 PR

**使用方式**：
```
你：/commit-push-pr
```
一步完成三件事，适合功能分支开发完成后快速发布。

---

#### `/clean_gone` — 清理分支

**何时用**：定期清理，或感觉本地分支太多时

**使用方式**：
```
你：/clean_gone
```
自动清理所有远程已删除但本地仍残留的分支（`git branch` 中标记为 `[gone]` 的）。

---

### 场景 2：代码审查（提交前 / PR 合并前）

#### `/code-review` — 快速审查

**何时用**：提交前快速检查是否有明显问题

**使用方式**：
```
你：/code-review
```

**工作原理**：启动 4 个并行 Agent
1. CLAUDE.md 合规检查 ×2（检查代码是否遵循项目规则）
2. Bug 扫描（检测潜在 Bug）
3. Git 历史上下文分析（结合 git log 理解变更背景）

置信度 < 80 的问题自动过滤，只报告高确信度问题。

**适合**：日常快速检查，耗时较短

---

#### `/review-pr` — 深度审查

**何时用**：重要功能合并前的全面审查

**使用方式**：
```
你：/review-pr
```

**工作原理**：启动 6 个专业 Agent
| Agent | 检查内容 |
|-------|---------|
| code-reviewer | 代码质量、Bug、安全漏洞 |
| comment-analyzer | 注释准确性和可维护性 |
| silent-failure-hunter | 静默失败和错误处理缺陷 |
| pr-test-analyzer | 测试覆盖质量 |
| type-design-analyzer | 类型设计质量（封装、不变量） |
| code-simplifier | 代码简化机会 |

**适合**：重要 PR、团队协作代码、关键功能上线前

**`/code-review` vs `/review-pr` 如何选择？**
| | `/code-review` | `/review-pr` |
|---|---|---|
| Agent 数量 | 4 个 | 6 个 |
| 耗时 | 较短 | 较长 |
| 深度 | 快速扫描 | 全面审查 |
| 使用频率 | 每次提交前 | 重要 PR 合并前 |

---

### 场景 3：功能开发（新功能 / 复杂任务）

#### `/feature-dev` — 引导式功能开发

**何时用**：开发新功能，需要系统性地理解代码库并设计方案

**使用方式**：
```
你：/feature-dev 添加 OTA 远程固件升级功能
```

**7 阶段工作流**：
```
阶段 1: 理解代码库 → code-explorer Agent 分析现有架构
阶段 2: 提问澄清   → 向你提出关键问题（如 OTA 源、回滚策略）
阶段 3: 需求确认   → 确认功能范围和约束
阶段 4: 架构设计   → code-architect Agent 设计方案
阶段 5: 实现       → 按设计方案编码
阶段 6: 审查       → code-reviewer Agent 检查实现质量
阶段 7: 总结       → 输出变更摘要
```

**ESP32 项目实际用例**：
```
你：/feature-dev 新增 BLE OTA 固件升级功能
你：/feature-dev 添加 MQTT 设备影子同步
你：/feature-dev 实现多语言 TTS 语音切换
```

**优势**：避免直接写代码导致的架构混乱，先理解再动手

---

#### `/autonomous-skill` — 长时任务自主执行

**何时用**：任务太大，一个会话搞不定（如大规模重构、全项目代码迁移）

**使用方式**：
```
你：/autonomous-skill 将项目从 ESP-IDF v5.1 迁移到 v5.4
```

**工作原理**：
1. **Initializer Agent**：分析任务，分解为子任务清单
2. 生成 `.autonomous/<task-name>/task_list.md` 和 `progress.md`
3. **Executor Agent**：逐个执行子任务，自动更新进度
4. 会话中断后，下次启动自动从 `progress.md` 继续

**适合**：
- 跨多文件的大规模重构
- 框架/SDK 版本迁移
- 全项目代码规范统一

---

### 场景 4：迭代式开发（调试 / 持续改进）

#### `/ralph-loop` — 持续迭代直到完成

**何时用**：任务需要多轮尝试才能完成（如调试、性能调优）

**使用方式**：
```
你：/ralph-loop 优化 GIF 动画播放性能，目标是音频不卡顿
```

**工作原理**：
- Claude 完成一轮后尝试退出 → Stop Hook 拦截 → 重新注入 prompt → 继续迭代
- 直到任务真正完成才停止

**取消方式**：
```
你：/cancel-ralph
```

**适合**：
- 性能调优（反复测量-修改-验证）
- 复杂 Bug 排查（需要多轮假设-验证）
- 代码质量持续改进

**注意**：会消耗较多 token，确保任务值得持续迭代

---

### 场景 5：知识管理（CLAUDE.md 维护）

#### `/claude-md-improver` — 审计规则文件

**何时用**：定期维护（建议每 1-2 周一次），或感觉 CLAUDE.md 与实际代码不一致时

**使用方式**：
```
你：/claude-md-improver
```

**输出**：
- 质量报告（一致性评分、过时内容、遗漏项）
- 自动更新建议
- 与当前代码库对比的差异分析

---

#### `/revise-claude-md` — 提取会话经验

**何时用**：解决了一个复杂问题后，在会话结束前执行

**使用方式**：
```
你：/revise-claude-md
```

**工作原理**：
- 回顾当前会话中的所有踩坑经验、解决方案、架构决策
- 自动提取有价值的内容更新到 CLAUDE.md
- 避免下次遇到同样问题

**最佳实践**：
```
解决完 Bug → 测试通过 → /revise-claude-md → /commit
```

---

### 场景 6：代码简化（内置）

#### `/simplify` — 代码简化审查

**何时用**：写完代码后，检查是否有可简化的地方

**使用方式**：
```
你：/simplify
```

**检查内容**：
- 代码复用机会
- 不必要的复杂度
- 可删除的冗余代码
- 保持功能不变的前提下简化实现

---

### 场景 7：自定义 Skill 创建与优化（元技能）

#### `/skill-creator` — 从零创建专业领域 Skills

**何时用**：需要为新的技术领域（如 Linux 驱动、Android HAL、新硬件平台）创建专属的 Claude Code Skill

**来源**：Anthropic 官方插件（claude-plugins-official），是一个"元技能"（Meta-Skill）— 专门用来创建其他 Skills 的 Skill。

**使用方式**：
```
你：/skill-creator
```

**四种操作模式**：

| 模式 | 命令 | 说明 |
|------|------|------|
| **Create** | `/skill-creator` | 通过交互式问答从零创建新 Skill，自动生成 SKILL.md |
| **Eval** | `/skill-creator eval` | 运行测试用例，对比有/无 Skill 的效果差异 |
| **Improve** | `/skill-creator improve` | 基于评测反馈自动迭代改进 Skill（最多 5 轮） |
| **Benchmark** | `/skill-creator benchmark` | A/B 盲测对比，量化 Skill 对输出质量的提升 |

**内置 4 个子 Agent**：

| Agent | 职责 |
|-------|------|
| Executor | 执行 Skill，生成输出结果 |
| Grader | 对输出结果评分（质量、准确性、完整性） |
| Comparator | A/B 盲测对比（有 Skill vs 无 Skill） |
| Analyzer | 分析评测结果，生成改进建议 |

**完整工作流程（Create 模式）**：

```
步骤 1: 捕获意图   → 理解你想让 Skill 做什么
步骤 2: 问答调研   → 收集边界情况、格式要求、依赖工具等
步骤 3: 编写 SKILL.md → 按最佳实践自动生成（含 frontmatter + 指令内容）
步骤 4: 定义测试用例 → 生成 2-3 个真实测试提示
步骤 5: 运行评估   → 执行 with-skill 和 baseline 对比打分
步骤 6: 迭代改进   → 根据反馈自动优化 SKILL.md 内容
步骤 7: 优化触发词 → 微调 description 字段提升触发精度
```

**实际用例**：

```
# 从零创建 Linux 驱动开发 Skill
你：/skill-creator
Claude：你想创建什么领域的 Skill？
你：Linux 内核驱动开发，包括设备树 DTS、GPIO/I2C/SPI 驱动、V4L2 摄像头驱动

# 从文档资料创建 Skill
你：/skill-creator
你：（提供 RK3588 SDK 文档、Android HAL 开发指南等资料）
Claude：自动消化资料 → 生成结构化的 SKILL.md

# 评估并优化已有 Skill
你：/skill-creator eval ~/.claude/skills/linux-driver/SKILL.md
你：/skill-creator improve ~/.claude/skills/linux-driver/SKILL.md
```

**生成的 SKILL.md 标准格式**：

```yaml
---
name: my-skill-name
description: 描述功能和触发时机（决定何时自动激活）
allowed-tools: Bash, Read, Grep, Glob    # 可选，限制可用工具
---

# Skill 标题

## 审查清单 / 排障速查表 / 构建流程
（结构化的专业知识内容）
```

**Skill 存放位置**：

| 范围 | 路径 | 说明 |
|------|------|------|
| 个人全局 | `~/.claude/skills/<name>/SKILL.md` | 所有项目通用（如你的 ESP32 Skills） |
| 项目级 | `.claude/skills/<name>/SKILL.md` | 仅当前项目 |
| 插件提供 | 插件安装目录内 | 通过 `claude plugins install` 安装 |

**与手动创建 Skill 的对比**：

| | 手动创建 | `/skill-creator` |
|---|---|---|
| 方式 | 自己编写 SKILL.md | 交互式引导 + 自动生成 |
| 测试 | 凭感觉验证 | 自动化评测 + A/B 对比 |
| 迭代 | 手动修改 | 自动分析 + 5 轮迭代优化 |
| 触发精度 | 靠经验写 description | 自动优化触发词 |
| 适合 | 熟悉 Skill 格式的用户 | 任何用户，尤其是新领域拓展 |

**最佳实践**：

```
准备资料（文档/教程/代码示例）
    ↓
/skill-creator（Create 模式，喂入资料）
    ↓
/skill-creator eval（评估效果）
    ↓
/skill-creator improve（迭代优化）
    ↓
投入使用，后续根据实际踩坑经验持续补充
```

---

### 场景 8：定时任务与远程 Agent

#### `/schedule` — 定时远程 Agent

**何时用**：需要周期性自动执行任务（如定时检查构建状态、定期代码审查、自动同步等）

**使用方式**：
```
你：/schedule                          # 查看和管理定时任务
你：/schedule create                   # 创建新的定时 Agent
你：/schedule list                     # 列出所有已创建的定时任务
你：/schedule run <trigger-name>       # 手动触发执行一次
```

**工作原理**：
- 基于 cron 表达式定义执行周期
- 每次触发时启动一个远程 Agent（headless 模式）
- Agent 执行完毕后自动停止，下次 cron 时间到达再启动

**ESP32 项目实际用例**：
```
# 每天早上 9 点自动检查代码规范
你：/schedule create "每天 9:00 运行 /code-review 检查未提交的代码"

# 每周一自动审计 CLAUDE.md
你：/schedule create "每周一 /claude-md-improver"
```

---

### 场景 9：配置自动化与快捷键

#### `/update-config` — 配置 hooks 自动化行为

**何时用**：需要设置自动化行为，如"每次提交前自动运行 lint"、"每次保存文件后自动格式化"

**使用方式**：
```
你：/update-config
你：帮我配置一个 hook，每次执行 Edit 工具后自动检查代码风格
```

**工作原理**：
- 修改 `~/.claude/settings.json` 中的 hooks 配置
- Hooks 是 Claude Code 的事件钩子系统，在特定事件（工具调用前/后、会话开始/结束等）自动执行 shell 命令
- 与 Skills 的区别：Skills 影响 Claude 的行为，Hooks 是在 Claude 行为之外自动执行的外部命令

**配置示例**：
```json
{
  "hooks": {
    "PostToolUse": [
      {
        "matcher": "Edit",
        "command": "echo '文件已修改'"
      }
    ]
  }
}
```

---

#### `/keybindings-help` — 自定义键盘快捷键

**何时用**：想修改 Claude Code 的默认快捷键，或添加自定义快捷键组合

**使用方式**：
```
你：/keybindings-help
你：帮我把提交快捷键改为 Ctrl+S
你：添加一个 chord 快捷键
```

**工作原理**：
- 修改 `~/.claude/keybindings.json` 文件
- 支持单键绑定和 chord 组合键（如 `Ctrl+K, Ctrl+C`）
- 可覆盖默认快捷键或新增自定义绑定

---

## 四、ESP32 项目推荐工作流

### 日常开发流程

```
编码 → /simplify（检查简化）→ /commit（提交）
```

### 新功能开发流程

```
/feature-dev（引导开发）→ 编码 → 构建测试 → /code-review（快速审查）→ /commit-push-pr（发布）
```

### 重要功能上线流程

```
/feature-dev → 编码 → 构建测试 → /review-pr（深度审查）→ 修复审查问题 → /commit-push-pr
```

### 复杂 Bug 排查流程

```
/ralph-loop 排查并修复xxx问题 → 修复完成 → /revise-claude-md（记录经验）→ /commit
```

### 大规模重构流程

```
/autonomous-skill（自主执行重构）→ 检查结果 → /review-pr（审查）→ /commit-push-pr
```

### 定期维护流程（每 1-2 周）

```
/claude-md-improver（审计规则）→ /clean_gone（清理分支）
```

### 新领域 Skill 创建流程

```
收集资料（文档/教程/API手册）→ /skill-creator（创建）→ /skill-creator eval（评估）→ /skill-creator improve（优化）
```

**示例**：为香橙派 CM5 (RK3588S) 创建 Linux 驱动开发 Skills：
```
1. 准备 Rockchip BSP 文档、Linux 内核驱动教程、设备树语法说明
2. /skill-creator → 创建 linux-driver Skill
3. /skill-creator → 创建 android-hal Skill
4. /skill-creator → 创建 rk3588-build Skill
5. /skill-creator eval → 评估效果 → /skill-creator improve → 迭代优化
```

---

## 五、自定义 Skills 与自动触发

### Skills 自动触发机制

当前对话中，以下 Skills 会根据关键词自动激活：

| Skill | 触发条件 |
|-------|---------|
| esp-build | 你说"编译"、"构建"、"烧录" |
| esp-analyze-log | 你提供设备日志、提到 crash/panic |
| esp-troubleshoot | 你描述设备异常 |
| esp-optimize | 你提到"优化"、"内存不足" |
| esp-code-review | 你要求"代码审查"、"review" |
| esp-driver | 你说"写一个驱动" |
| linux-driver | 你说"Linux 驱动"、"设备树"、"内核模块" |
| android-hal | 你说"HAL"、"AIDL"、"HIDL"、"JNI" |
| rk3588-build | 你说"编译 SDK"、"刷机"、"Docker 编译环境" |
| rk3588-troubleshoot | 你描述驱动不工作、设备不识别、内核崩溃 |
| simplify | 通过 /simplify 调用 |
| loop | 通过 /loop 调用 |
| claude-api | 涉及 Anthropic SDK 开发（import anthropic / @anthropic-ai/sdk） |
| schedule | 通过 /schedule 调用，或提到"定时任务"、"cron"、"定期执行" |
| update-config | 通过 /update-config 调用，或提到"配置 hooks"、"自动化行为"、"settings.json" |
| keybindings-help | 通过 /keybindings-help 调用，或提到"快捷键"、"键盘绑定"、"rebind" |
| **hw-driver-workflow** | 提供原理图/数据手册/参考代码，或说"帮我写驱动"、"适配芯片"、"分析原理图" |
| **find-skills** | 说"有没有xxx的Skill"、"找一个Skill" |
| **summarize** | 说"总结"、"压缩"、提供长文档/URL 要求提取关键信息 |
| **tavily-research** | 说"调研"、"搜索"、"查一下xxx的资料"、需要在线查找技术方案 |
| **tmux** | 需要监控终端日志、长时间编译、远程会话管理 |
| **embedded-systems** | 涉及固件开发、RTOS、中断处理、DMA、功耗优化、裸机编程、volatile 声明等通用嵌入式工程原则 |

### ESP32 Skills 与插件配合

| 自定义 Skill | 触发方式 | 与插件配合 |
|-------------|---------|-----------|
| esp-build | "帮我编译" / "构建项目" | 编译 → `/commit` 提交 |
| esp-analyze-log | 提供日志文件路径 | 分析日志 → 修复 → `/revise-claude-md` 记录 |
| esp-troubleshoot | 描述设备异常现象 | 排障 → `/ralph-loop` 持续调试 |
| esp-optimize | "优化内存" / "固件太大" | 优化 → `/simplify` 检查 → `/commit` |
| esp-code-review | "帮我审查代码" | 先 esp-code-review → 再 `/review-pr` 双重审查 |
| esp-driver | "写一个I2C驱动" | `/feature-dev` 设计 → esp-driver 生成 → `/code-review` 审查 |

### RK3588/Linux 驱动 Skills 与插件配合

| 自定义 Skill | 触发方式 | 与插件配合 |
|-------------|---------|-----------|
| linux-driver | "写一个 GPIO/I2C/SPI 驱动" | `/feature-dev` 设计 → linux-driver 生成 → `/code-review` 审查 |
| android-hal | "开发 HAL 让 APP 控制硬件" | linux-driver 写驱动 → android-hal 写 HAL → `/review-pr` 审查 |
| rk3588-build | "编译内核" / "刷机" / "搭建编译环境" | 编译 → 刷机 → `/revise-claude-md` 记录踩坑 |
| rk3588-troubleshoot | "设备不识别" / "内核崩溃" | 排障 → `/ralph-loop` 持续调试 → `/revise-claude-md` 记录 |

---

## 六、注意事项

1. **Token 消耗**：`/review-pr`（6 Agent）和 `/ralph-loop`（持续迭代）消耗较多 token，按需使用
2. **`/ralph-loop` 需要手动取消**：通过 `/cancel-ralph` 停止，否则会一直运行
3. **`/autonomous-skill` 的进度文件**：保存在 `.autonomous/` 目录，不要手动删除未完成的任务
4. **`/spec-kit-skill` 依赖外部工具**：需要安装 GitHub Spec-Kit CLI，目前 ESP32 项目用不到
5. **插件更新**：运行 `claude plugins update` 可更新所有插件到最新版本
6. **`/skill-creator` 资料质量决定 Skill 质量**：喂入的文档越专业、越详细，生成的 Skill 审查清单和排障表越准确。建议提供官方文档 + 实战踩坑经验的组合
7. **Skill 持续迭代**：首次创建的 Skill 不一定完美，随着实际开发中遇到新问题，持续补充更新 SKILL.md（类似你现有 ESP32 Skills 的演进过程）
8. **`/schedule` 定时任务**：需要网络连接才能触发远程 Agent，离线环境下无法使用
9. **`/update-config` 修改 hooks**：hooks 配置错误可能阻塞工具调用，修改前建议备份 `settings.json`
10. **快捷键配置文件**：位于 `~/.claude/keybindings.json`，格式错误会导致快捷键失效

---

## 七、文件路径速查

| 文件 | 路径 | 说明 |
|------|------|------|
| 全局规则 | `~/.claude/CLAUDE.md` | 所有项目通用的指令规则 |
| 插件配置 | `~/.claude/settings.json` | enabledPlugins、hooks、permissions |
| 快捷键 | `~/.claude/keybindings.json` | 自定义键盘快捷键 |
| 自定义 Skills | `~/.claude/skills/<name>/SKILL.md` | 个人全局 Skills |
| 项目级 Skills | `.claude/skills/<name>/SKILL.md` | 仅当前项目生效 |
| 项目级规则 | `.claude/CLAUDE.md` 或项目根 `CLAUDE.md` | 项目专属指令 |
| 自动记忆 | `~/.claude/projects/<path>/memory/` | 跨会话持久化记忆 |
| 官方插件缓存 | `~/.claude/plugins/cache/claude-plugins-official/` | 下载的插件文件 |
| 社区插件缓存 | `~/.claude/plugins/cache/claude-code-settings/` | 第三方插件文件 |

---

## 八、新电脑环境恢复指南

### 8.1 开发环境信息

| 环境 | 版本 | 说明 |
|------|------|------|
| **ESP-IDF** | **v5.4.2** | 路径：`~/esp/esp-idf/v5.4.2/esp-idf/` |
| Claude Code | 最新版（npm 安装） | 当前 v2.1.79 |
| Node.js | 16+ | Claude Code 运行依赖 |
| Python | 3.8+ | ESP-IDF 构建依赖 |
| 操作系统 | macOS | ESP-IDF 通过 `export.sh` 激活环境 |

### 8.2 恢复步骤

#### 步骤 1：安装 Claude Code

```bash
npm install -g @anthropic-ai/claude-code
```

#### 步骤 2：恢复用户数据

如果 `~/.claude/` 目录已通过 Git 备份：

```bash
# 方式 A：直接 clone 到 ~/.claude/
git clone <你的仓库地址> ~/.claude

# 方式 B：已有 ~/.claude/ 目录（Claude Code 安装后自动创建）
cd ~/.claude
git init
git remote add origin <你的仓库地址>
git fetch origin
git checkout -f main
```

恢复后自动生效的内容（无需额外操作）：
- `CLAUDE.md` — 全局规则（ESP32/LVGL/BLE/RTC 开发经验）
- `skills/` — 11 个自定义 Skills（ESP32×6 + RK3588×3 + Android HAL + 硬件驱动工作流）
- `settings.json` — 插件开关配置
- `projects/*/memory/` — 各项目跨会话记忆

#### 步骤 3：重新安装插件

`settings.json` 中记录了插件开关，但插件代码（`plugins/cache/`）未纳入 Git 备份，需要重新下载：

```bash
# 官方插件（7 个）
claude plugins install commit-commands@claude-plugins-official
claude plugins install code-review@claude-plugins-official
claude plugins install pr-review-toolkit@claude-plugins-official
claude plugins install feature-dev@claude-plugins-official
claude plugins install ralph-loop@claude-plugins-official
claude plugins install claude-md-management@claude-plugins-official
claude plugins install skill-creator@claude-plugins-official

# 社区插件（2 个）
claude plugins install autonomous-skill@claude-code-settings
claude plugins install spec-kit-skill@claude-code-settings
```

#### 步骤 3.1：重新安装第三方 Skills

第三方 Skills 通过 `npx skills add` 安装，不在 Git 备份中，需要重新下载：

```bash
# 第三方 Skills（5 个）
npx skills add vercel-labs/skills@find-skills -g -y
npx skills add steipete/clawdis@tmux -g -y
npx skills add steipete/clawdis@summarize -g -y
npx skills add tavily-ai/skills@tavily-research -g -y
npx skills add https://github.com/jeffallan/claude-skills --skill embedded-systems -g -y
```

#### 步骤 3.2：安装 GSD 执行框架

GSD（Get Shit Done）是防上下文腐烂的任务编排框架，安装后自动启用 context monitor hook：

```bash
npx get-shit-done-cc@latest --claude --global
```

安装后自动配置：68 个 Skills + context monitor hook + read-before-edit guard + prompt injection guard。

#### 步骤 4：配置 API Key

```bash
# 设置 Anthropic API Key（环境变量，不在配置文件中）
export ANTHROPIC_API_KEY=你的密钥

# 建议写入 shell 配置文件持久化
echo 'export ANTHROPIC_API_KEY=你的密钥' >> ~/.zshrc
```

#### 步骤 5：安装 ESP-IDF v5.4.2

```bash
mkdir -p ~/esp && cd ~/esp
git clone -b v5.4.2 --recursive https://github.com/espressif/esp-idf.git v5.4.2/esp-idf
cd v5.4.2/esp-idf
./install.sh esp32s3    # 按需安装目标芯片（esp32s3/esp32c3 等）

# 激活环境
source ~/esp/esp-idf/v5.4.2/esp-idf/export.sh

# 验证
idf.py --version    # 应输出 ESP-IDF v5.4.2
```

### 8.3 恢复内容清单

| 内容 | 来源 | 需要下载 | 说明 |
|------|------|:---:|------|
| 全局规则 `CLAUDE.md` | Git 备份 | ❌ | clone 后自动生效 |
| 自定义 Skills（11 个） | Git 备份 | ❌ | clone 后自动生效 |
| 插件配置 `settings.json` | Git 备份 | ❌ | clone 后自动生效 |
| 项目记忆 `memory/` | Git 备份 | ❌ | clone 后自动生效 |
| 本指南文档 | Git 备份 | ❌ | clone 后自动生效 |
| 插件代码（9 个插件） | 远程下载 | ✅ | 执行 `claude plugins install`（步骤 3） |
| 第三方 Skills（5 个） | 远程下载 | ✅ | 执行 `npx skills add`（步骤 3.1） |
| GSD 执行框架（68 个 Skills） | 远程下载 | ✅ | 执行 `npx get-shit-done-cc@latest`（步骤 3.2） |
| Claude Code 程序 | npm 远程 | ✅ | 执行 `npm install -g` |
| ESP-IDF v5.4.2 | GitHub | ✅ | 执行 `git clone` + `install.sh` |
| API Key | 手动配置 | ✅ | 写入环境变量 |

---

## 九、GSD 执行框架与工具链协作

### 9.1 GSD 是什么

GSD（Get Shit Done）是一个防上下文腐烂的任务编排框架。它不替代你的 Skills 和插件，而是在**执行层**提供：
- **context monitor**：自动监控上下文窗口使用量，接近满时提醒处理
- **任务原子化**：大任务拆成小任务，每个任务在独立上下文窗口执行
- **持久化状态**：关键信息写入文件（PROJECT.md/STATE.md），不依赖对话记忆
- **原子提交**：每个任务完成后自动 git commit，支持回滚

### 9.2 你不需要记任何命令

**直接描述需求即可**，Claude 会根据任务复杂度自动选择执行方式：

| 任务规模 | Claude 的判断依据 | 执行方式 | Token 消耗 |
|---------|-----------------|---------|-----------|
| **小事** | 改动 1-2 个文件，几分钟搞定 | 直接做（或 /gsd-fast） | 低 |
| **中事** | 涉及 3-5 个文件，需要分析设计 | /gsd-quick | 中 |
| **大事** | 涉及 5+ 个文件，多阶段大任务 | /gsd-plan-phase + /gsd-execute-phase | 较高（但防腐烂） |

**举例**：
- "帮我修复这个编译错误" → 直接做
- "帮我写一个 I2C 温度传感器驱动" → 建议 /gsd-quick
- "把按键版的 6 个 Screen 迁移过来" → 建议 /gsd-plan-phase 拆分执行

如果你觉得 Claude 判断不准，可以直接说"用 quick 就行"或"这个比较大，拆开做"。

### 9.3 GSD 与 hw-driver-workflow 的协作关系

GSD 和 hw-driver-workflow 是**不同层**，不冲突：

```
┌─────────────────────────────────────────────────┐
│  hw-driver-workflow（领域层）                      │
│  知道嵌入式该怎么开发：硬件分析→方案→编码→调试→沉淀  │
│  + embedded-systems（通用嵌入式原则）               │
│  + esp-driver / linux-driver（平台 API 模板）      │
├─────────────────────────────────────────────────┤
│  GSD（执行层）                                    │
│  知道怎么拆任务、管上下文、防腐烂                    │
│  context monitor + 原子任务 + 独立上下文窗口        │
└─────────────────────────────────────────────────┘
```

**hw-driver-workflow 在什么时候被调用**：

| 任务规模 | hw-driver-workflow 是否参与 | 说明 |
|---------|:---:|------|
| 小事（改 Bug） | 通常不触发 | 纯代码修改不需要硬件分析流程 |
| 中事（写驱动） | ✅ 触发 | 提供硬件分析→方案→编码的领域知识 |
| 大事（模块迁移） | ✅ 触发 | GSD 拆任务，每个子任务中 hw-driver-workflow 提供嵌入式知识 |

**简单说**：GSD 管"怎么执行不腐烂"，hw-driver-workflow 管"嵌入式该怎么做"。

### 9.4 GSD 常用命令速查（按需使用）

| 命令 | 说明 | 使用频率 |
|------|------|---------|
| `/gsd-fast` | 极轻量执行，零子 Agent 开销 | 高频 |
| `/gsd-quick` | 轻量任务，带原子提交和状态追踪 | 高频 |
| `/gsd-do 你的需求` | 自动路由到正确的 GSD 命令 | 高频 |
| `/gsd-plan-phase N` | 创建详细任务计划 | 大任务 |
| `/gsd-execute-phase N` | 按波次并行执行计划 | 大任务 |
| `/gsd-verify-work N` | 验证交付物 | 大任务 |
| `/gsd-new-project` | 初始化新项目 | 新项目 |
| `/gsd-map-codebase` | 分析现有代码库架构 | 接手项目 |
| `/gsd-help` | 查看所有可用命令 | 随时 |

### 9.5 防上下文腐烂的覆盖范围

| 场景 | 是否防腐烂 | 机制 |
|------|:---:|------|
| 小任务直接对话 | ❌ | 对话短，不会腐烂，无需防护 |
| /gsd-fast | ⚠️ 部分 | context monitor 监控，但同一窗口 |
| /gsd-quick | ⚠️ 部分 | context monitor + 状态追踪 |
| /gsd-plan + execute | ✅ 完全 | 每个子任务独立 200K 上下文窗口 |
| GSD context monitor hook | ✅ 始终运行 | 任何对话中自动监控，接近满时提醒 |

> **注意**：GSD 的 context monitor hook 在**所有对话中**自动运行（包括小任务），它不消耗额外 Token，只在上下文接近满时才介入提醒。这是 GSD 安装后唯一"始终开启"的功能。