1. 三种扩展机制到底在解决什么问题Claude Code 用久了会遇到一个分水岭刚开始你只是在对话框里敲需求它帮你改代码但当项目变大、团队协作变多、重复性任务变频繁之后你会发现每次都要重新交代一遍背景、每次都要重复描述某个流程、每次让它审查代码都会把主对话刷得乱七八糟。这时候就需要扩展机制出场了。Claude Code 目前提供三种扩展方式CLAUDE.md、Skill、Subagent。它们经常被混为一谈因为看起来都是写一个文件让 Claude 更懂你但实际作用层面完全不同。CLAUDE.md 解决的是你需要知道什么Skill 解决的是这件事怎么做Subagent 解决的是独立干完一件事再回来汇报。理解这三句话选型基本就不会错。我见过不少人在项目根目录堆了一个几百行的 CLAUDE.md把构建命令、代码规范、API 文档、部署流程全塞进去结果每次对话上下文都被占掉一大块真正需要的那条规范反而被淹没。也见过把本该做成 Subagent 的代码审查逻辑硬写成 Skill导致审查过程把主对话刷屏后面想接着改代码都找不到上下文。这些坑的根源都是没搞清楚三者的边界。这篇文章会从上下文注入、能力封装、任务委派三个维度拆开讲每个机制给出可复制的配置片段和验证动作最后给出一套按项目规模快速定位的判断方法。如果你正在纠结某个逻辑该放哪里可以直接跳到第 5 节的排查对照表。2. TaoToken 前置准备让 Claude Code 稳定跑起来在深入三种机制之前得先保证 Claude Code 本身能稳定调用模型。Claude Code 默认走 Anthropic 官方接口但国内网络环境下经常遇到连接超时、401 鉴权失败、local proxy failed 这类报错。TaoToken 提供兼容 Anthropic 协议的接入层把 Base URL 指向它就能绕开这些网络问题同时保留 Claude Code 的全部扩展能力。你需要准备三样东西Base URL、API Key、Model ID。这三件套在后续所有配置里都会反复出现建议先记下来。Base URL 填https://taotoken.net/api注意这里不加任何查询参数。API Key 到控制台创建路径是 console创建后复制那串以sk-开头的字符串。Model ID 根据你要用的模型填比如claude-sonnet-4-20250514这类官方标识。配置方式有两种。第一种是环境变量适合临时测试export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的key export ANTHROPIC_MODELclaude-sonnet-4-20250514第二种是写进 Claude Code 的 settings 文件适合长期使用。项目级配置放在.claude/settings.json个人级放在~/.claude/settings.json{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_API_KEY: sk-你的key, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }如果你用的是 Codex 或 Cline 这类工具配置位置不同但三件套逻辑一致。Codex 走~/.codex/auth.jsonCline 走 MCP 配置里的env字段。不管哪个工具Base URL、Key、Model ID 缺一不可少一个就会报鉴权或模型找不到的错。配好之后先别急着写扩展文件跑一个最小验证在项目目录下执行claude进入交互模式输入列出当前目录的文件能正常返回就说明接入通了。如果报 401检查 Key 有没有复制完整如果报 local proxy failed检查 Base URL 是不是写成了带 UTM 参数的地址——API 地址不要带查询参数。这一步通了之后三种扩展机制才有意义。否则你写的 CLAUDE.md 再规范模型调不通也是白搭。3. 三种机制的可复制配置与验证这一节把三种机制的配置片段全部给出来你可以直接复制到项目里跑。每个片段后面都跟一个验证动作确认它真的生效了。3.1 CLAUDE.md会话启动时自动加载的项目背景CLAUDE.md 放在项目根目录Claude Code 启动时会自动全量读进上下文。它适合写几乎每次任务都成立的约定比如技术栈、命名规范、构建命令、提交信息格式。一个典型的 CLAUDE.md 长这样# 项目背景 这是一个基于 FastAPI PostgreSQL 的后端服务Python 3.11用 uv 管理依赖。 ## 构建与测试 - 安装依赖uv sync - 跑测试uv run pytest -x - 启动开发服务uv run uvicorn app.main:app --reload ## 代码规范 - 所有 commit message 必须带 feat: / fix: / chore: 前缀 - 新增接口必须同步更新 docs/api.md - 数据库迁移用 alembic不要手写 SQL ## 目录约定 - app/routers/ 放路由 - app/models/ 放 ORM 模型 - app/services/ 放业务逻辑如果你同时用 Codex 或 Cursor可以维护一份 AGENTS.md 作为跨工具标准然后在 CLAUDE.md 里用AGENTS.md桥接导入AGENTS.md ## Claude Code 专属补充 - 优先使用 Read/Grep 而不是 cat/grep 命令验证动作在项目目录下启动claude输入这个项目用什么跑测试如果它直接答出uv run pytest -x说明 CLAUDE.md 加载成功。如果答不出来检查文件名是不是CLAUDE.md全大写以及是不是放在项目根目录而不是子目录。3.2 Skill按需加载的操作手册Skill 放在.claude/skills/name/SKILL.md会话开始时 Claude 只看到它的 description真正用到时才加载全文。它适合封装一套具体流程比如某个 API 的调用规范、某种文档的写作模板。一个 Skill 的最小结构--- name: api-convention description: 当需要新增或修改 HTTP 接口时使用包含本项目的接口设计规范 allowed-tools: Read, Grep --- # 接口设计规范 ## URL 命名 - 资源用复数/users 而不是 /user - 嵌套资源不超过两层/users/{id}/orders 可以再深就拆 ## 请求与响应 - 请求体统一用 JSON字段名用 snake_case - 响应统一包一层 { data: ..., error: null } - 错误码用 HTTP 状态码 业务码组合 ## 示例 新增用户接口 POST /users { name: 张三, email: zhangsanexample.com } 返回 { data: { id: 1, name: 张三 }, error: null }allowed-tools字段可以限定这个 Skill 被调用时能用哪些工具比如只给 Read 和 Grep防止它误改文件。验证动作在对话里输入我要新增一个查询订单的接口观察 Claude 是否自动引用 api-convention 这个 skill。如果没触发检查 description 写得够不够具体——description 是 Claude 判断是否加载的唯一依据写得太泛比如接口相关它匹配不上。3.3 Subagent独立上下文执行的任务委派Subagent 放在.claude/agents/name.md项目级或~/.claude/agents/name.md个人级。被委派时它新开一个独立上下文窗口过程不进入主对话只把结论带回来。它适合读很多文件、跑很多步骤、不想污染主对话的重活。一个代码审查 Subagent 的例子--- name: java-reviewer description: 当需要审查 Java 代码质量时使用只读不改输出审查报告 tools: Read, Grep, Glob --- 你是一个 Java 代码审查专家。你的任务是审查指定目录下的 Java 代码检查以下方面 1. 空指针风险是否有未做 null 检查的直接调用 2. 资源泄漏InputStream、Connection 等是否在 finally 或 try-with-resources 中关闭 3. 并发问题共享可变状态是否有同步保护 4. 异常处理是否吞掉了异常或只打印不处理 输出格式 ## 审查报告 ### 严重问题 - 文件:行号 - 问题描述 ### 建议改进 - 文件:行号 - 问题描述 ### 总结 一句话概括整体质量。tools字段限定它只能用 Read、Grep、Glob不能写文件这样审查过程绝对安全。验证动作在对话里输入用 java-reviewer 审查 src/main/java 目录观察它是否独立跑完并只返回报告主对话里不会出现它读文件的中间过程。如果主对话被刷屏了说明它没被识别为 Subagent检查文件是不是放在.claude/agents/下、frontmatter 里的name和文件名是否一致。3.4 三者组合Skill 与 Subagent 不是互斥的一个 Subagent 内部可以引用某个 Skill 作为参考知识。比如文档撰写子代理可以调用公司写作规范 skill。反过来一个 Skill 也可以通过context: fork配置把任务派发到某个 Subagent 去执行。组合配置示例在 Skill 里指定 fork--- name: deep-search description: 当需要在代码库中做深度搜索时使用 context: fork agent: Explore --- 搜索目标{{query}} 请在整个代码库中查找相关实现返回文件路径和关键代码片段。这样这个 Skill 被触发时实际执行的是 Explore 这个 Subagent搜索过程不会进入主对话。4. 验证请求与成功结果对照配置写完不算完得实际跑一遍确认行为符合预期。这一节给出三个验证场景和对应的成功结果你可以照着对照。场景一验证 CLAUDE.md 自动加载。启动claude后直接问这个项目的 commit message 格式要求是什么。成功结果是它不假思索地答出feat:/fix:/chore:前缀不需要你去提醒。如果它反问你你想用什么格式说明 CLAUDE.md 没加载。场景二验证 Skill 按需触发。输入帮我写一个新的用户注册接口。成功结果是它先引用 api-convention skill 的规范然后按规范生成代码URL 用/users复数、响应包data字段。如果它直接按自己的习惯写说明 skill 没匹配上。场景三验证 Subagent 上下文隔离。输入用 java-reviewer 审查 src/main/java。成功结果是主对话里只出现一条委派消息和最终报告中间读文件的过程完全不显示。你可以用/context命令查看当前上下文占用如果审查前后主对话的 token 数没有明显增长说明隔离生效了。三个场景都通过之后再跑一次真实任务做端到端验证。比如让 Claude 新增一个接口并提交观察它是否同时用到了 CLAUDE.md 的提交规范、Skill 的接口规范、以及是否在需要时自动委派 Subagent 做审查。这种组合行为才是三种机制协同工作的样子。如果某个场景没通过先别急着改配置按下一节的排查表逐项对照。5. 本篇常见错误排查这一节列出实际使用中最容易踩的坑每条都对应真实报错或异常行为。报错 401 Unauthorized模型调用被拒。检查ANTHROPIC_API_KEY是否完整有没有多余空格。如果用的是 settings.json确认 JSON 格式合法env字段下的 key 名拼写正确。TaoToken 的 Key 在 API Keys 页面创建复制时注意别漏字符。报错 local proxy failedBase URL 配置有问题。确认填的是https://taotoken.net/api不要带任何查询参数。如果你从别处复制了带 UTM 的地址把?后面的部分全部删掉。报错 reading choices 或返回空模型 ID 写错了。检查ANTHROPIC_MODEL是不是官方标识比如claude-sonnet-4-20250514。有些第三方模型 ID 不被 Claude Code 识别换回官方标识再试。OAuth 相关报错如果你之前登录过 Anthropic 官方账号本地可能残留 OAuth token和 API Key 冲突。清掉~/.claude/下的凭据缓存或者显式设置ANTHROPIC_API_KEY覆盖。CLAUDE.md 不生效三个检查点。文件名必须全大写CLAUDE.md必须放项目根目录如果用了AGENTS.md桥接确认 AGENTS.md 也在根目录且路径正确。Skill 不触发description 写得太泛。Claude 靠 description 做语义匹配写接口相关不如写当需要新增或修改 HTTP 接口时使用。另外确认文件路径是.claude/skills/name/SKILL.md目录名和 frontmatter 里的name一致。Subagent 刷屏主对话说明它没被识别为 Subagent。检查文件是否在.claude/agents/下frontmatter 是否有name和descriptiontools字段格式是否正确。如果放在~/.claude/agents/下则是个人级所有项目都能用。CC Switch / Cline MCP / Codex auth.json 配置遗漏这三个工具的三件套位置不同。CC Switch 在它的配置文件里填 Base URL Key Model IDCline 在 MCP 配置的env字段里填Codex 在~/.codex/auth.json里填。任何一个少填都会导致鉴权失败对照本文第 2 节的三件套逐项核对。排查顺序建议从模型接入开始接入不通后面全是白搭。接入通了再查扩展文件路径最后查 description 匹配。按这个顺序走大部分问题五分钟内能定位。6. 按项目规模选型与后续动作三种机制不是三选一而是按需组合。小项目可能一个 CLAUDE.md 就够了中等项目加几个 Skill大项目才需要 Subagent 做任务隔离。判断口诀再重复一遍这条规则几乎每次任务都用得上放 CLAUDE.md这是一套具体操作流程、只在特定场景需要、任何 agent 都能复用做成 Skill这是一个独立任务、会读很多文件、跑很多步骤、不希望过程刷屏主对话、需要限定工具权限做成 Subagent。如果你现在的规范审查逻辑以后想变成写代码时顺手检查一下、不需要独立开任务的轻量模式可以考虑把部分逻辑也做成 Skill但只要还是完整独立跑一遍、只读、出报告的模式保持 Subagent 就是对的。想验证不同模型在三种机制下的表现差异可以到模型对话里直接试。长期做编码和 Agent 任务的话Coding Plan 的额度更划算。接入过程中遇到报错先对照第 5 节排查还搞不定就翻接入文档里面有三件套的完整说明。最后给一个实操建议先把 CLAUDE.md 写扎实这是所有扩展的地基。地基稳了再往上加 Skill最后才考虑 Subagent。别一上来就三个全上配置越多排查成本越高。等你能稳定判断这个逻辑该放哪的时候三种机制才算真正用明白了。