Claude Code 使用指南：从 CLAUDE.md 到 Skill 子代理的协作配置

1. 为什么单次对话撑不起团队协作Claude Code 刚上手时大多数人把它当成一个更聪明的终端补全问一句、改一段、跑一下结束。这个用法在单人小脚本里没问题但一旦进入真实项目就会暴露三个硬伤。第一每次新开会话Claude 对项目的技术栈、目录约定、命名规范一无所知你得反复用自然语言交代背景token 全花在重复描述上。第二改错了只能靠 git 手动回滚对话上下文却回不去重新解释需求又是一轮消耗。第三代码审查、写测试、查文档这些任务和主开发流程混在一条对话里上下文互相污染越到后面越笨。这篇要解决的就是把单次对话升级成可复用的协作工作流。核心抓手是四个热词CLAUDE.md 负责项目记忆Skill 负责能力扩展Rewind 负责安全回退子代理负责并行分工。我会给出可直接复制的 CLAUDE.md 骨架、Skill 目录结构、子代理配置片段以及每一项的验证动作。适合已经在用 Claude Code、但还没把它接进团队流程的开发者。下面所有配置都基于命令行版本配合 TaoToken 的接入点使用模型调用走统一入口省去多平台切换的麻烦。2. 前置准备把接入点配好再谈协作在写 CLAUDE.md 之前先把模型接入这一层理顺。Claude Code 本身是客户端真正干活的是背后的模型服务。我实测下来用 TaoToken 作为统一接入点比较省心它兼容 Anthropic 的接口协议Claude Code 不需要改任何代码只改环境变量就能指向它。你需要先拿到一个 API Key。打开 https://taotoken.net/api-keys 创建复制出来备用。注意这个 Key 只在创建时完整显示一次丢了就重新建。然后配置环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_API_KEY这两个变量指向 TaoToken 的 API 地址即可export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的key如果你用的是 zsh把这两行写进~/.zshrcbash 就写进~/.bashrc然后source一下。Windows 用户在 PowerShell 里用$env:ANTHROPIC_BASE_URLhttps://taotoken.net/api设置当前会话想持久化就写进系统环境变量。验证接入是否成功最直接的办法是启动 Claude Code 后随便问一句claude # 进入交互界面后输入 你现在连接的是哪个模型服务只回答服务名称如果它能正常回复说明接入层通了。这一步没通后面所有配置都是空中楼阁。关于接入的完整参数说明可以对照 https://taotoken.net/doc 里的接口文档核对尤其是 base_url 结尾不要多加斜杠这是新手最容易踩的坑。3. CLAUDE.md给项目装上长期记忆CLAUDE.md 是放在项目根目录的 Markdown 文件Claude Code 每次在项目里启动都会自动读取。它的作用相当于给模型一份项目说明书让它不用你每次开口就懂上下文。很多人以为越长越好其实相反——太长会挤占上下文窗口反而让模型抓不住重点。原则是宁缺毋滥、直击本质。3.1 用 /init 生成初稿最省事的起点是在项目根目录启动 Claude Code输入/init。它会扫描项目结构自动生成一份 CLAUDE.md 初稿包含技术栈、目录说明、常用命令。生成后别急着用先人工过一遍把废话删掉。3.2 可复制的 CLAUDE.md 骨架下面这份骨架我用了几个项目直接改字段就能用# 项目订单服务 ## 一句话简介 基于 Go Gin 的订单处理服务对外提供 REST API内部通过 gRPC 调用库存和支付。 ## 技术栈 - 语言Go 1.22 - Web 框架Gin - 数据库PostgreSQL 15ORM 用 GORM - 缓存Redis 7 - 测试标准库 testing testify ## 目录结构 - cmd/ 入口按服务拆分 - internal/ 业务逻辑禁止外部 import - pkg/ 可复用的公共库 - api/ protobuf 定义 - migrations/ 数据库迁移脚本 ## 代码规范 - 命名导出函数用驼峰包名全小写单词 - 错误处理统一用 errors.Wrap 包装禁止裸 panic - 注释导出符号必须有注释注释用中文 - 提交前必须跑 gofmt 和 go vet ## 常用命令 - 启动make run - 测试make test - 迁移make migrate-up ## 禁止事项 - 不要修改 migrations 下已提交的脚本 - 不要在 internal 里引入外部项目的包这份骨架的关键在于禁止事项和代码规范两节。模型最容易犯的错就是自作主张改迁移脚本、或者把内部包暴露出去提前写死规则能省掉大量返工。3.3 验证记忆是否生效写完 CLAUDE.md 后重启 Claude Code问一个只有读了这份文件才知道的问题claude # 输入 我们这个项目用什么 ORM只回答名称如果它答出 GORM说明记忆加载成功。如果答不上来检查文件是不是放在了启动目录的根下——Claude Code 只读当前工作目录及其父目录的 CLAUDE.md放错位置等于没写。4. Skill把重复能力封装成可调用模块CLAUDE.md 解决知道什么Skill 解决会做什么。Skill 是 Claude Code 的能力扩展机制本质是一个带SKILL.md的目录里面写清楚这个技能什么时候触发、怎么执行。官方在 github.com/anthropics/skills 维护了一批技能比如前端设计、PDF 处理、文档生成。4.1 Skill 目录结构一个 Skill 的标准结构长这样~/.claude/skills/ └── api-review/ ├── SKILL.md # 技能定义必须有 ├── templates/ # 可选模板文件 │ └── review.md └── scripts/ # 可选辅助脚本 └── check.shSKILL.md的头部是 YAML 元信息下面接正文说明--- name: api-review description: 审查 REST API 设计检查命名、状态码、分页、错误格式是否符合团队规范 --- ## 何时使用 当用户要求审查 API 接口设计、或新增接口需要评审时触发。 ## 执行步骤 1. 读取 api/ 目录下的 protobuf 或路由定义 2. 对照团队规范逐项检查 3. 输出问题清单按严重程度排序 ## 团队规范 - 路径用复数名词如 /orders 而非 /order - 分页统一用 page 和 page_size - 错误响应固定为 {code, message, detail}4.2 手动安装官方 Skill直接claude plugin install有时会因为仓库太大而超时手动装更稳# 浅克隆只取最新一层 git clone --depth1 https://github.com/anthropics/skills.git /tmp/skills # 建目录并复制 mkdir -p ~/.claude/skills/frontend-design cp /tmp/skills/skills/frontend-design/SKILL.md \ ~/.claude/skills/frontend-design/SKILL.md # 验证 head -5 ~/.claude/skills/frontend-design/SKILL.md4.3 验证 Skill 被识别重启 Claude Code输入/skills查看已加载的技能列表。如果能看到frontend-design和自定义的api-review说明注册成功。然后在对话里显式点名用 api-review 技能审查一下我刚写的 /orders 接口模型会按 SKILL.md 里的步骤执行。如果它没反应多半是 description 写得不够具体触发条件模糊模型判断不出该不该用。5. Rewind 与子代理回退和并行的两条腿协作工作流里出错和分工是常态Rewind 和子代理分别解决这两个问题。5.1 Rewind 回退Claude Code 里双击 Esc 或输入/rewind会弹出历史节点列表用上下键选择要回到的位置。它能把代码和对话上下文一起回退到某个节点之前。这一点比 git 强——git 只能回代码对话上下文回不去重新解释需求又是一轮消耗。有个限制要记住Rewind 只能回滚 Claude 直接创建或编辑的文件。如果它执行了npm install或go mod tidy生成的文件Rewind 撤不掉得手动处理。所以大改动之前先git commit存一个存档双保险。5.2 子代理配置子代理是独立运行的分身有自己的上下文窗口和主对话互不干扰。最典型的用法是代码审查主对话继续开发分身独立审查两边并行。创建步骤是在 Claude Code 里输入/agents然后按提示走选作用域团队项目选 Project、选创建方式、描述职责、配权限、选模型、选颜色、配记忆。配置完成后会生成一个 Markdown 文件放在.claude/agents/下。一个代码审查子代理的配置片段--- name: code-reviewer description: 独立审查代码变更检查安全漏洞、性能问题和规范符合度 model: claude-sonnet tools: [Read, Grep, Glob] --- 你是代码审查专家。收到审查任务后 1. 用 git diff 获取本次变更 2. 逐文件检查SQL 注入、越界、空指针、资源泄漏 3. 对照 CLAUDE.md 里的代码规范 4. 输出问题清单标注文件和行号按严重程度排序 5. 不要修改代码只报告注意tools里只给了读权限没给写权限。审查类子代理就该只读避免它自作主张改代码。需要它写测试时再单独建一个带 Write 权限的子代理。5.3 验证子代理工作在主对话里下达任务让 code-reviewer 审查一下 internal/order 目录下最近的改动主对话会把任务派给子代理子代理独立跑完返回结果。你可以在输出里看到它用了哪些工具、读了哪些文件。如果它没被触发检查.claude/agents/下的文件名和name字段是否一致。6. 本篇常见错排查配置过程中有几个高频报错我整理成对照表现象原因处理启动报 401API Key 无效或未导出重新export确认 Key 没多余空格连接超时base_url 写错或多了斜杠核对为https://taotoken.net/apiCLAUDE.md 不生效文件不在启动目录放到项目根重启会话Skill 不触发description 太模糊补上明确的触发场景关键词Rewind 找不到节点会话已关闭用claude --resume恢复后再回退子代理不响应权限或模型配置缺失检查 agents 文件头部字段完整还有一个隐蔽的坑上下文窗口用满后模型会变笨。输入/context查看使用率超过 70% 就该处理。同一功能持续开发用/compact压缩切换全新任务用/clear清空。这两个命令用对了能明显感觉模型聪明回来。7. 把工作流跑起来整套配置串起来是这样的项目根放 CLAUDE.md 提供记忆~/.claude/skills/放 Skill 扩展能力.claude/agents/放子代理做并行分工出错用 Rewind 回退上下文满了用 compact 或 clear 管理。接入层统一走 TaoToken模型调用不用改代码。如果你还在单次对话阶段建议先从 CLAUDE.md 开始这是投入产出比最高的一步。跑顺了再加 Skill最后上子代理。想直接体验模型对话效果可以从 https://taotoken.net/models 进去试长期做编码和 Agent 协作的建议看下 https://taotoken.net/coding-plan 的套餐比按次调用划算。接入文档在 https://taotoken.net/docAPI Key 在 https://taotoken.net/api-keys 创建。配置过程中卡住了对照第 6 节的排查表逐项过一遍基本都能定位。