Claude Code 学习笔记：用 CLAUDE.md、Hooks、Skills 与 MCP 搭建可复现的本地开发工作流

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_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=claude_code_setup
• API Keys 页面：https://taotoken.net/api-keys?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=claude_code_setup

Base URL 用https://taotoken.net/api，注意这个地址不带任何查询参数。Model ID 根据你的任务复杂度选：简单改动用 Haiku，日常开发用 Sonnet，复杂重构用 Opus。具体可用模型列表可以在模型对话页面确认。

• 模型对话：https://taotoken.net/chat?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=claude_code_setup

Claude Code 读取环境变量的方式有两种：一种是 shell 环境变量，一种是项目级.claude/settings.json。推荐后者，因为可以提交到 Git，团队共享。但 Key 这种敏感信息不要提交，用 shell 环境变量注入。

在~/.zshrc或~/.bashrc里加一行：

export ANTHROPIC_API_KEY="sk-你的TaoToken密钥" export ANTHROPIC_BASE_URL="https://taotoken.net/api"

然后source ~/.zshrc生效。验证一下：

echo $ANTHROPIC_BASE_URL # 应该输出 https://taotoken.net/api

如果你用 CCSwitch 管理多套环境变量，可以在 CCSwitch 里新建一个配置，Base URL 填https://taotoken.net/api，Key 填你的密钥，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/api，Key 填你的密钥，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: FC<Props> = (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 的配置格式是command+args+env，不同 MCP Server 的参数不同。常见的 MCP Server 有文件系统、Git、数据库、API 文档等。你可以在 TaoToken 的接入文档里找到更多 MCP 配置示例。

• 接入文档：https://taotoken.net/doc?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=claude_code_setup

4. 验证请求：从会话启动到 Hooks 触发的完整链路

配置写完了，得验证每一步都生效。这一节给出逐步验证动作，你跟着做一遍，就能确认整条链路跑通。

4.1 验证 CLAUDE.md 加载

在项目根目录启动 Claude Code：

cd 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 的 Key，Base 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 都是https://taotoken.net/api，Key 都是 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 Plan：https://taotoken.net/coding-plan?utm_source=taotoken_aicg_blog_end&utm_medium=csdn&utm_campaign=rewrite&utm_content=claude_code_setup

最后说一个我踩过的坑：不要一次性把所有配置都写完。先写 CLAUDE.md，跑一周，看哪些地方 AI 还是不懂，再补。再加 Hooks，跑一周，看哪些检查最有用，再固化。最后加 Skills 和 MCP。配置是迭代出来的，不是设计出来的。一次写太多，反而不知道哪条配置在起作用。

从今天开始，打开你的项目，创建第一个CLAUDE.md，写下三行：技术栈、目录约定、常用命令。然后启动 Claude Code，问它“你知道这个项目怎么跑测试吗”。如果它能答对，你就已经迈出了第一步。剩下的，交给时间。