1. 从零散技巧到稳定工作流Claude Code 进阶能力到底解决什么问题Claude Code 用了一段时间之后很多人会卡在同一个瓶颈单次对话里它能帮你改代码、跑测试、查文档但每次开新会话之前交代过的规范、流程、校验步骤又得重新说一遍。Skills、Subagents、Hooks、MCP 这四个能力本质上就是把这套“每次都要重复交代”的东西沉淀成可复用的资产。Skills 负责封装团队规范和多步流程Subagents 负责把重型分析拆到独立上下文里跑Hooks 负责在生命周期节点上做确定性校验MCP 负责把外部工具接进来。它们组合起来才能把零散技巧变成稳定工作流。这篇文章面向已经上手 Claude Code、但还没系统用过这四个能力的开发者。我会按“问题场景 → 前置准备 → 可复制配置 → 验证步骤 → 排错 → 下一步”的顺序展开每个配置片段都能直接粘到项目里跑。如果你还没配置好模型接入可以先用 TaoToken 模型对话 验证一下请求链路是否通再往下做工作流编排。先说清楚这四个能力的分工避免混用能力触发方式上下文成本典型用途Skills显式/命令或自动匹配按需加载封装多步流程、团队规范SubagentsClaude 主动委派独立上下文主会话零成本重型分析、并行搜索Hooks生命周期事件自动触发通常零成本格式化、危险命令拦截MCPClaude 主动调用工具工具定义常驻数据库、浏览器、项目管理理解这张表后面所有配置都不会跑偏。我试过把这四样一股脑全塞进项目结果上下文被 MCP 工具定义占掉一大截反而拖慢了日常编码。所以顺序很重要先把 Skills 和 Hooks 跑通再引入 Subagents最后按需接 MCP。2. 前置准备接入配置与目录结构在写任何 Skill 之前先把模型接入和项目目录结构理清楚。Claude Code 的所有扩展能力都依赖一个稳定的 API 入口这里用 TaoToken 作为接入层它的 API 地址是https://taotoken.net/api兼容 Anthropic 的接口格式。2.1 环境变量与 Base URL 配置最省事的方式是通过环境变量注入避免把 Key 硬编码进配置文件。在~/.zshrc或~/.bashrc里加上export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的TaoToken密钥如果你用的是 Claude Code 的 settings 文件也可以写成 JSON。项目级配置放在.claude/settings.json用户级放在~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的TaoToken密钥 } }Key 的获取入口在 TaoToken API Keys生成后复制到上面两个位置之一即可。注意 Base URL 后面不要多加/v1Claude Code 会自己拼接路径多写反而会 404。2.2 项目目录结构Claude Code 的扩展文件有固定的查找路径先建好骨架mkdir -p .claude/skills .claude/agents .claude/hooks .claude/rules touch .claude/settings.json CLAUDE.md最终结构大致是这样项目根/ ├── CLAUDE.md ├── .claude/ │ ├── settings.json │ ├── rules/ │ │ └── api-rules.md │ ├── skills/ │ │ └── code-review/ │ │ └── SKILL.md │ ├── agents/ │ │ └── test-runner.md │ └── hooks/ │ └── block-dangerous.sh2.3 CLAUDE.md 保持精简CLAUDE.md 每次会话都会加载所以只放“每次都需要”的信息。控制在 200 行以内具体到可验证# 项目约定 ### 构建与测试 - 构建npm run build - 测试npm test - 开发npm run dev ### 代码规范 - 使用 2 空格缩进 - 所有 API 端点以 /api/v1 为前缀 - 错误响应格式{ error: { code, message } } ### 安全 - JWT_SECRET 从环境变量读取不硬编码 - 用户输入必须用 zod 验证特定场景的规则分流到.claude/rules/比如只对 API 路由生效的规则--- paths: - src/routes/**/*.ts --- # API 路由规则 - 每个路由文件导出 Express Router - 所有路由用 asyncHandler 包装 - 必须有对应的 zod schema这样前端规则不会干扰后端也节省了上下文。配置完成后用 TaoToken 接入文档 核对一下参数格式确认 Base URL 和 Key 都正确。3. 可复制配置Skills、Subagents、Hooks、MCP 四件套这一节是全文的核心每个配置片段都能直接复制。我会按“先 Skills、再 Subagents、再 Hooks、最后 MCP”的顺序给因为这是上下文成本从低到高的顺序。3.1 Skills封装团队代码审查流程Skill 就是一个带 YAML frontmatter 的 Markdown 文件。创建.claude/skills/code-review/SKILL.md--- name: code-review description: 审查代码变更的质量、安全性和性能输出分级反馈 --- # 代码审查流程 当被要求审查代码时按以下步骤执行 1. 运行 git diff 获取变更文件列表 2. 逐个文件审查关注 - 类型安全和边界条件 - 错误处理是否完整 - 性能隐患N1 查询、不必要的循环 - 安全漏洞SQL 注入、XSS 3. 输出分级反馈 - 重要合并前必须修复 - 小问题建议改进 - 预先存在不是本次变更引入的 ## 验证 - 运行 npm test 确认没有回归 - 运行 npm run lint 确认风格一致description字段写得越准自动匹配命中率越高。调用时直接输入/code-review或者自然语言说“帮我审查一下这个 PR”Claude 会自动加载。3.2 Subagents隔离重型分析任务子代理在独立上下文里跑主会话只收摘要。创建.claude/agents/test-runner.md--- name: test-runner description: 运行测试并分析失败原因区分真 bug 和测试本身需要更新 tools: Bash, Read, Grep model: haiku --- 你是测试分析专家。当被要求运行测试时 1. 执行项目的测试命令 2. 如果有失败分析失败原因 3. 区分“真正的 bug”和“测试本身需要更新” 4. 给出具体修复建议附上文件路径和行号关键字段说明字段作用tools限制可用工具审查类只给 Read/Grep 就够model简单任务用 haiku快且便宜isolation设为 worktree 可在隔离副本里跑把探索性的、中间产物多的任务交给子代理主会话保持干净。一个用 haiku 跑代码搜索的子代理成本远低于在主会话里用大模型做同样的事。3.3 Hooks确定性校验与危险命令拦截Hooks 在.claude/settings.json里配置。先写一个拦截危险命令的脚本.claude/hooks/block-dangerous.sh#!/usr/bin/env bash # 从 stdin 读取工具调用 JSON检查是否包含危险命令 input$(cat) command$(echo $input | jq -r .tool_input.command // empty) if echo $command | grep -qE rm -rf|DROP TABLE|TRUNCATE; then echo 阻止执行危险命令: $command 2 exit 2 fi exit 0赋予执行权限chmod x .claude/hooks/block-dangerous.sh然后在 settings.json 里注册{ hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: jq -r .tool_input.file_path | xargs npx prettier --write } ] } ], PreToolUse: [ { matcher: Bash, hooks: [ { type: command, command: .claude/hooks/block-dangerous.sh } ] } ] } }退出码 2 表示阻止操作。PostToolUse 在编辑后自动格式化PreToolUse 在执行前拦截危险命令。这两个都是确定性的不依赖 Claude “记得”去做。3.4 MCP接入数据库与外部工具MCP 让 Claude 能主动调用外部工具。以 SQLite 为例claude mcp add sqlite -- npx -y modelcontextprotocol/server-sqlite export SQLITE_DB_PATH./app.db配置作用域用--scope project可以写进.claude/settings.json团队共享{ mcpServers: { sqlite: { command: npx, args: [-y, modelcontextprotocol/server-sqlite], env: { SQLITE_DB_PATH: ${SQLITE_DB_PATH} } } } }敏感信息用环境变量传递不要硬编码。MCP 工具定义会常驻上下文所以只添加真正需要的工具。如果你只是偶尔查一次数据库直接在终端用 SQL 客户端更快。4. 验证请求一次完整任务链的跑通步骤配置写完不算完得验证整条链路能跑通。这一节用一个真实任务链给一个 Express 项目加一个“获取任务列表”的端点走完 Skill 创建、Hook 校验、Subagent 分析、MCP 查询的全流程。4.1 验证模型接入先确认 API 链路通。在项目根目录启动 Claude Codeclaude输入一个简单请求 读取 package.json告诉我项目用了哪些依赖如果返回了依赖列表说明 Base URL 和 Key 都正确。如果报 401回到第 2 节检查环境变量。如果报local proxy failed检查 Base URL 是否多写了/v1。4.2 验证 Skill 加载输入/code-review看 Claude 是否加载了审查流程。如果提示“未知命令”检查.claude/skills/code-review/SKILL.md的路径和 frontmatter 格式。YAML 的---必须顶格name和description不能缺。4.3 验证 Hook 触发让 Claude 编辑一个文件 在 src/utils/logger.ts 里加一行注释编辑完成后检查文件是否被 Prettier 格式化过。如果没生效先确认jq已安装jq --version没装的话macOS 用brew install jqLinux 用apt install jq。4.4 验证 Subagent 隔离让 Claude 做一个重型分析 分析 src/ 下所有文件找出没有错误处理的异步函数Claude 会委派给子代理。你只会看到最终摘要中间的文件读取过程不会进入主会话。如果子代理没被触发检查.claude/agents/test-runner.md的description是否匹配任务。4.5 验证 MCP 调用 查询 users 表里最近 7 天注册的用户数量Claude 会生成 SQL 并调用 SQLite MCP。如果报“工具不存在”运行claude mcp list确认服务器已注册。如果报连接错误检查SQLITE_DB_PATH是否指向真实文件。4.6 完整任务链验证把上面串起来走一次完整流程 /code-review 审查当前 git diff 分析 src/services/ 下有没有内存泄漏风险 查询 tasks 表里超过 30 天未更新的任务三个请求分别触发 Skill、Subagent、MCP。如果都能正常返回说明四件套已经跑通。这套链路验证下来你会发现每个能力各司其职互不干扰。5. 本篇常见错排查401、local proxy failed、reading choices、OAuth配置过程中最容易踩的坑集中在接入层和配置格式上。这一节按真实报错逐个排查。5.1 401 Unauthorized最常见的原因是 Key 没生效。排查顺序确认ANTHROPIC_API_KEY环境变量已导出echo $ANTHROPIC_API_KEY确认 Key 没有多余空格或换行确认 Base URL 是https://taotoken.net/api不是首页地址如果用了 settings.json确认 JSON 格式合法jq . .claude/settings.jsonKey 失效的话去 TaoToken API Keys 重新生成一个。5.2 local proxy failed这个报错通常和 Base URL 格式有关。检查两点Base URL 末尾不要加/v1Claude Code 会自己拼不要配置额外的代理环境变量除非你的网络环境确实需要如果确认格式没问题还是报错用 curl 直接测一下curl -X POST https://taotoken.net/api/v1/messages \ -H x-api-key: $ANTHROPIC_API_KEY \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:claude-sonnet-4-6,max_tokens:100,messages:[{role:user,content:hi}]}返回正常 JSON 说明链路通问题在 Claude Code 配置侧。5.3 reading choices 报错这个报错一般出现在响应解析阶段常见原因是模型返回格式不符合预期。排查确认请求的 Model ID 拼写正确比如claude-sonnet-4-6确认没有在请求里混用 OpenAI 格式的参数如果用了自定义 MCP 服务器检查它返回的数据结构是否符合协议Model ID 写错是最常见的原因。对照 TaoToken 模型对话 页面上的可用模型列表核对。5.4 OAuth 相关报错如果你用的是 Claude Code 的 OAuth 登录流程报错通常和 token 过期有关。排查运行claude logout再claude login重新走一遍确认系统时间准确OAuth token 对时间敏感如果同时配置了 API Key 和 OAuth优先用 API Key避免冲突5.5 Hook 不触发Hook 配置对了但没执行检查matcher字段是否匹配工具名Edit|Write是正则脚本是否有执行权限ls -l .claude/hooks/脚本退出码是否正确0 表示放行2 表示阻止5.6 Skill 自动匹配不命中description写得太模糊会导致自动匹配失败。把“审查代码”改成“审查代码变更的质量、安全性和性能输出分级反馈”命中率会明显提升。显式调用/code-review永远有效自动匹配只是锦上添花。6. 把工作流沉淀下来下一步怎么走四件套跑通之后接下来是把它们打包成团队资产。插件机制可以把 Skills、Agents、MCP 配置、Hooks 打包在一起分发。创建plugin.json{ name: team-workflow, version: 1.0.0, description: 团队标准工作流, skills: [skills/code-review], agents: [agents/test-runner.md], mcp: { servers: mcp/servers.json }, hooks: { config: hooks/hooks.json } }团队成员克隆仓库后用claude --plugin-dir ./plugin加载新同事入职就能直接用上验证过的最佳实践。如果你需要长期跑编码任务或 Agent 编排TaoToken Coding Plan 提供了更适合持续调用的方案。配置管理入口在 TaoToken Console可以集中查看用量和 Key 状态。最后给一个实用建议不要一次性把所有能力都上齐。先从 CLAUDE.md 和 Skills 开始跑顺了再加 Hooks等遇到重型分析任务再引入 SubagentsMCP 按需接。每加一层观察上下文占用和响应速度的变化。工作流的价值不在于功能多而在于稳定可复用——能让你每次开新会话都省下重复交代的时间这套配置就值了。
