1. 为什么你的 Claude Code 工作流总是“一次性”的很多人第一次用 Claude Code 的感觉是惊艳第二次用就开始怀疑人生。原因不复杂每次新会话都是全新的上下文窗口你上一轮辛苦调教出来的项目约定、目录结构、构建命令、代码风格它统统不记得。于是你反复粘贴同一段“请用 pnpm 不要用 npm”“测试文件放在源码旁边”“API 返回统一{ data, error }结构”粘贴到你自己都烦。Claude Code Docs 里其实给了一套完整的解法用CLAUDE.md承载“每次会话都必须知道”的持久上下文用Skills承载“按需加载”的可复用知识与工作流用MCP连接外部服务用Subagents做上下文隔离。问题在于文档是散点式的很多人读完知道有这些概念却拼不出一个能跑、能复现、能提交进 Git 的工作流。这篇就干一件事把文档要点落成可复制的配置。我会给出CLAUDE.md骨架、.claude/skills/目录结构、.mcp.json配置片段最后用一次 Subagent 调用把整条链路验证一遍。适合谁适合已经能跑起 Claude Code、但每次都在重复“喂上下文”的开发者。如果你还没配好 API 访问后面第 2 节会给出接入方式用 TaoToken 的兼容端点即可配置方式和官方一致。核心检索词先摆出来Claude Code 的CLAUDE.md是每个会话自动加载的项目指令Skills是按需加载的可调用工作流MCP是连接外部工具与数据的协议Subagents是拥有独立上下文窗口的隔离工作者。四者协作才能搭出可复现的编码工作流。2. 前置把 Claude Code 接到可用的 API 端点Claude Code 本身是个代理框架它需要模型来推理。默认它走 Anthropic 官方通道但很多团队希望统一走一个兼容端点方便计费和审计。TaoToken 提供 Anthropic 兼容的 API配置方式就是设置环境变量Claude Code 会读取ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN。先拿到 Key。打开控制台创建 API Keyhttps://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite然后在 shell 里配置macOS/Linux 写进~/.zshrc或~/.bashrcWindows 用系统环境变量export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你的key注意ANTHROPIC_BASE_URL后面不要加/v1Claude Code 会自己拼接路径。配好后验证一下claude -p reply with the single word: ok如果返回ok说明模型通道通了。这一步是整个工作流的地基地基不稳后面全是玄学问题。如果你更想先在网页里试模型对话可以走模型对话入口https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite接入文档在这里遇到 401/404 先对照它排查https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite3. CLAUDE.md 骨架把“每次都要说”的规则固化下来CLAUDE.md的加载规则很关键Claude 从当前工作目录向上遍历到根目录读取沿途所有CLAUDE.md全部累加进上下文。子目录里的嵌套文件在你进入该目录工作时才加载。所以项目根目录的CLAUDE.md应该只放“全项目通用”的东西控制在 200 行以内超了就拆到.claude/rules/。下面是我实测下来比较稳的骨架直接复制改# 项目约定 ## 命令 - 安装依赖: pnpm install - 构建: pnpm build - 测试: pnpm test - 单测: pnpm test -- file - 类型检查: pnpm typecheck ## 技术栈 - TypeScript strict 模式 - React 19只用函数组件 - 状态管理用 zustand不用 redux ## 代码规则 - 具名导出禁止 default export - 测试文件与源码同目录: foo.ts - foo.test.ts - 所有 API 路由返回 { data, error } 结构 - 禁止直接编辑 .env改 .env.example ## 架构 - src/api/ 路由层只做参数校验和转发 - src/services/ 业务逻辑 - src/db/ 数据访问禁止在 services 里写裸 SQL ## Compact Instructions 压缩对话时保留当前任务目标、已修改文件列表、未解决的报错。几个容易踩的点。第一CLAUDE.md里的规则是请求不是保证Claude 可能不遵守。真正要强制执行的规则比如“永远不要动.env”应该写成PreToolUsehook这个后面第 5 节讲。第二path/to/import可以导入其他文件相对路径是相对于包含导入语句的那个文件不是工作目录这点文档里写得很清楚但很容易搞错。第三如果你团队已经在用AGENTS.md可以建一个CLAUDE.md只写一行AGENTS.md来复用。.claude/rules/用来放路径门控的规则只有 Claude 处理匹配文件时才加载省上下文--- paths: - src/api/**/*.ts --- # API 开发规则 - 所有端点必须用 Zod 校验输入 - 返回结构: { data: T } | { error: string } - 公开端点必须限流4. Skills 目录结构把可复用工作流做成可调用命令Skills和CLAUDE.md的分工文档里一句话说透了如果 Claude 应该始终知道它放CLAUDE.md如果它是 Claude 有时需要的参考材料或者你用/name触发的工作流放 skill。Skills 默认在会话开始时只加载描述完整内容在你调用时才加载所以上下文成本很低。目录结构长这样.claude/ skills/ security-review/ SKILL.md checklist.md deploy/ SKILL.mdSKILL.md用 frontmatter 控制触发方式。下面这个security-review是“仅用户可调用”的Claude 不能自动触发必须你手动敲/security-review--- description: 审查代码变更的安全漏洞、认证缺口和注入风险 disable-model-invocation: true argument-hint: branch-or-path --- ## 待审查的 diff !git diff $ARGUMENTS 审查上面的变更重点看 1. 注入漏洞SQL、XSS、命令注入 2. 认证与授权缺口 3. 硬编码密钥或凭证 完整检查清单见本目录的 checklist.md。 按严重程度分级报告并给出修复步骤。这里有两个语法要记住。!反引号包裹的行会执行 shell 命令并把输出注入 prompt所以git diff $ARGUMENTS会把 diff 直接喂给 Claude。$ARGUMENTS替换成你在 skill 名后面输入的内容比如/security-review main..HEAD。checklist.md是 skill 的附属文件Claude 在运行 skill 时会按需读取不用全塞进SKILL.md。disable-model-invocation: true这个设置很实用它让 skill 描述完全不进上下文直到你手动调用。适合/deploy这种你不想让 Claude 自作主张触发的操作。反过来如果你想让 Claude 能自动发现但不想出现在/菜单里用user-invocable: false。5. MCP 配置连接外部服务并给规则上“硬锁”MCP让 Claude 能访问外部工具和数据。项目级配置放在根目录.mcp.json团队共享、提交进 Git{ mcpServers: { github: { command: npx, args: [-y, modelcontextprotocol/server-github], env: { GITHUB_TOKEN: ${GITHUB_TOKEN} } } } }${GITHUB_TOKEN}从环境变量读取不要把 token 写死在文件里。MCP 服务器的覆盖优先级是本地 项目 用户同名服务器按这个顺序生效。工具定义默认是延迟加载的会话开始时只有工具名进上下文完整 JSON schema 在你实际用到时才拉取所以空闲的 MCP 工具几乎不占上下文。现在说“硬锁”。CLAUDE.md里写“禁止编辑.env”只是请求Claude 可能忘。用settings.json里的 hook 才能真正拦住{ permissions: { allow: [Bash(pnpm test *), Bash(pnpm run *)], deny: [Bash(rm -rf *)] }, hooks: { PostToolUse: [ { matcher: Edit|Write, hooks: [ { type: command, command: jq -r .tool_input.file_path | xargs npx prettier --write } ] } ] } }permissions.allow里的Bash(pnpm test *)支持通配符匹配pnpm test开头的命令这样 Claude 跑测试就不用每次问你。deny优先级更高。PostToolUsehook 在每次文件编辑后自动跑 prettierhook 在主对话外执行零上下文成本除非它返回输出。这就是文档说的“把护栏放在 hooks 里”——需要每次都成立、不需要 Claude 思考的操作用 hook需要推理的多步骤任务用 skill。6. Subagent 调用验证一次跑通整条链路Subagents有自己的独立上下文窗口完成后只把摘要返回主对话。适合“读很多文件但只关心结论”的任务。定义放在.claude/agents/--- name: code-reviewer description: 审查代码的正确性、安全性和可维护性 tools: Read, Grep, Glob skills: security-review --- 你是资深代码审查者。审查时关注 1. 正确性逻辑错误、边界情况、null 处理 2. 安全性注入、认证绕过、数据暴露 3. 可维护性命名、复杂度、重复代码 每条发现都必须给出具体修复方案。注意skills: security-review这一行subagent 的 skills 字段里列出的 skill 会在启动时完整预加载进它的上下文这和主对话里“按需加载”的行为不同。tools字段限制了它只能用只读工具防止审查者乱改代码。现在验证。在项目里敲claude进入交互模式后让它调用这个 subagent用 code-reviewer subagent 审查 src/api/ 目录下最近的改动只返回关键发现。预期行为主对话生成一个 subagentsubagent 在自己的上下文里读文件、跑security-reviewskill、返回一份摘要。你的主对话只收到摘要那些被读进来的几十个文件内容不会污染主上下文。这就是文档说的“上下文隔离”。验证成功的标志有三个一是主对话里能看到 subagent 的调用记录二是返回的是摘要而非原始文件内容三是主对话的/context占用没有明显上涨。跑/context可以看实时分解跑/memory可以确认哪些CLAUDE.md和自动记忆文件在启动时被加载了。7. 本篇常见错排查报错一401 Unauthorized或invalid api key。九成是ANTHROPIC_AUTH_TOKEN没生效。先echo $ANTHROPIC_AUTH_TOKEN确认非空再确认ANTHROPIC_BASE_URL是https://taotoken.net/api且没有多余的/v1。改完环境变量要新开终端或source一下。报错二skill 敲了/security-review没反应。检查SKILL.md的 frontmatter 是否合法description是必填的。再确认目录层级是.claude/skills/security-review/SKILL.md不是.claude/skills/security-review.md。skill 和 command 同名时 skill 优先。报错三MCP 服务器连不上。先手动跑一遍command和args里的命令比如npx -y modelcontextprotocol/server-github看是不是网络或包安装问题。再确认${GITHUB_TOKEN}对应的环境变量真的存在。MCP 服务器按名称覆盖本地配置会盖掉项目配置排查时留意~/.claude.json里有没有同名项。报错四CLAUDE.md规则不生效。先跑/memory确认文件被加载了。如果规则是“永远不要做 X”这种必须成立的别指望CLAUDE.md改用PreToolUsehook。另外注意CLAUDE.md是累加的多级文件冲突时 Claude 自己判断更具体的通常优先但这不是保证。报错五上下文很快被填满。跑/context看谁在占空间。常见元凶是把大段参考文档塞进了CLAUDE.md应该移到 skill 里按需加载。长任务开始前用/compact focus on the auth bug fix指定压缩重点切换不相关任务时用/clear。大范围读取交给 subagent。8. 把配置沉淀成可复现资产到这里一条可复现的工作流就成型了CLAUDE.md管每次会话的持久上下文.claude/rules/管路径门控的局部规则.claude/skills/管按需加载的可调用工作流.mcp.json管外部连接.claude/agents/管隔离的 subagentsettings.json里的 hooks 管必须每次都成立的硬规则。这套东西全部提交进 Git新同事 clone 下来就能得到和你一样的行为。如果你要把这套工作流用在长期编码或 Agent 场景Coding Plan 比按量计费更划算入口在这里https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite最后给一个我踩过的坑CLAUDE.md别贪多。我一开始把 API 风格指南整篇贴进去结果每次会话光加载它就吃掉一大块上下文Claude 反而对真正重要的构建命令视而不见。后来把参考材料全挪进 skillCLAUDE.md压到 80 行以内行为立刻稳定了。记住那条经验法则——始终要知道的放CLAUDE.md有时才需要的放 skill必须每次都成立的放 hook。