1. 为什么你的 Claude Code 用起来像“高级聊天框”很多人第一次打开 Claude Code输入一句“帮我改个 bug”看它噼里啪啦读文件、跑命令、改代码会觉得这玩意儿挺神。但用上一周就会发现每次新开会话它都像失忆一样项目结构要重新讲一遍代码规范要重新强调一遍昨天刚说过的“别用 any 类型”今天又忘了。这不是模型不行而是你还没把 Claude Code 从“对话工具”升级成“工程化 Agent”。Claude Code 的本质是模型推理能力 工具调用能力的组合。模型是大脑工具是双手。它能自主读代码、改文件、跑命令、查文档通过“收集上下文 → 采取行动 → 验证结果”的代理循环完成任务。但循环的质量取决于你给它喂了什么上下文、封装了什么技能、接入了什么外部工具。这篇文章聚焦三条主线CLAUDE.md 项目记忆、Skills 技能封装、MCP 工具接入。我会给出可直接复制的 CLAUDE.md 模板、Skills 目录结构、MCP 配置片段以及每一步的验证动作。适合已经用过 Claude Code 基础功能、想把它变成可复用工作流的开发者。如果你还在纠结怎么拿到 API Key、怎么配环境文末的接入部分也会覆盖。先说一个我踩过的坑早期我把所有规则都塞进对话里结果上下文窗口很快被占满Claude 开始“忘事”。后来才明白持久规则要放 CLAUDE.md按需知识要封装成 Skills外部能力要通过 MCP 接入。这三者分工明确混在一起用只会让 Token 账单和你的血压一起飙升。下面按六个部分展开每一部分都有可复制的配置和验证步骤。2. TaoToken 前置准备把 Base URL 和 Key 配好在折腾 CLAUDE.md、Skills、MCP 之前得先确保 Claude Code 能正常调用模型。如果你用的是官方订阅可以跳过这部分如果你希望通过 API 方式接入、方便统一管理 Key 和成本那这一步是基础。TaoToken 提供的是兼容 Anthropic 接口的 API 服务Claude Code 可以直接把 Base URL 指向它。你需要准备三样东西Base URL、API Key、Model ID。这三件套在后续的 MCP 配置、Codex auth.json、Cline MCP 里都会反复出现建议先记下来。2.1 获取 API Key访问 TaoToken 控制台创建一个 API Key。地址是https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite创建后复制 Key形如sk-xxxxxxxx。注意不要把它提交到 Git 仓库建议放在环境变量或本地配置文件中。2.2 配置 Claude Code 的 Base URLClaude Code 通过环境变量读取 API 配置。在~/.zshrc或~/.bashrc中加入export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的Key export ANTHROPIC_MODELclaude-sonnet-4-20250514如果你用的是 Windows PowerShell对应写法$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api $env:ANTHROPIC_API_KEYsk-你的Key $env:ANTHROPIC_MODELclaude-sonnet-4-20250514保存后执行source ~/.zshrc让配置生效。注意 Base URL 后面不要加/v1Claude Code 会自己拼接路径。2.3 验证连通性在终端执行claude --version确认 Claude Code 已安装。然后进入任意项目目录运行claude -p 用一句话说明当前目录是什么项目如果返回了合理的描述说明 Base URL 和 Key 配置成功。如果报 401检查 Key 是否复制完整如果报连接超时检查 Base URL 是否写成了https://taotoken.net/api不要带 UTM 参数UTM 只用于网页跳转。2.4 模型选择建议不同任务对模型的要求不同。日常编码和文件操作Sonnet 系列足够复杂重构、多步推理可以切到 Opus 系列。你可以在会话中用/model命令临时切换也可以在环境变量里固定默认模型。配置好这一步后面的 CLAUDE.md、Skills、MCP 才有意义。否则你封装再多技能模型调不通也是白搭。3. CLAUDE.md 项目记忆模板让 Claude 每次开局就懂你CLAUDE.md 是 Claude Code 在每个会话开始时自动加载的项目说明文件。它占用主上下文所以内容要精炼建议控制在 200 行以内。放什么放“始终执行”的核心规则构建命令、代码规范、目录约定、禁止事项。3.1 文件位置与加载顺序Claude Code 会按以下顺序查找并加载 CLAUDE.md位置作用范围是否提交 Git./CLAUDE.md当前项目建议提交./CLAUDE.local.md当前项目本地覆盖不提交~/.claude/CLAUDE.md全局所有项目不提交子目录./src/CLAUDE.md特定目录建议提交加载顺序是全局 → 项目 → 子目录后面的会覆盖前面的。你可以用/init命令让 Claude 自动生成一份初始 CLAUDE.md然后手动精简。3.2 可复制的 CLAUDE.md 模板下面这份模板我用了几个月覆盖了大多数中大型项目的需求。你可以直接复制按项目实际情况修改# 项目说明 这是一个 TypeScript Node.js 的后端服务使用 Fastify 框架PostgreSQL 数据库Prisma ORM。 ## 构建与测试命令 - 安装依赖pnpm install - 开发启动pnpm dev - 运行测试pnpm test - 类型检查pnpm typecheck - 代码格式化pnpm format ## 代码规范 - 禁止使用 any必要时用 unknown 加类型守卫 - 所有导出函数必须有显式返回类型 - 使用 zod 做运行时校验不要手写 if 判断 - 错误处理统一用 AppError 类不要直接 throw new Error - 日志用 pino不要用 console.log ## 目录约定 - src/routes/ 放路由定义每个文件对应一个资源 - src/services/ 放业务逻辑不直接操作数据库 - src/repositories/ 放数据访问层Prisma 调用只在这里出现 - src/schemas/ 放 zod schema - tests/ 放集成测试单元测试与被测文件同目录 ## 禁止事项 - 不要修改 prisma/migrations/ 下的已有迁移文件 - 不要提交 .env 文件 - 不要在生产代码中使用 console.log - 不要跳过测试直接提交 ## Compact Instructions 压缩上下文时保留当前修改的文件路径、最近的测试结果、未完成的 TODO 列表。 可以丢弃已完成的文件读取内容、重复的命令输出。3.3 验证 CLAUDE.md 是否生效在项目根目录启动 Claude Code输入请复述一下本项目的构建命令和代码规范中关于 any 的要求如果 Claude 能准确说出pnpm dev和“禁止使用 any”说明 CLAUDE.md 加载成功。如果它答不上来检查文件是否在项目根目录、文件名大小写是否正确必须是CLAUDE.md不是claude.md。3.4 用 .claude/rules/ 拆分大型规则如果项目规则超过 200 行建议拆到.claude/rules/目录按路径或语言匹配加载。例如.claude/ rules/ typescript.md python.md api-design.md在 CLAUDE.md 中引用## 规则文件 - TypeScript 规范见 .claude/rules/typescript.md - API 设计规范见 .claude/rules/api-design.md这样只有匹配到对应文件类型时才会加载完整规则节省上下文。你可以用/context命令查看当前上下文占用情况确认规则文件是否被按需加载。4. Skills 技能封装把重复工作流变成一条命令Skills 是 Claude Code 的按需加载能力。会话开始时只加载 Skill 的描述真正调用时才加载完整内容。这比把所有东西塞进 CLAUDE.md 节省大量 Token。适合封装API 文档、部署清单、代码审查流程、重复性工作流。4.1 Skills 目录结构Skills 放在.claude/skills/目录下每个 Skill 一个文件夹核心文件是SKILL.md.claude/ skills/ deploy/ SKILL.md checklist.md api-review/ SKILL.md endpoints.md security-audit/ SKILL.mdSKILL.md的头部用 YAML frontmatter 定义元信息--- name: deploy description: 部署服务到生产环境包含预检查、构建、发布、验证四个阶段 disable-model-invocation: false --- # 部署流程 ## 预检查 1. 确认当前分支是 main 2. 确认 pnpm test 全部通过 3. 确认 pnpm typecheck 无错误 4. 检查 .env.production 是否存在 ## 构建 bash pnpm build发布pnpm deploy:prod验证访问/health端点确认返回 200检查日志中是否有 ERROR 级别输出确认数据库迁移已应用### 4.2 调用 Skill 在 Claude Code 会话中输入 /deployClaude 会加载这个 Skill 并按照流程执行。你也可以用自然语言触发“帮我走一遍部署流程”Claude 会根据 description 匹配到对应的 Skill。 ### 4.3 disable-model-invocation 的用法 如果某个 Skill 只希望手动调用、不希望模型自动触发设置 yaml disable-model-invocation: true这样会话开始时连描述都不会加载只有你显式输入/skill-name时才加载。适合那些不常用、但内容很长的参考手册。4.4 Skill Subagent 组合对于需要并行处理的任务可以在 Skill 中定义 Subagent。例如一个安全审计 Skill--- name: security-audit description: 并行运行安全性、性能、代码风格三个维度的审查 --- # 安全审计 启动三个 Subagent 并行工作 1. 安全性 Subagent检查 SQL 注入、XSS、敏感信息泄露 2. 性能 Subagent检查 N1 查询、内存泄漏、慢查询 3. 风格 Subagent检查命名规范、注释完整性、测试覆盖率 每个 Subagent 返回摘要主代理汇总后输出报告。Subagent 拥有独立上下文完成后只返回摘要不会污染主对话。这比在主会话里逐个检查节省大量 Token。4.5 验证 Skills 是否生效输入/skills查看已加载的 Skill 列表。如果看不到你创建的 Skill检查目录结构是否正确必须是.claude/skills/name/SKILL.md文件名大小写敏感。然后输入/deploy测试调用观察 Claude 是否按流程执行。5. MCP 工具接入让 Claude 连上数据库和外部服务MCPModel Context Protocol是连接外部服务的标准协议。通过 MCPClaude 可以查数据库、发 Slack 消息、操作浏览器、调用内部 API。MCP 提供“能力”Skill 提供“知识”——MCP 是厨房和设备Skill 是菜谱和出品标准。5.1 MCP 配置片段MCP 服务器配置放在.claude/settings.json或~/.claude/settings.json中。下面是一个连接 PostgreSQL 的配置示例{ mcpServers: { postgres: { command: npx, args: [ -y, modelcontextprotocol/server-postgres, postgresql://user:passwordlocalhost:5432/mydb ] }, filesystem: { command: npx, args: [ -y, modelcontextprotocol/server-filesystem, /Users/yourname/projects ] } } }如果你用的是 Cline 或 Claude Desktop配置位置不同但结构一致。Cline 的 MCP 配置在cline_mcp_settings.json中格式相同。5.2 三件套Base URL Key Model ID在 MCP 配置中如果某个服务器需要调用模型同样需要三件套。以 Codex 的auth.json为例{ base_url: https://taotoken.net/api, api_key: sk-你的Key, model: claude-sonnet-4-20250514 }这三个字段在 Claude Code、Cline MCP、Codex auth.json 中含义一致只是字段名可能略有不同。配置时注意不要漏掉任何一个。5.3 验证 MCP 连接在 Claude Code 中输入/mcp查看已连接的 MCP 服务器列表和状态。如果显示connected说明连接成功。然后测试调用请查询 users 表中最近注册的 5 个用户如果 Claude 能返回查询结果说明 MCP 工作正常。如果报local proxy failed检查 MCP 服务器命令是否正确、端口是否被占用。如果报reading choices错误通常是返回数据格式不符合预期检查 MCP 服务器版本是否与 Claude Code 兼容。5.4 MCP 成本控制MCP 服务器的工具定义和 JSON Schema 会在每个请求中加载占用上下文。如果某个 MCP 服务器不常用建议在不需要时禁用。用/context查看各 MCP 服务器的上下文占用用/mcp检查连接状态和成本。5.5 Skill MCP 组合模式MCP 提供连接Skill 教导如何使用。例如--- name: db-query description: 按照团队规范查询数据库 --- # 数据库查询规范 ## 连接 使用 postgres MCP 服务器连接。 ## 查询规范 1. 所有查询必须带 LIMIT默认 100 2. 禁止 SELECT *必须显式列出字段 3. 时间范围查询必须用 created_at 索引 4. 复杂查询先 EXPLAIN确认走索引 ## 示例 查询最近 7 天注册用户 sql SELECT id, email, created_at FROM users WHERE created_at NOW() - INTERVAL 7 days ORDER BY created_at DESC LIMIT 100;这样 Claude 不仅知道“能连数据库”还知道“怎么查才符合团队规范”。 ## 6. 常见报错排查401、local proxy failed、reading choices 配置过程中最容易遇到几类报错这里逐一排查。 ### 6.1 401 Unauthorized **现象**调用模型时返回 401提示 invalid api key。 **原因**API Key 错误、过期、或没有正确传入。 **排查步骤** 1. 检查环境变量 ANTHROPIC_API_KEY 是否设置echo $ANTHROPIC_API_KEY 2. 确认 Key 没有多余空格或换行 3. 确认 Base URL 是 https://taotoken.net/api不是网页地址 4. 如果用的是配置文件检查 JSON 格式是否正确字段名是否为 api_key ### 6.2 local proxy failed **现象**MCP 连接时报 local proxy failed 或 connection refused。 **原因**MCP 服务器启动失败、端口被占用、或命令路径错误。 **排查步骤** 1. 手动运行 MCP 服务器命令看是否报错npx -y modelcontextprotocol/server-postgres ... 2. 检查端口是否被占用lsof -i :端口号 3. 确认 npx 在 PATH 中which npx 4. 如果是 Windows检查是否需要 cmd /c 前缀 ### 6.3 reading choices 错误 **现象**调用模型时返回 error reading choices 或类似格式错误。 **原因**API 返回格式与 Claude Code 预期不符通常是 Base URL 指向了不兼容的接口。 **排查步骤** 1. 确认 Base URL 是 https://taotoken.net/api不要加 /v1 或 /chat/completions 2. 确认 Model ID 是 Anthropic 格式如 claude-sonnet-4-20250514不是 OpenAI 格式 3. 用 curl 直接测试接口 bash curl -X POST https://taotoken.net/api/v1/messages \ -H x-api-key: sk-你的Key \ -H anthropic-version: 2023-06-01 \ -H content-type: application/json \ -d {model:claude-sonnet-4-20250514,max_tokens:100,messages:[{role:user,content:hi}]}如果 curl 能返回正常结果说明接口没问题问题在 Claude Code 配置。6.4 OAuth 相关报错现象提示OAuth token expired或authentication failed。原因如果你用的是官方订阅登录OAuth token 可能过期。排查步骤运行claude logout然后claude login重新登录如果用的是 API Key 方式确认没有同时启用 OAuth检查~/.claude/下的配置文件是否有冲突6.5 Skills 不加载现象输入/skills看不到自定义 Skill。排查步骤确认目录是.claude/skills/name/SKILL.md确认文件名是SKILL.md不是skill.md或SKILLS.md确认 frontmatter 格式正确name和description字段存在重启 Claude Code 会话6.6 CLAUDE.md 不生效现象Claude 不遵守 CLAUDE.md 中的规则。排查步骤确认文件在项目根目录文件名是CLAUDE.md运行/context查看 CLAUDE.md 是否被加载确认规则没有与全局~/.claude/CLAUDE.md冲突如果规则太长Claude 可能忽略部分内容建议精简到 200 行以内7. 把三条主线串起来从配置到可复用工作流到这里CLAUDE.md、Skills、MCP 三条主线已经分别讲完。最后说一下怎么把它们组合起来形成真正可复用的工程化工作流。一个典型的组合模式是CLAUDE.md 放核心规则Skills 放按需知识MCP 提供外部能力。比如一个 API 开发项目CLAUDE.md 中写“所有 API 必须遵循.claude/rules/api-design.md中的规范错误处理统一用AppError。”Skills 中封装一个api-review技能包含完整的 API 设计检查清单和示例。MCP 中接入数据库和 Slack让 Claude 能查表结构、发通知。这样当你输入“帮我审查一下新增的/users接口”时Claude 会自动加载 CLAUDE.md 中的规则、调用api-reviewSkill 中的检查清单、通过 MCP 查询数据库确认字段类型最后给出审查报告。如果你想进一步扩展可以尝试 Agent Teams——多个 Claude Code 会话协作共享任务列表、互相通信。目前支持 Agent Teams 的模型有限使用前确认你的模型是否在支持列表中。最后给一个实用建议每次调整 CLAUDE.md 或新增 Skill 后用/context检查上下文占用。如果发现某个 Skill 或 MCP 服务器占用过高考虑设置disable-model-invocation: true或在不使用时禁用。上下文是稀缺资源省下来的 Token 就是省下来的钱。如果你还没有配置好 API 接入可以从 TaoToken 的模型对话页面先测试接口连通性https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite确认模型能正常返回后再回到 Claude Code 中配置 Base URL 和 Key。接入文档在这里https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite长期做编码和 Agent 任务的可以了解 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite配置过程中遇到问题优先检查三件套Base URL、Key、Model ID。这三个对了剩下的就是熟练度问题。