1. 为什么你的 Claude Code 用起来像“金鱼记忆”很多人第一次用 Claude Code 命令行 AI 编程工具时都会经历同一个落差单次对话里它像个靠谱的结对程序员可一旦关掉终端再回来它就把项目结构、命名习惯、构建命令忘得一干二净。你不得不每次重复“这个项目用 pnpm 不用 npm”“测试文件放在 tests/ 下”“别动 legacy 目录”重复到怀疑人生。问题不在模型而在你没有给它一份稳定的项目记忆。Claude Code 的上下文感知能力是“读得到”而不是“记得住”——它每次启动都会重新扫描工作目录但扫描不到你脑子里的团队约定。CLAUDE.md 就是解决这件事的文件它放在项目根目录Claude Code 启动时自动加载相当于给 AI 一份随项目走的入职手册。再往上一层当你想让它查数据库、调内部 API、读 Jira 工单时光靠读文件就不够了。这时需要 MCPModel Context Protocol把外部工具接进来。CLAUDE.md 管“懂规矩”MCP 管“够得着”两者配齐Claude Code 才从“会用”走到“用好”。这篇就按这个顺序给你可复制的骨架和逐条验证命令。2. 前置准备TaoToken 接入与 Claude Code 环境2.1 拿到可用的 API KeyClaude Code 本身是客户端真正干活的是背后的模型服务。你需要一个兼容 Anthropic 接口的接入点。打开 TaoToken 官网 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content 注册后进入控制台 https://taotoken.net/console?utm_sourcetaotoken_aicg_blog_endutm_contentconsoleutm_campaignrewrite 创建密钥在 API Keys 页面 https://taotoken.net/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi-keysutm_campaignrewrite 复制你的 Key。这个 Key 只显示一次先存到密码管理器里。2.2 配置环境变量Claude Code 读取两个关键变量接口地址和密钥。接口基址用 https://taotoken.net/api 注意这里不加任何查询参数。写进 shell 配置文件别直接写在命令行里否则会进 history。# 写入 ~/.zshrc 或 ~/.bashrc export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_API_KEYsk-你的密钥 # 让配置立即生效 source ~/.zshrc # 验证变量已加载只回显前缀避免泄露完整 Key echo ${ANTHROPIC_API_KEY:0:8}2.3 安装并确认版本npm install -g anthropic-ai/claude-code claude --version如果版本号正常输出说明客户端就绪。接着在任意项目目录里跑一次claude能进入交互界面就代表链路通了。这一步不通后面所有配置都白搭所以先确认再往下走。3. CLAUDE.md 骨架让项目记忆可复制3.1 文件放哪、怎么分层CLAUDE.md 支持三层项目根目录团队共享提交进 Git、用户主目录~/.claude/CLAUDE.md个人偏好不进版本库、子目录局部覆盖。团队协作场景下根目录那份是重点它决定了所有人拉下代码后 AI 的行为是否一致。3.2 可直接复制的骨架下面这份骨架我按“AI 读完就能干活”的标准写你替换方括号内容即可# 项目订单服务 order-service ## 技术栈 - 语言Go 1.22 - 框架Gin GORM - 数据库PostgreSQL 15 - 缓存Redis 7 - 构建Makefile 封装禁止直接 go build ## 目录约定 - cmd/ 入口一个服务一个子目录 - internal/ 业务逻辑禁止跨模块直接 import - pkg/ 可复用工具 - migrations/ SQL 迁移只增不改 ## 编码规范 - 错误必须用 fmt.Errorf(xxx: %w, err) 包装 - 所有对外接口必须有 context.Context 参数 - 新增函数必须配单元测试测试文件同目录 _test.go ## 常用命令 - make test 跑全部单测 - make lint 静态检查 - make migrate 执行数据库迁移 - make run 本地启动 ## 禁区 - 不要修改 migrations/ 下已存在的文件 - 不要引入新的第三方 ORM - 不要动 vendor/ 目录3.3 写好 CLAUDE.md 的三个原则第一写“约束”而不是“介绍”。AI 不需要知道项目多牛它需要知道什么不能碰。第二命令要能直接执行别写“运行测试”这种模糊描述写make test。第三控制在 100 行以内太长会挤占上下文预算反而降低响应质量。我试过把 300 行的文档塞进去结果它开始忽略后半部分精简到 80 行后行为明显稳定。4. MCP 配置把外部工具链接进来4.1 MCP 是什么、解决什么问题MCP 是一套让 Claude Code 调用外部服务的协议。你可以把它理解成给 AI 装“插件”数据库插件让它能查表结构GitHub 插件让它能读 Issue文件系统插件让它能访问项目外的目录。每个 MCP 服务是一个独立进程Claude Code 通过标准输入输出和它通信。4.2 注册一个 MCP 服务用claude mcp add命令注册格式是“名称 启动命令”。下面以 SQLite 为例这是最容易本地验证的# 注册一个 SQLite MCP 服务 claude mcp add sqlite -- npx -y modelcontextprotocol/server-sqlite --db-path ./data/app.db # 查看已注册的服务列表 claude mcp list # 查看某个服务的详细配置 claude mcp get sqlite注意--后面的部分是服务进程的启动参数--db-path指向你的实际数据库文件。注册信息默认写在项目级配置里团队可以共享。4.3 用配置文件批量管理命令注册适合临时试团队协作更推荐写配置文件。在项目根目录建.mcp.json{ mcpServers: { sqlite: { command: npx, args: [-y, modelcontextprotocol/server-sqlite, --db-path, ./data/app.db] }, filesystem: { command: npx, args: [-y, modelcontextprotocol/server-filesystem, ./docs] } } }这份文件提交进 Git 后队友拉下来直接生效不用各自敲命令。filesystem那个服务把./docs目录暴露给 AI适合让它读设计文档。4.4 权限与安全边界MCP 服务能访问真实资源所以要在 CLAUDE.md 里写清楚边界。比如数据库服务只给只读账号文件系统服务只暴露文档目录而不是整个家目录。别把生产库连接串直接塞进配置用环境变量引用{ mcpServers: { postgres: { command: npx, args: [-y, modelcontextprotocol/server-postgres], env: { DATABASE_URL: ${READONLY_DB_URL} } } } }5. 验证逐条确认配置真的生效5.1 验证 CLAUDE.md 被加载进入项目目录启动 Claude Code直接问它项目约定cd order-service claude在交互界面输入这个项目用什么命令跑测试有哪些目录不能改如果它准确答出make test和 migrations 禁区说明 CLAUDE.md 加载成功。答不出来就检查文件名大小写——必须是全大写CLAUDE.md放在项目根目录。5.2 验证 MCP 服务连通在 Claude Code 里输入斜杠命令查看 MCP 状态/mcp正常情况会列出已注册服务及其连接状态。如果显示 failed先退出 Claude Code在终端单独跑一次服务启动命令看报错信息。常见的是npx找不到包或数据库路径写错。5.3 验证工具真的能被调用连上 SQLite 后直接让它查数据用 sqlite 服务列出所有表名它应该返回数据库里的表清单。这一步成功代表从“配置”到“实际调用”的链路完整打通。如果它说“我没有这个工具”回到/mcp确认服务状态再检查.mcp.json的 JSON 格式有没有多余逗号。6. 常见报错排查6.1 启动就报 401 或鉴权失败九成是环境变量没生效。新开一个终端窗口重新source配置文件或者直接echo $ANTHROPIC_API_KEY确认非空。另一个坑是 Key 前后带了空格或换行复制时容易带上用echo检查一下。6.2 CLAUDE.md 不生效先确认文件名和位置。然后检查是不是被.gitignore忽略了——有些模板会把CLAUDE.md加进忽略列表导致队友拉不到。最后看内容有没有语法问题Markdown 标题层级乱不影响加载但文件编码必须是 UTF-8。6.3 MCP 服务启动超时npx首次拉包会慢超时阈值可能不够。解决办法是先在终端手动跑一次npx -y modelcontextprotocol/server-sqlite --db-path ./data/app.db把包缓存到本地之后再注册就快了。如果服务本身需要网络确认当前网络能访问对应源。6.4 工具调用返回权限错误数据库服务用了只读账号却执行写操作或者文件系统服务访问了未暴露的目录。回到配置检查账号权限和暴露路径别为了图省事给全权限。生产库尤其要守住只读这条线。6.5 上下文被撑爆、响应变慢CLAUDE.md 太长或 MCP 返回数据太多都会挤占上下文。用/compact压缩历史对话把 CLAUDE.md 精简到 100 行内MCP 查询加LIMIT限制返回行数。长期高频编码的话可以考虑 Coding Plan https://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_contentcoding-planutm_campaignrewrite 这类面向持续编码场景的方案额度管理更省心。7. 把配置变成团队资产CLAUDE.md 和.mcp.json最大的价值不是让单个人爽而是让整个团队拉下代码后 AI 行为一致。建议把这两份文件纳入代码评审新增目录约定时同步更新 CLAUDE.md接入新工具时更新.mcp.json让它们和代码一起演进。验证模型能力或调试提示词时可以到模型对话 https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_contentchatutm_campaignrewrite 里快速试接入细节和参数说明查接入文档 https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_contentdocutm_campaignrewrite 。配置这东西写一次、验证一次、提交一次后面每个人都能省下重复解释的时间。
