Claude Code 玩法大全：从 CLAUDE.md 到 SubAgent 的进阶配置指南

1. 为什么你的 Claude Code 还停留在“高级搜索框”装好 Claude Code 之后很多人用了一周就放弃了理由出奇一致它好像也没比网页版强多少。问一句答一句改个 Bug 要来回贴代码项目一复杂就开始胡说八道。问题不在模型在于你只用了它的“对话层”没碰它的“工程层”。Claude Code 真正的分水岭是把它从“问答机器人”改造成“项目里的常驻协作者”。这中间有四根支柱CLAUDE.md 负责项目记忆MCP 负责连接外部世界SubAgent 负责分工并行Skills 负责把重复动作固化成一键命令。这四样东西单独看都不复杂组合起来才是一套稳定可复用的 AI 编码工作流。这篇不写安装默认你已经能跑起claude命令。接下来按“先给记忆、再给手脚、再给分工、最后给肌肉记忆”的顺序把每一块都落到可复制的配置和可验证的动作上。你照着做每一步都能立刻看到行为差异。2. 前置准备把模型接入层配稳在折腾 CLAUDE.md 和 MCP 之前先把底层接入配稳否则后面所有调试都会被“请求失败”干扰。我习惯用 TaoToken 作为统一的模型接入层它的 API 地址是https://taotoken.net/api兼容主流 SDK 的调用方式配置一次就能在多个工具间复用。先拿到 API Key。打开控制台页面https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite在 API Keys 页面创建一个新 Key复制出来。这个 Key 后面会写进环境变量不要直接硬编码到项目文件里。接着把它写进 shell 配置。macOS 或 Linux 用户编辑~/.zshrc或~/.bashrcexport TAOTOKEN_API_KEYsk-你的key export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEY$TAOTOKEN_API_KEYWindows 用户在 PowerShell 里用setx设置或者直接在系统环境变量面板里加。设置完执行source ~/.zshrc让配置生效然后echo $ANTHROPIC_BASE_URL确认输出正确。这里有个容易踩的点Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个变量名字写错它不会报错只会默默走默认地址然后超时。所以配完一定要回显确认。如果你用的是别的客户端接入文档在https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite里面有各语言的调用示例。底层通了之后再往上叠 CLAUDE.md 这些能力出问题时你才能确定是“配置逻辑错”而不是“网络没通”。3. CLAUDE.md给项目写一份会自我进化的员工手册CLAUDE.md 是 Claude Code 每次启动自动读取的文件。你可以把它理解成新员工入职时拿到的那本手册项目用什么框架、代码风格什么要求、测试怎么跑、哪些坑不能踩。没有它Claude 每次会话都像第一天上班什么都要问一遍。3.1 一份可直接复制的骨架在项目根目录建CLAUDE.md先填这五块# CLAUDE.md ## 项目概述 FastAPI React 全栈应用。后端 Python 3.12前端 TypeScript Vite。 数据库 PostgreSQL缓存 Redis。 ## 编码规范 - 后端遵循 Google Python Style Guide变量 snake_case - 所有 API 入参必须用 Pydantic model 校验 - 前端组件用函数式写法禁止 class component - commit message 用 Conventional Commits ## 常用命令 - 启动后端cd backend uvicorn main:app --reload - 跑测试pytest tests/ -v - 前端启动cd frontend pnpm dev - 数据库迁移alembic upgrade head ## 已知坑点 - 测试环境 Redis 用 fakeredis不要连真实实例 - DatePicker 在 Safari 有兼容问题临时用 native input - 禁止调用生产环境任何外部接口 ## 目录结构 - backend/app/api/ 路由层 - backend/app/services/ 业务逻辑 - frontend/src/components/ 通用组件写完保存重启 Claude Code然后问它“这个项目怎么跑测试”。如果它直接答出pytest tests/ -v说明读取成功。3.2 多级 CLAUDE.md 的合并逻辑CLAUDE.md 不只能放根目录。它支持三层叠加Claude 会自动合并位置作用典型内容~/.claude/CLAUDE.md全局个人偏好回复用中文、习惯 vim 键位项目根/CLAUDE.md项目级规范框架选型、API 设计、测试策略子目录/src/auth/CLAUDE.md模块级上下文该模块负责 OAuth2依赖 jwt 库模块级写得越精确生成代码越贴合。比如在src/auth/CLAUDE.md里写清楚“token 过期时间统一从配置读取不要硬编码 3600”Claude 在这个目录下干活时就不会再犯这个错。3.3 让它自己写教训一个很实用的习惯每次 Claude 犯了错别只是手动改掉直接让它把教训追加进 CLAUDE.md。比如它误用了同步阻塞的数据库调用你就说“把这条教训写进 CLAUDE.md 的已知坑点”。随着项目迭代这个文件越来越厚同类错误会肉眼可见地减少。这比每次会话重复叮嘱高效得多。4. MCP给 Claude 接上数据库和外部工具MCP 全称 Model Context Protocol是 Claude Code 连接外部能力的标准接口。没有 MCP它只能读写本地文件和跑命令有了 MCP它能查数据库、操作 GitHub、调 API。4.1 配置片段MCP 的配置写在~/.claude/settings.json或项目级.claude/settings.json。下面是一个 GitHub MCP 的例子{ mcpServers: { github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_TOKEN: ghp_你的token } } } }也可以用命令行添加claude mcp add github \ --command npx \ --args -y modelcontextprotocol/server-github \ --env GITHUB_TOKENghp_你的token配置完执行claude mcp list能看到 github 这条就说明注册成功。4.2 一个容易踩的坑MCP 装好了不代表 Claude 会主动用。很多时候它会选择更笨的方式完成任务比如你让它建 PR它可能去调ghCLI 而不是走 GitHub MCP。解决办法是明确指定“用 GitHub MCP 帮我创建一个 PR”。养成这个习惯MCP 的命中率会高很多。数据库类 MCP 尤其要注意权限。给它配只读账号别用生产库的写权限账号。CLAUDE.md 里也写一句“禁止对生产库执行写操作”双保险。5. SubAgent把大任务拆给多个小助手并行SubAgent 是 Claude Code 的子代理机制。主 Claude 可以派出独立的子 Agent 执行特定任务每个子 Agent 有自己的上下文窗口不会污染主会话。5.1 定义示例在.claude/agents/目录下建 Markdown 文件定义子代理。比如一个专门做安全审查的--- name: security-auditor description: 审查代码安全问题专注注入、越权、敏感信息泄露 tools: Read, Grep, Glob --- 你是一名安全审计师。审查指定代码时重点检查 1. SQL 注入和命令注入风险 2. 权限校验是否缺失 3. 敏感信息是否硬编码 4. 输入是否做了边界校验 输出格式按严重程度排序的问题列表每条包含文件位置、问题描述、修复建议。再定义一个性能优化师--- name: perf-optimizer description: 找出性能瓶颈专注 N1 查询和内存泄漏 tools: Read, Grep, Glob --- 你是一名性能优化师。审查代码时重点找 1. 循环内的数据库查询N1 2. 未释放的资源句柄 3. 大对象的不必要拷贝 4. 缺失的索引建议 输出问题清单 预期收益评估。5.2 怎么触发定义好之后在对话里说“用 security-auditor 和 perf-optimizer 并行审查 src/api/ 目录”。Claude 会拆分任务两个子 Agent 各自跑结果汇总回主会话。处理大项目时这种分而治之比单会话硬扛高效得多。6. Skills把重复劳动固化成一键命令Skills 是你给 Claude 定义的快捷指令放在~/.claude/skills/目录下用/触发。6.1 一个技术债扫描 Skill建文件~/.claude/skills/techdebt.md# /techdebt - 技术债扫描 扫描当前项目找出以下问题 1. 重复代码相似度超过 80% 的代码块 2. 过长函数超过 50 行的函数 3. 硬编码配置写在代码里的 URL、密钥、魔法数字 4. 缺失测试没有对应测试文件的核心模块 输出格式按严重程度排序的表格包含文件位置、问题描述、建议修复方案。之后在 Claude 里输入/techdebt一键完成扫描。一次编写长期复用。6.2 验证 Skill 是否生效输入/后如果能看到 techdebt 出现在补全列表里说明注册成功。如果没出现检查文件是否放在~/.claude/skills/下、扩展名是否是.md、文件名是否和触发命令一致。7. 逐项验证确认四块能力都真的生效配置写完不算数要逐项验证。下面是我常用的验证清单能力验证动作预期结果CLAUDE.md问“这个项目怎么跑测试”直接答出你写的命令MCP说“用 GitHub MCP 列出最近的 PR”返回真实 PR 列表SubAgent说“用 security-auditor 审查 src/”输出结构化安全问题清单Skills输入/techdebt触发扫描并返回表格四项都通过说明工作流搭起来了。任何一项失败回到对应章节检查配置路径和权限。8. 本篇常见错排查CLAUDE.md 不生效最常见是文件名大小写或位置错。确认是项目根目录的CLAUDE.md不是claude.md。另外重启 Claude Code 才会重新读取。MCP 注册成功但调用失败多半是 token 权限不足或环境变量没传进去。用claude mcp list看状态再单独跑一次 MCP server 命令看报错。SubAgent 不触发检查.claude/agents/下的文件 frontmatter 格式name和description必须存在。触发时明确说出 agent 名字别指望它自己猜。Skill 命令冲突两个 skill 用了同一个触发名会冲突。保持命名唯一比如/techdebt和/review分开。请求超时或 401回到第 2 节确认ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY都设置正确。Key 失效就去控制台重新生成一个。9. 把工作流跑起来四块能力配齐之后你的日常会变成这样新会话启动Claude 自动读 CLAUDE.md 了解项目需要查数据时走 MCP大任务拆给 SubAgent 并行重复动作用 Skill 一键触发。你从“写代码的人”变成“定方向的人”。想验证模型对话效果可以去模型对话页面https://taotoken.net/model-chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite快速试长期做编码和 Agent 任务Coding Plan 页面https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite有更划算的方案接入细节和参数说明都在接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewrite。先把 CLAUDE.md 写起来这一步的收益最直接。