📘 一套自用 Claude Code 进阶工作流完全指南：命令、子代理、技能三层分工
本指南提炼自个人长期的 Claude Code 深度编码实践，并在 2026-09-28 进行了全面升级。
核心理念：命令层手动触发明确意图 → 代理层委派执行重度任务 → 技能库按需自动/显式加载领域知识，基础层（CLAUDE.md + 陷阱库）全程兜底。
📺 视频全景讲解与演示
- 🎬 B 站高清视频：一套自用Claude Code 进阶工作流介绍以及用法：命令、子代理、技能三层分工，一期讲清怎么用 (BV1ega56yEp9)
视频长达 5 分钟，一期系统讲清三层分工机制、实战演练与命令调用演示。
〇、工作流架构总览
你的 Claude Code 工作流全景
│
├── 🎛️ 命令层 ~/.claude/commands/（17 个斜杠命令，手动触发）
├── 🤖 代理层 ~/.claude/agents/（14 个子代理，委派执行，独立上下文）
├── 🧰 技能库 ~/.agents/skills/（98 个技能，中央库，多 AI 工具共享）
│ ├── ~/.claude/skills/（Claude Code 入口，共 94 项）
│ │ ├── 80 个符号链接 → 指向中央库
│ │ ├── 7 个同名本地定制版（覆盖中央库版本）
│ │ └── 7 个本地私有技能（中央库专属）
│ └── 11 个中央技能未接入 Claude Code（为 Codex 等其它工具保留）
└── ⚙️ 基础层 全局 CLAUDE.md（工作原则）+ 踩坑陷阱库（PgSQL 本地存储，83+ 条记录）三层分工模型速查
| 层级 | 触发机制 | 核心职责 | 典型场景 |
|---|---|---|---|
| 命令层 | 用户输入 /名称 | 明确且规范的工作流入口 | 规划方案、编译修复、经验复盘、技能速查 |
| 代理层 | 说 “用 @名称 处理…” 或自动委派 | 拥有独立上下文的重量级任务 | 架构设计、安全审计、代码审查、构建救火 |
| 技能库 | 关键词语义自动触发 / 显式点名 | 按需注入的垂直领域知识与工具包 | 动效设计、画架构图、生图、PPT 生成、方法论 |
| 基础层 | 全局自动隐式生效 | 兜底执行规范与经验检索 | 编码语言规范、工具路径记录、防呆踩坑库 |
一、斜杠命令全表（17 个）
命令层用于约束日常高频动作，避免每次输入大量重复的 Prompt：
| 命令 | 核心作用 | 典型用法与适用时机 |
|---|---|---|
/help | 实时扫描命令、代理与技能库并生成全景手册 | /help、/help agents |
/plan | 核心铁律：需求复述 + 风险评估 + 3-5 步实现计划，确认后才动手写代码 | /plan 实现学生选课系统后端 |
/build-fix | 智能检测构建系统，以最小外科手术式改动增量修复报错 | 编译构建报红时直接运行 |
/quality-gate | 单文件代码质量门禁（格式化检查 + 坏味道分析） | /quality-gate src/main.py |
/test-coverage | 覆盖率分析 + 自动补充缺失单元测试，逼近 80%+ 覆盖率阈值 | 课程设计或交付前跑单测覆盖 |
/update-docs | 从源码、Schema、路由等权威源头逆向同步刷新 Markdown 文档 | 代码重构完同步 README |
/trap | 🔍 检索历史踩坑陷阱库（内置 83+ 条真实报错与避坑方案） | 同一类报错第二次出现时必查 |
/retrospect | 疑难 Bug 修复后将经验蒸馏沉淀至本地数据库 | 攻克耗时难题后一键复盘 |
/conventions | 全局行为规范（中文注释 / 命令附解释 / 英文附翻译 / 中文思考） | 检查当前规范是否严格对齐 |
/toolchain | 本地多语言工具链路径速查（Python/Java/Node/MinGW/PostgreSQL/Android） | 快速获取环境物理路径 |
/check_all_tool_position | 遍历扫描本机所有工具位置写入本地路径索引库 | 新装 SDK 或开发工具后运行一次 |
/skills | 分级浏览全局技能库（支持分类过滤与内部 README 查看） | /skills、/skills --all |
/skill-stats | 技能调用频率与健康度统计（从历史 transcript 中解析僵尸技能） | /skill-stats update |
/skill-guide | 编写新 Skill 的防呆清规（Windows + Git Bash 环境 6 条铁律） | 编写自定义技能前先读 |
/image2-half-2k | 调用 image2.5 模型生成 2K（2048×2048）超清视觉插图 | /image2-half-2k 赛博朋克风城市夜景 |
/image2-half-4k | 调用 image2.5 模型生成 4K（4096×4096）印刷级海报大图 | /image2-half-4k 科技风格主视觉 |
/notify_AskUserQuestion_persistence | 任务提问弹窗常驻开关（默认 true，常驻直到终端作答） | 配合任务通知插件联动使用 |
二、子代理全表（14 个）
子代理运行在独立的上下文窗口中，不会让主对话被海量的文件检索和中间编译日志撑爆：
| 代理 | 何时介入 | 工具权限 | 核心职责 |
|---|---|---|---|
@planner | 复杂多文件需求、重大架构重构前 | 只读权限 | 梳理依赖关系、边界分析与分步落地计划 |
@architect | 系统分层设计、微服务拓扑、E-R 建模与选型 | 只读权限 | 防范循环依赖、单向依赖审查与架构解耦 |
@tdd-guide | 新功能编写或核心逻辑重构 | 读写 + 终端 | 驱动红-绿-重构循环，确保分支覆盖 |
@build-error-resolver | JS/TS 构建、Webpack/Vite、npm 报错救火 | 读写 + 终端 | 外科手术式修复第一行致命报错，严禁扩大修改面 |
@code-reviewer | 功能代码写完后的最后一道防线 | 只读 + 终端 | 审查小函数原则（<50行）、防御性检查与命名 |
@security-reviewer | 处理用户输入、鉴权 Token、SQL、敏感数据 | 只读 + 终端 | 防范 OWASP Top 10、注入、SSRF、越权与密钥泄露 |
@refactor-cleaner | 长期迭代后的代码库治理 | 读写 + 终端 | 清理未导出死函数、无用依赖与废弃文件 |
@docs-lookup | 查阅前沿框架最新 API 规范与官方示例 | 只读 + 联网 | 避免 AI 根据陈旧预训练知识臆造废弃方法 |
@frontend-scout | 前端第三方库选型把关 | 读写 + 联网 | 严谨核查许可证、周下载量、打包体积与更新频率 |
@cpp-reviewer | C++ 现代特性与核心模块质量把控 | 只读 + 终端 | 内存泄漏排查、智能指针安全与并发竞态审查 |
@cpp-build-resolver | CMakeLists.txt 链接、g++/MSVC 编译排错 | 读写 + 终端 | 解决符号未定义、头文件循环包含与库链接失败 |
@java-reviewer | Spring Boot 课设与企业级后端审查 | 只读 + 终端 | 分层解耦（Controller/Service/Repo）与事务隔离 |
@java-build-resolver | Maven / Gradle 依赖冲突与打包报错 | 读写 + 终端 | 解决 NoSuchMethodError、版本传递冲突与镜像源配置 |
@database-reviewer | 复杂 SQL 优化、索引设计与慢查询治理 | 只读 + 终端 | EXPLAIN 执行计划分析、避免全表扫描与索引失效 |
三、技能库导览（中央库 98 个 + 本地私有 7 个）
技能是按需挂载的专业知识容器，平时不占用主上下文，只有在触发对应任务时才被按需拉取：
中央技能库精选板块分布
├── 📐 工程方法论 superpowers (TDD、小步重构、防御性编程)
├── 🛠️ 工程自动化 mattpocock/skills (Git 工作流、代码治理)
├── ✍️ 宝玉系列技能 (深度翻译、概念科普图谱、技术小册撰写)
├── 🎨 UI / UX 设计 (ui-ux-pro-max，Design Tokens，彻底告别 AI 塑料感)
├── ⚡ 顶级动效法则 (emilkowalski 缓动函数、阻尼动效、合成器优化)
├── 🎬 视频合成 (HyperFrames 编程式短视频与宣发素材生成)
└── 🏛️ 架构绘图 (Mermaid 规范表达、系统时序图、微服务交互图)技能调用的两大黄金法则
- 自动关键词感知：编写网页样式时自动激活
ui-ux-design-tokens；遇到复杂报错自动触发trap检索； - 显式点名唤醒：在主对话中直接说 “用 baoyu-translate 翻译这篇论文” 或 “用 archify-diagram 画出系统时序图”。
四、四大典型高频实战场景闭环
场景 1：实现一个复杂的跨模块新功能
- 输入命令：运行
/plan 需求描述； - 代理委派：由
@planner仔细阅读项目根目录的 README、代码规范与现有结构，给出 3-5 步实现方案； - 确认动手：用户人工 Review 计划无误后，再调用写工具生成代码；
- 质量门禁：完成后委派
@code-reviewer审查代码行数、类型安全与中文注释规范。
场景 2：构建或编译彻底炸了
- 输入命令：直接运行
/build-fix； - 代理委派：
@build-error-resolver捕捉第一条致命错误行； - 精准修复：绝不大面积重写文件，只修复导致类型不兼容或配置缺失的关键代码行；
- 编译复测：自动重新执行构建命令验证是否通过。
场景 3：遇到隐蔽玄学 Bug 第二次重现
- 先查陷阱库：在动手乱改前，运行
/trap 关键报错关键词； - 经验对齐：匹配历史排查记录中的根本原因（例如：Windows 编码乱码、路径转义、Docker 挂载权限）；
- 修复复盘：修复成功后运行
/retrospect，将本次隐蔽坑点一键沉淀进知识库。
场景 4：编写前端页面去除“AI 塑料味”
- 审美禁令生效：严禁无脑居中 + 紫蓝渐变（
from-purple-600 to-blue-500）； - 设计令牌先行：使用严格的 4px/8px 网格阶梯间距，应用深色 4 层明度阶梯底色；
- 交互状态闭环：显式提供
:hover,:focus-visible,:active,:disabled状态； - 动效天花板：采用
cubic-bezier(0.16, 1, 0.3, 1)非线性阻尼缓动。
🔗 相关开源生态与自制插件链接
- 视频中提到的自制开源作品：
- 🔔 Claude Code Task Notify（桌面弹窗通知）
- 📜 Claude Conventions Skill（全局规范）
- 🪄 Neovim Cursor for JetBrains（光标拖尾插件）
- 主流社区开源技能库：
