装好 Claude Code、接上 API 之后,很多人会发现它「能用但不够顺手」:每次新会话都要重新解释项目怎么跑测试、哪些目录不能动;想让它查数据库、操作浏览器,又不知道从哪接。这两件事分别对应 Claude Code 的两个进阶功能:CLAUDE.md 让它记住项目的规矩,MCP 让它接上外部工具。这篇把两者的位置、写法和常用命令讲清楚。还没装好的话,先看 macOS / Linux 安装教程 或 Windows 安装教程。
CLAUDE.md 是什么
CLAUDE.md 是 Claude Code 的「项目记忆」:每次启动会话时自动读入,内容相当于你每次开工前都会交代的那些话。写好了,模型一上来就知道怎么构建、怎么测试、代码风格是什么,不用你每次重复。
它可以放在几个位置:
| 位置 | 作用范围 | 适合放什么 |
|---|---|---|
| 项目根目录 CLAUDE.md | 当前项目,提交进仓库全队共享 | 构建命令、代码规范、架构说明 |
| 子目录里的 CLAUDE.md | 处理该目录下的文件时读入 | 某个模块特有的约定 |
| ~/.claude/CLAUDE.md | 你本机的所有项目 | 个人习惯,如回复语言、提交信息风格 |
在 monorepo 里,可以在根目录写全局约定,再给前端、后端各放一份更具体的 CLAUDE.md。
快速生成第一版
在项目目录里启动 Claude Code,输入:
/init它会分析代码库,生成一份包含构建命令、目录结构和主要约定的初稿。生成后一定要人工改一遍:删掉显而易见的内容,补上只有你知道的坑。之后想修改时,用 /memory 可以直接打开记忆文件编辑。
写什么、不写什么
值得写进去的,是模型从代码里看不出来、或者很容易做错的东西:
- 常用命令:怎么装依赖、跑单个测试、跑 lint、启动开发服务器
- 代码规范:工具检查不到的约定,例如错误处理方式、命名习惯、哪些库不要用
- 架构地图:核心目录各管什么,改某类功能应该去哪里改
- 工作流程:提交前必须跑哪些检查,数据库迁移怎么生成
- 已知的坑:某个测试依赖本地服务、某个配置文件是自动生成的不要手改
不值得写的:通用的编程建议(「写清晰的代码」)、代码里一眼就能看到的信息、很长的背景故事。一个简短的例子:
# 项目约定
## 常用命令
- 安装依赖:pnpm install
- 单个测试:pnpm test -- path/to/file.test.ts
- 提交前:pnpm lint && pnpm typecheck
## 规范
- API 层统一抛 AppError,不要直接 throw Error
- 数据库访问只放在 src/repo/,业务代码不要直接写 SQL
## 注意
- src/generated/ 是自动生成的,不要手改
- e2e 测试依赖本地 Redis,单元测试不需要文档比较长时,不必全部塞进 CLAUDE.md,可以用 @ 引用其它文件,例如写一行 @docs/architecture.md,让它按需读取。
控制长度:它每一轮都要花 Token
CLAUDE.md 会随每一次请求发给模型,写得越长,每一轮的输入 Token 越多。经验上控制在一两屏以内,定期删掉过时内容。提示缓存会降低重复部分的成本,但不会让它变成零。更多省 Token 的做法见 Claude Code 省 Token 技巧。
MCP 是什么
MCP(Model Context Protocol)是让 Claude Code 调用外部工具的标准协议。接上 MCP 服务器以后,模型可以操作浏览器、查询数据库、读写工单系统或在线文档,而不只是读写本地文件和跑命令。
MCP 服务器分两类:
- 本地服务器:在你机器上以子进程运行,通常用 npx 或 uvx 启动
- 远程服务器:通过 HTTP 地址连接,由服务方托管,常需要登录授权
添加 MCP 服务器
本地服务器,命令放在 -- 后面。以 Playwright 浏览器自动化为例:
claude mcp add playwright -- npx @playwright/mcp@latest需要环境变量的,用 -e 传入:
claude mcp add my-db -e DATABASE_URL=postgres://localhost/dev -- npx -y your-db-mcp-server远程服务器用 --transport http,需要鉴权头时加 --header:
claude mcp add --transport http my-api https://mcp.example.com/mcp \
--header "Authorization: Bearer your-token"管理命令:
claude mcp list # 查看已添加的服务器
claude mcp get playwright # 查看某个服务器的配置
claude mcp remove playwright在会话里输入 /mcp 可以查看各服务器的连接状态,需要 OAuth 登录的远程服务器也在这里完成授权。
三种作用域
添加时用 --scope 指定作用域:
| 作用域 | 存在哪 | 谁能用 |
|---|---|---|
| local(默认) | 你本机,针对当前项目 | 只有你,只在这个项目 |
| project | 项目根目录的 .mcp.json | 提交后全队共享 |
| user | 你本机的用户配置 | 只有你,所有项目 |
团队都要用的服务器用 project 作用域,生成的 .mcp.json 长这样:
{
"mcpServers": {
"playwright": {
"command": "npx",
"args": ["@playwright/mcp@latest"]
}
}
}.mcp.json 会进仓库,不要把密钥直接写进去。它支持引用环境变量,写成 ${DATABASE_URL} 这样的形式,每个人在自己的环境里配置真实值。出于安全考虑,Claude Code 第一次使用项目里 .mcp.json 声明的服务器前会请你确认。
通过 Zivv 使用时要注意什么
MCP 服务器运行在你这边,Claude Code 把工具定义随请求一起发给模型,模型决定调用哪个工具,再由 Claude Code 在本地执行。这套流程走的是标准的 Anthropic 工具调用协议,通过 Zivv 使用不需要任何额外配置。
需要留意两点:
- 工具定义也占 Token:每接一个 MCP 服务器,它的全部工具定义都会出现在每一轮请求里。用不到的服务器及时移除,或者只在需要的项目里用 local 作用域添加
- 换模型时确认工具调用能力:Claude 全系列都支持工具调用;如果用 DeepSeek、GLM 等模型驱动 Claude Code,它们同样支持工具调用,但复杂的多工具编排 Claude 通常更稳,见 国产大模型接入
安全提醒
MCP 服务器能读取数据、执行操作,权限和你本机的程序一样大。只安装来源可信的服务器,给数据库类服务器使用只读账号或测试库,团队共享的 .mcp.json 合并前像代码一样做评审。
常见问题 FAQ
Q:CLAUDE.md 改了要重启会话吗? A:新开的会话会读到最新内容。正在进行的会话里如果改了,可以直接告诉模型「重新读一下 CLAUDE.md」。
Q:CLAUDE.md 写中文还是英文? A:都可以。按团队习惯写,关键是简短、具体、可执行。
Q:MCP 服务器连不上怎么办? A:先在会话里用 /mcp 看状态和报错,再单独在终端运行一次服务器的启动命令,确认依赖装好、环境变量正确。
Q:子代理和 MCP 是一回事吗? A:不是。子代理是 Claude Code 内部把任务拆给独立上下文执行的机制,MCP 是接外部工具的协议,两者可以一起用。
写在最后
CLAUDE.md 解决「每次都要重新交代」,MCP 解决「只能读写本地文件」,两者配好以后,Claude Code 才真正像一个熟悉项目的同事。底层的模型调用照常通过 Zivv:注册 Zivv 拿到 Key,按 Claude Code 专区 配好两个环境变量,就可以开始折腾这些进阶功能。