1. 为什么你的 Claude Code 总是“失忆”从零搭建可复现工作流的真实痛点很多人第一次打开 Claude Code敲下claude回车问一句“帮我看看这个项目”然后发现它像个刚入职的实习生不知道项目用什么框架、不知道测试怎么跑、不知道提交规范甚至把node_modules里的压缩代码读了一遍。这不是模型不行而是你没给它“说明书”。Claude Code 本质上是一个跑在终端里的编码 Agent它的能力上限不取决于模型本身而取决于你喂给它的上下文质量。官方文档里有一句话我印象很深模型能力是地板配置质量才是天花板。换句话说同一个 Sonnet 模型在裸奔状态下和配置完善状态下产出质量能差出一个数量级。我试过在一个中型前端项目里做对比不写任何配置直接让 Claude Code 改一个组件它会随手引入新的状态管理库、改掉 ESLint 规则、提交信息写成“fix bug”。而当我补齐了CLAUDE.md、.claude/settings.json、Hooks 和 MCP 之后它开始遵守项目的目录约定、自动跑 lint、提交信息符合 Conventional Commits。差别不在模型在配置。这篇文章要解决的核心问题是如何用 CLAUDE.md、Hooks、Skills 与 MCP 四件套在本地搭出一条稳定、可复现、团队可共享的 AI 辅助开发工作流。适合三类人刚接触 Claude Code 想系统上手的新手、已经在用但配置零散的开发者、想把 AI 协作流程固化进团队工程规范的 Tech Lead。整条工作流可以拆成四层从下往上依次是CLAUDE.md项目说明书每次会话自动加载解决“AI 不知道项目长什么样”的问题。Hooks事件触发器在提交前、工具调用后等时机自动执行命令解决“AI 不遵守规范”的问题。Skills可复用的任务知识包按需加载解决“重复教 AI 同一件事”的问题。MCP连接外部工具和数据源解决“AI 够不到数据库、API、文档”的问题。下面我会按“先跑通再优化”的顺序给出每一层可直接复制的配置片段和验证动作。所有配置都基于 Claude Code 官方支持的格式路径和字段名保持一致你复制粘贴就能用。2. 前置准备TaoToken 接入 Claude Code 的 Base URL 与 Key 配置在开始写配置之前得先让 Claude Code 能正常发请求。Claude Code 默认走 Anthropic 官方端点但国内开发者更常用的是兼容 Anthropic 协议的接入方式。TaoToken 提供了兼容 Anthropic Messages API 的端点配置方式和官方一致只是把 Base URL 换掉。你需要准备三样东西Base URL、API Key、Model ID。这三件套在 Claude Code、Cline、Codex 等工具里都是通用的只是字段名不同。先拿到 API Key。打开 TaoToken 控制台进入 API Keys 页面创建一个新 Key复制保存。注意 Key 只在创建时显示一次丢了就得重建。控制台入口https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_setupAPI Keys 页面https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_setupBase URL 用https://taotoken.net/api注意这个地址不带任何查询参数。Model ID 根据你的任务复杂度选简单改动用 Haiku日常开发用 Sonnet复杂重构用 Opus。具体可用模型列表可以在模型对话页面确认。模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_setupClaude Code 读取环境变量的方式有两种一种是 shell 环境变量一种是项目级.claude/settings.json。推荐后者因为可以提交到 Git团队共享。但 Key 这种敏感信息不要提交用 shell 环境变量注入。在~/.zshrc或~/.bashrc里加一行export ANTHROPIC_API_KEYsk-你的TaoToken密钥 export ANTHROPIC_BASE_URLhttps://taotoken.net/api然后source ~/.zshrc生效。验证一下echo $ANTHROPIC_BASE_URL # 应该输出 https://taotoken.net/api如果你用 CCSwitch 管理多套环境变量可以在 CCSwitch 里新建一个配置Base URL 填https://taotoken.net/apiKey 填你的密钥Model 填claude-sonnet-4-5之类的 ID。CCSwitch 的好处是切换环境不用改 shell 配置适合同时维护多个项目的场景。这里有个坑要提醒Claude Code 对 Base URL 的格式比较敏感末尾不要带斜杠也不要带/v1后缀。https://taotoken.net/api就是完整地址Claude Code 会自己拼接/v1/messages。如果你填成https://taotoken.net/api/v1请求会变成/v1/v1/messages直接 404。配置完成后在终端跑一次claude输入一句“你好”能正常回复就说明接入成功。如果报 401先检查 Key 是否复制完整如果报连接超时检查 Base URL 是否写错。这一步跑通之后再往下做工程化配置。3. 可复制配置CLAUDE.md、settings.json、Hooks 与 Skills 四件套这一节是整篇文章的核心给出四个可直接复制的配置文件。建议按顺序来先写 CLAUDE.md再配 settings.json然后加 Hooks最后沉淀 Skills。3.1 CLAUDE.md三层记忆体系的项目说明书CLAUDE.md 分三层优先级从高到低是文件夹级 项目级 全局级。三层叠加生效不冲突。全局级放在~/.claude/CLAUDE.md写你个人的习惯所有项目都会读# 个人偏好 - 永远用中文回答代码注释可以用英文 - 提交信息遵循 Conventional Commits 规范 - 修改代码前先说明改动计划等我确认后再动手 - 不要主动引入新的第三方依赖除非我明确要求项目级放在项目根目录CLAUDE.md写项目技术栈和规范可以提交 Git# 项目说明 ## 技术栈 - 前端React 18 TypeScript Vite - 状态管理Zustand - 样式Tailwind CSS - 测试Vitest Testing Library ## 目录约定 - src/components/ 放通用组件 - src/features/ 放业务模块每个模块自带 hooks 和 utils - src/lib/ 放纯函数工具 ## 开发规范 - 组件文件用 PascalCase工具函数用 camelCase - 所有导出必须有类型标注 - 提交前必须跑 pnpm lint 和 pnpm test ## 常用命令 - 启动开发pnpm dev - 跑测试pnpm test - 构建pnpm build文件夹级放在子目录比如src/features/payment/CLAUDE.md写这个模块专属的坑# 支付模块约定 - 所有金额字段用分为单位禁止用浮点数 - 调用支付网关必须走 src/lib/payment-gateway.ts 封装不要直接 fetch - 测试环境用 mock 网关不要连真实沙箱三层叠加后Claude Code 在改支付模块时会同时读到全局偏好、项目规范和支付模块约定。这就是“在合适的时候注入合适的上下文”。3.2 .claude/settings.json项目级行为控制在项目根目录创建.claude/settings.json控制 Claude Code 在这个项目里的行为。这个文件可以提交 Git团队共享。{ permissions: { allow: [ Bash(pnpm lint), Bash(pnpm test), Bash(pnpm build), Bash(git status), Bash(git diff) ], deny: [ Bash(rm -rf *), Bash(git push --force), Read(./.env), Read(./.env.local) ] }, env: { NODE_ENV: development } }allow列表里的命令 Claude Code 可以直接执行不用每次问你。deny列表里的命令会被拒绝防止误操作。注意.env文件被禁止读取避免密钥泄露。如果你用 CCSwitch 管理环境变量可以在 CCSwitch 里配置项目级的 Base URL 和 Key这样.claude/settings.json里就不用写敏感信息。CCSwitch 的配置界面里Base URL 填https://taotoken.net/apiKey 填你的密钥Model 填claude-sonnet-4-5。3.3 Hooks提交前自动跑检查Hooks 是事件触发器在特定时机自动执行命令。最实用的场景是提交前跑 lint 和测试。在.claude/settings.json里加hooks字段{ hooks: { PreToolUse: [ { matcher: Bash(git commit*), hooks: [ { type: command, command: pnpm lint pnpm test } ] } ] } }这段配置的意思是当 Claude Code 准备执行git commit命令时先跑pnpm lint pnpm test。如果检查失败提交会被阻止Claude Code 会看到错误信息并尝试修复。实测下来这个 Hook 能拦住 80% 的低级错误忘记跑 lint、测试没通过就提交、类型报错没修。Claude Code 看到 lint 错误后会自己改代码再重试提交形成一个闭环。Hooks 支持的事件类型有PreToolUse、PostToolUse、UserPromptSubmit等。PreToolUse在工具调用前触发PostToolUse在工具调用后触发。你可以用matcher字段匹配特定的工具调用比如Bash(git commit*)匹配所有 git commit 命令。3.4 Skills把重复任务沉淀成知识包Skills 是可复用的任务知识包放在.claude/skills/目录下每个 Skill 是一个 Markdown 文件。当 Claude Code 遇到相关任务时会按需加载对应的 Skill。比如你经常需要“新增一个 React 组件”可以写一个 Skill# 新增 React 组件 ## 触发条件 当用户要求新增组件时使用此 Skill。 ## 步骤 1. 在 src/components/ 下创建 PascalCase 命名的文件夹 2. 创建 index.tsx导出组件 3. 创建 index.test.tsx写基础渲染测试 4. 创建 index.stories.tsx写 Storybook 故事 5. 在 src/components/index.ts 里导出新组件 ## 模板 tsx import { FC } from react; interface Props { // 在这里定义 props } export const ComponentName: FCProps (props) { return div{/* 内容 */}/div; };注意事项组件必须有类型标注测试文件必须覆盖基础渲染Storybook 故事必须包含默认状态把这个文件放在 .claude/skills/new-component.md下次你让 Claude Code 新增组件时它会自动读取这个 Skill按步骤执行。不用每次重复解释“组件放哪、测试怎么写、Storybook 怎么配”。 Skills 和 CLAUDE.md 的区别是CLAUDE.md 是每次会话都加载的全量上下文Skills 是按需加载的任务知识。CLAUDE.md 写“项目是什么”Skills 写“某件事怎么做”。 ### 3.5 MCP接入外部工具链 MCP 是 Model Context Protocol让 Claude Code 连接外部工具和数据源。最常见的场景是接入数据库、API 文档、Git 仓库。 在 .claude/settings.json 里加 mcpServers 字段 json { mcpServers: { postgres: { command: npx, args: [-y, modelcontextprotocol/server-postgres], env: { DATABASE_URL: postgresql://localhost:5432/mydb } } } }这段配置让 Claude Code 能查询本地 PostgreSQL 数据库的 schema。当你问“用户表有哪些字段”时它会通过 MCP 查询数据库而不是瞎猜。注意MCP 直连生产库是禁止的只连本地开发库或只读副本。生产库的凭证不要写进配置文件。MCP 的配置格式是commandargsenv不同 MCP Server 的参数不同。常见的 MCP Server 有文件系统、Git、数据库、API 文档等。你可以在 TaoToken 的接入文档里找到更多 MCP 配置示例。接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_setup4. 验证请求从会话启动到 Hooks 触发的完整链路配置写完了得验证每一步都生效。这一节给出逐步验证动作你跟着做一遍就能确认整条链路跑通。4.1 验证 CLAUDE.md 加载在项目根目录启动 Claude Codecd your-project claude输入“你知道这个项目用什么技术栈吗”如果 Claude Code 回答 React TypeScript Vite说明项目级 CLAUDE.md 加载成功。再输入“我的个人偏好是什么”如果回答“永远用中文回答”说明全局级 CLAUDE.md 也加载了。如果没加载检查文件路径是否正确全局级是~/.claude/CLAUDE.md项目级是项目根目录CLAUDE.md。注意文件名大小写敏感必须是全大写。4.2 验证 settings.json 权限输入“帮我跑一下 pnpm lint”如果 Claude Code 直接执行不问你说明allow列表生效。输入“帮我读一下 .env 文件”如果被拒绝说明deny列表生效。如果权限没生效检查.claude/settings.json的 JSON 格式是否正确。可以用cat .claude/settings.json | jq .验证如果报错说明 JSON 有语法问题。4.3 验证 Hooks 触发让 Claude Code 改一行代码然后说“帮我提交”。观察终端输出应该先看到pnpm lint pnpm test的执行日志然后才是 git commit。如果 lint 或测试失败提交会被阻止Claude Code 会尝试修复。如果 Hook 没触发检查matcher字段是否匹配。Bash(git commit*)匹配所有以git commit开头的命令注意通配符位置。如果你用的是git commit -m xxx也能匹配。4.4 验证 Skills 加载输入“帮我新增一个 Button 组件”观察 Claude Code 是否按 Skill 里的步骤执行创建文件夹、写 index.tsx、写测试、写 Storybook、更新导出。如果它跳过了某一步说明 Skill 没加载。检查.claude/skills/new-component.md是否存在文件名是否和触发条件匹配。Skills 是按需加载的只有任务相关时才会读取。4.5 验证 MCP 连接输入“用户表有哪些字段”如果 Claude Code 通过 MCP 查询数据库并返回真实 schema说明 MCP 连接成功。如果它说“我无法访问数据库”说明 MCP 没配好。检查mcpServers配置里的command和args是否正确。可以手动跑一遍npx -y modelcontextprotocol/server-postgres看是否能启动。如果报错检查DATABASE_URL是否可连接。4.6 验证模型切换在会话里输入“切换到 Haiku 模型”然后问一个简单问题观察响应速度。再切换到 Opus问一个复杂问题观察思考深度。模型切换可以通过/model命令也可以在 settings.json 里配默认模型。如果你用 TaoToken 接入模型 ID 用claude-haiku-4-5、claude-sonnet-4-5、claude-opus-4-5这种格式。具体可用 ID 在模型对话页面确认。5. 常见报错排查401、local proxy failed、reading choices 与 OAuth配置过程中最容易踩的坑都集中在接入层。这一节列出四类高频报错和排查方法。5.1 401 Unauthorized报错信息API Error: 401 Unauthorized原因API Key 无效或未正确注入。排查步骤第一检查环境变量是否生效。跑echo $ANTHROPIC_API_KEY如果输出为空说明 shell 配置没 source。跑source ~/.zshrc再试。第二检查 Key 是否复制完整。TaoToken 的 Key 通常以sk-开头长度固定。如果复制时漏了字符会 401。第三检查 Base URL 是否配对。如果你用的是 TaoToken 的 KeyBase URL 必须是https://taotoken.net/api。用官方 Key 配 TaoToken 的 URL 也会 401。第四检查 settings.json 里是否覆盖了环境变量。如果.claude/settings.json的env字段里写了ANTHROPIC_API_KEY会覆盖 shell 环境变量。删掉这行或者改成正确的 Key。5.2 local proxy failed报错信息Error: local proxy failed to start原因Claude Code 的本地代理启动失败通常是端口被占用或网络配置问题。排查步骤第一检查是否有其他 Claude Code 实例在跑。跑ps aux | grep claude如果有残留进程kill 掉再试。第二检查端口占用。Claude Code 默认用随机端口如果防火墙拦截了本地回环会启动失败。检查系统防火墙设置确保127.0.0.1的本地连接不被拦截。第三检查 Base URL 是否可达。跑curl -I https://taotoken.net/api如果返回 200 或 401说明网络通。如果超时检查 DNS 和网络配置。第四如果你用了 CCSwitch检查 CCSwitch 的代理配置是否和 Claude Code 冲突。CCSwitch 只管理环境变量不应该启动代理。如果 CCSwitch 里配了代理端口删掉。5.3 reading choices 报错报错信息Error: reading choices: unexpected end of JSON input原因API 返回的响应格式不符合预期通常是 Base URL 或 Model ID 写错。排查步骤第一检查 Base URL 是否带了多余后缀。https://taotoken.net/api是正确格式不要加/v1或末尾斜杠。第二检查 Model ID 是否有效。如果你填了claude-3-5-sonnet这种旧 ID可能不被支持。用claude-sonnet-4-5这种新格式。第三检查请求是否被中间层拦截。如果你在公司网络里可能有网关改写了响应。换一个网络环境试试。第四检查 Claude Code 版本。跑claude --version如果版本太旧可能不支持新的响应格式。升级到最新版。5.4 OAuth 相关报错报错信息Error: OAuth token expired原因Claude Code 尝试用 OAuth 登录但 token 过期或未配置。排查步骤第一如果你用 API Key 接入不需要 OAuth。检查是否误触发了登录流程。跑claude logout退出登录状态然后用 API Key 重新接入。第二检查环境变量里是否有ANTHROPIC_AUTH_TOKEN。这个变量会触发 OAuth 流程如果你用 API Key删掉这个变量。第三如果你确实需要用 OAuth检查系统时间是否准确。OAuth token 对时间敏感系统时间偏差超过 5 分钟会报过期。第四检查~/.claude/目录下的凭证文件。如果文件损坏删掉重新登录。注意备份其他配置文件。5.5 Codex auth.json 配置对照如果你同时用 Codex它的配置文件和 Claude Code 不同。Codex 用~/.codex/auth.json格式如下{ openai_api_key: sk-你的TaoToken密钥, base_url: https://taotoken.net/api }注意 Codex 的字段名是openai_api_key和base_url和 Claude Code 的ANTHROPIC_API_KEY和ANTHROPIC_BASE_URL不同。三件套对照工具Base URL 字段Key 字段Model 字段Claude CodeANTHROPIC_BASE_URLANTHROPIC_API_KEYANTHROPIC_MODELCodexbase_urlopenai_api_keymodelClineapiBaseapiKeymodelId不管哪个工具Base URL 都是https://taotoken.net/apiKey 都是 TaoToken 控制台创建的密钥Model ID 都是claude-sonnet-4-5这种格式。三件套对齐了接入就不会出问题。6. 把工作流跑成习惯从单次配置到团队共享配置写完、验证通过之后最后一步是把它变成习惯。单次配置只能解决一次问题只有沉淀成团队规范才能持续产生收益。第一件事是把.claude/settings.json、CLAUDE.md、.claude/skills/提交到 Git。新同事 clone 项目后不用重新配置直接claude就能用。注意.claude/settings.local.json不要提交这个文件放个人覆盖配置。第二件事是定期迭代 CLAUDE.md。每次 Claude Code 犯了一个错就把这个错写进 CLAUDE.md 的“注意事项”。比如它总是忘记跑测试就加一条“提交前必须跑 pnpm test”。CLAUDE.md 是活的文档越用越准。第三件事是把常用任务沉淀成 Skills。每次你重复解释同一个流程超过两次就写一个 Skill。比如“新增 API 路由”“新增数据库迁移”“新增国际化文案”这些都可以写成 Skill。第四件事是用 Hooks 固化检查。除了提交前跑 lint 和测试还可以加更多 Hook比如PostToolUse在文件修改后自动跑格式化UserPromptSubmit在用户输入后自动补充上下文。如果你想把这条工作流用在长期编码项目里可以考虑 TaoToken 的 Coding Plan它针对 Agent 场景做了优化适合长时间运行的编码任务。Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentclaude_code_setup最后说一个我踩过的坑不要一次性把所有配置都写完。先写 CLAUDE.md跑一周看哪些地方 AI 还是不懂再补。再加 Hooks跑一周看哪些检查最有用再固化。最后加 Skills 和 MCP。配置是迭代出来的不是设计出来的。一次写太多反而不知道哪条配置在起作用。从今天开始打开你的项目创建第一个CLAUDE.md写下三行技术栈、目录约定、常用命令。然后启动 Claude Code问它“你知道这个项目怎么跑测试吗”。如果它能答对你就已经迈出了第一步。剩下的交给时间。