1. 为什么你的 Claude Code 总在“失忆”从一次真实返工说起刚用 Claude Code 的前两周我几乎每天都在重复同一句话“保持最小改动别顺手重构。”它答应得很好下一次会话又忘得干干净净。这不是模型笨而是它每次开新会话时对项目的认知是空白的——除非你提前把规矩写下来。CLAUDE.md就是这份“规矩”。它是 Claude Code 在每次会话启动时第一个读取的文件相当于给 AI 签的一份项目契约代码风格、目录约定、测试命令、禁止事项全写在这里。你不需要每次对话都重复交代它自己会先读一遍再动手。这份契约适合谁三类人最该马上做一是刚接触 Claude Code、还在被“AI 乱改代码”折磨的开发者二是团队里多人共用一套仓库、希望 AI 输出风格统一的工程组三是用 Claude Code 做非编码任务写文档、做产品原型的产品或运营同学。一句话只要你希望 AI 稳定遵循项目规范CLAUDE.md就是初始化阶段最该花时间的一件事。我实测下来同一句“优化 index.html”没有契约时它删了半个文件的样式还改了变量命名写好契约后它只动了三处、每处都带注释说明。差别不在模型在于你有没有把约束前置。下面按“问题场景 → 前置准备 → 可复制配置 → 验证请求 → 常见报错 → 后续动作”的顺序展开每一步都能直接跟做。2. 接入前的准备TaoToken 环境与 Claude Code 安装配置在写契约之前得先让 Claude Code 能跑起来。国内直连 Anthropic 官方接口经常超时所以这里用 TaoToken 做接入层——它提供兼容 Anthropic 协议的 API 端点Claude Code 只需改两个环境变量就能指向它。先拿到 API Key。打开 https://taotoken.net/api-keys 登录后创建一个新 Key复制保存。注意 Key 只在创建时完整显示一次丢了就得重建。接着配置环境变量。Claude Code 读取的是ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN这两个变量。Linux/macOS 下写入 shell 配置文件# 写入 ~/.zshrc 或 ~/.bashrc export ANTHROPIC_BASE_URLhttps://taotoken.net/api export ANTHROPIC_AUTH_TOKENsk-你刚才复制的KeyWindows PowerShell 用户用$env:ANTHROPIC_BASE_URL https://taotoken.net/api $env:ANTHROPIC_AUTH_TOKEN sk-你刚才复制的Key改完执行source ~/.zshrc或重开终端然后验证 Claude Code 是否装好claude --version如果提示命令不存在先安装npm install -g anthropic-ai/claude-code安装完成后进入你的项目目录执行claude启动。第一次启动它会问你信任哪些目录选当前项目即可。此时如果配置正确你会看到交互界面输入一句“你好”能正常回复说明接入层通了。这里有个容易踩的坑ANTHROPIC_BASE_URL末尾不要加/v1Claude Code 会自己拼接路径。加了反而会 404。另外 Key 不要写进项目里的.env并提交到 Git环境变量方式最安全。环境通了才轮到本文的主角——契约文件。没有可用的 Claude Code写再多CLAUDE.md也没人读。3. 可复制的 CLAUDE.md 配置三层结构与完整模板Claude Code 的契约体系分三层按加载顺序从广到窄层级路径作用域是否提交 Git全局~/.claude/CLAUDE.md本机所有项目否项目./CLAUDE.md或./.claude/CLAUDE.md当前仓库是本地./CLAUDE.local.md当前仓库、仅自己否全局文件放跨项目通用的偏好比如“注释用英文”“保持最小 diff”。项目文件放架构、命令、目录约定。本地文件放个人备注比如“我本地测试端口是 3001”。先创建全局文件mkdir -p ~/.claude touch ~/.claude/CLAUDE.md然后写入下面这份精简模板控制在 80 行内别贪多# 全局编码契约 ## 沟通方式 - 默认中文回复代码、命令、变量名用英文 - 不确定时先读代码库不要凭空发明模式 ## 代码风格 - 注释仅使用英文 - 遵循 DRY、KISS、YAGNI 原则 - 保持改动最小只围绕当前请求不回退无关改动 ## 错误处理 - 始终显式抛出错误绝不静默忽略 - 错误信息包含调试上下文请求参数、状态码 - 日志用结构化字段不要把动态值插进消息字符串 ## 终端使用 - 优先非交互式命令 - git diff 用 git --no-pager diff - 搜索优先用 rg ## 工作流 - 修改前先读现有代码和相关 CLAUDE.md - 若项目指令含测试或 lint 命令且本次改了代码完成前必须运行项目级文件更具体。在项目根目录执行 Claude Code 的/init命令它会扫描项目生成初稿cd your-project claude # 进入交互后输入 /init生成的初稿通常是英文且偏泛手动改成中文并补上关键信息。一份可直接用的项目模板# 项目契约 ## 项目概述 静态 HTML 演示页单文件 index.html内嵌 CSS 与 JS。 ## 目录结构 - index.html 入口页面 - assets/ 静态资源 - docs/ 设计文档 ## 常用命令 - 本地预览python3 -m http.server 8000 - 格式化npx prettier --write . ## 命名规范 - CSS 类名用 kebab-case - JS 变量用 camelCase常量全大写 ## 边界与禁止 - 不要引入新的第三方库除非明确要求 - 不要改动 assets/ 下的二进制文件 - 提交前必须跑一次格式化命令如果项目前后端分离在frontend/和backend/各自放一份CLAUDE.md避免规范互相干扰。子目录文件会覆盖上层同名规则。写契约的核心判断标准只有一条Claude 能从代码里读出来的不要写它猜不到的必须写。比如“用 4 空格缩进”它能从现有代码看出来不用写“测试前必须先跑npm run build”它猜不到必须写。4. 验证契约是否生效重跑同一任务对比输出写完契约不算完得验证它真的被读取、真的改变了行为。方法很简单找一个之前让 AI 做过的任务清空会话重跑对比前后差异。先准备一个“反例”。在没写契约时让 Claude Code 优化index.html它大概率会大改结构、改命名、加一堆没要求的兜底逻辑。记下这次 diff 的行数。然后确认契约文件就位ls -la ./CLAUDE.md cat ./CLAUDE.md | head -20重启 Claude Code退出再进确保新会话加载契约输入同一句指令优化 index.html保持最小改动观察它的行为。生效时你会看到几个明显信号它先读CLAUDE.md界面会显示读取动作改动前会说明“根据项目契约我只调整 X”diff 行数显著减少且不会引入新库。我实测同一任务无契约时改了 47 行、动了 3 个函数名有契约后只改了 9 行全部集中在目标区域还附了英文注释。这就是契约的价值——把“每次都要交代”变成“一次写好、次次生效”。如果发现它没读契约检查三点文件是否在项目根目录、文件名大小写是否为CLAUDE.md、当前会话是否在契约写入之后启动的。改完契约必须重启会话才生效热更新不保证。验证通过后把契约提交到 Gitgit add CLAUDE.md git commit -m chore: add CLAUDE.md contract团队协作时这份文件就是 AI 输出的统一标准新人拉下仓库即生效。5. 常见报错排查401、local proxy failed 与契约不生效接入和验证过程中几类报错最常出现逐个对照处理。401 UnauthorizedKey 无效或没被读取。先确认环境变量生效echo $ANTHROPIC_AUTH_TOKEN输出为空说明没写进当前 shell重新source配置文件。输出有值但仍 401去 https://taotoken.net/api-keys 检查 Key 是否被删或额度耗尽必要时重建。local proxy failed / connection refused通常是ANTHROPIC_BASE_URL写错。正确值是https://taotoken.net/api不要带/v1不要带末尾斜杠。改完重启终端。reading choices 相关报错这类多出现在用 OpenAI 兼容格式调用时。Claude Code 走的是 Anthropic 协议确认你用的端点是 Anthropic 兼容入口而不是 OpenAI 的/v1/chat/completions。契约不生效最常见原因是文件位置或命名错误。Claude Code 只认根目录的CLAUDE.md或.claude/CLAUDE.mdclaude.md小写不认。另一个原因是会话没重启旧会话仍用旧契约。OAuth 相关提示如果你之前登录过官方账号可能残留凭证冲突。清理~/.claude/下的旧凭证文件只保留环境变量方式。排查时记住一个顺序先验证环境变量 → 再验证网络可达 → 最后验证契约文件。多数问题出在第一步。6. 契约之后让规则随错误迭代而不是一次写全契约不是一次性写完的文档而是随项目生长的活文件。最好的迭代方式是AI 每犯一次同样的错就往CLAUDE.md加一条规则。你可以直接让 Claude Code 自己写规则。发现它又加了没要求的兜底逻辑就说你刚才加了未要求的兜底逻辑把这条约束写进 CLAUDE.md它会生成一条精确规则并追加。这比自己措辞更省事也更贴合实际场景。长期用 Claude Code 做编码和 Agent 任务的话稳定的额度比反复试错更重要。需要持续跑项目、频繁调用模型的可以看看 Coding Planhttps://taotoken.net/coding-plan?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentcoding_plan 按周期计费比按量更划算。只是偶尔验证模型效果的用模型对话https://taotoken.net/chat?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentmodel_chat 就够。接入细节和参数说明都在接入文档https://taotoken.net/doc?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_contentdoc 里遇到协议问题先查它。最后给一个实用习惯每次项目初始化先跑/init生成草稿手动精简到 80 行内提交 Git再开始写业务代码。契约先行后面每一次会话都省心。