1. 为什么你的 Claude Code 每次都要重新解释项目Claude Code 是 Anthropic 推出的终端原生 AI 编程助手它跑在命令行里能直接读写文件、执行 shell 命令、创建 git 提交。但很多人第一次用完之后会有个共同的困惑明明昨天刚跟它讲过这个项目用 pnpm 不用 npm接口错误统一返回{code, message}今天开个新会话它又按默认习惯给你生成一堆 npm 命令和裸抛异常。问题不在模型在于你没把项目约定沉淀下来。Claude Code 每次会话启动时会读取一个叫CLAUDE.md的记忆文件以及.claude/settings.json里的配置。这两个东西不写它就等于每次都在空手进你的仓库。这篇就围绕 CLI 环境下的配置落地来讲怎么写出能真正生效的CLAUDE.md怎么用 Slash Commands 把高频操作固化成一条命令以及怎么逐条验证它们确实被加载了。适合谁看已经在终端里跑过claude命令、但还没系统配置过项目记忆和自定义命令的开发者。如果你连安装都还没做先npm install -g anthropic-ai/claude-code然后claude --version确认能打印版本号再往下看。2. 前置准备把 CLI 和项目目录理顺2.1 确认运行环境Claude Code 对 Node 版本有要求低于 18 会在启动时报错。用 nvm 切到 22 LTS 最稳nvm install 22 nvm use 22 node -v # 期望输出 v22.x.xWindows 用户注意原生 PowerShell 下部分命令行为不一致建议在 WSL2 或 Git Bash 里操作路径分隔符和权限模型都更接近文档描述。2.2 进入项目并初始化cd your-project claude首次启动会走一次授权流程完成后令牌会缓存到本地后续不用重复登录。进去之后先别急着让它写代码第一件事是执行/init/init这个命令会在项目根目录生成一个初始的CLAUDE.md内容是根据你仓库结构自动推断出来的项目描述、技术栈和常见模式。自动生成的东西只能算草稿真正有价值的是你手动往里补的规则。2.3 关于模型接入的一点说明Claude Code 默认走 Anthropic 官方接口。如果你希望通过兼容协议接入其他模型服务可以在~/.claude/settings.json里配置ANTHROPIC_BASE_URL和ANTHROPIC_AUTH_TOKEN两个环境变量指向对应的 API 端点。TaoToken 提供了 Anthropic 兼容的 API 接入方式控制台里可以创建密钥接入文档https://taotoken.net/api 密钥管理https://taotoken.net/console/api-keys?utm_sourcetaotoken_aicg_blog_endutm_contentapi_keysutm_campaignrewrite配置好之后/model命令切换模型时就会走你设定的端点。这一步不是必须的但如果你手头有多个模型想对比着用提前配好省得来回改。3. 可复制的 settings.json 骨架3.1 配置文件的三层结构Claude Code 的配置分三层优先级从低到高路径用途是否提交 Git~/.claude/settings.json全局个人偏好否项目.claude/settings.json团队共享配置是项目.claude/settings.local.json本地个人覆盖否加进 .gitignore团队规范放中间那层个人习惯放最上面或最下面那层。这样别人 clone 你的仓库后能直接继承团队约定又不会把你的本地路径带进去。3.2 一份能直接用的骨架在项目根目录建.claude/settings.json写入{ permissions: { defaultMode: acceptEdits, allow: [ Read, Glob, Grep, Edit, Bash(git status), Bash(git diff *), Bash(pnpm run *), Bash(pnpm test *) ], deny: [ Read(**/.env*), Read(**/.ssh/**), Read(**/*.pem), Bash(sudo *), Bash(rm -rf *) ] }, hooks: { PostToolUse: [ { matcher: Write(*.ts), hooks: [ { type: command, command: npx prettier --write $file } ] } ] } }几个关键点解释一下。defaultMode设成acceptEdits表示文件修改自动接受但 shell 命令仍然要确认——这是安全和效率的折中。allow里我特意把Bash(pnpm run *)这种带通配的放进去因为日常跑脚本太频繁每次都点确认很烦。deny里把.env、.ssh、.pem全部挡掉防止模型在探索代码库时把密钥读进上下文。hooks里的PostToolUse是文件写入后的自动格式化。$file是 Claude Code 注入的变量代表刚被修改的文件路径。注意 matcher 写的是Write(*.ts)只对 TypeScript 文件生效避免误格式化 JSON 或 Markdown。3.3 权限模式的选择defaultMode有三个常用值default每次修改和命令都确认最安全适合刚上手或敏感仓库acceptEdits文件修改自动执行shell 命令仍需确认日常开发推荐plan只读模式只分析不改动适合读陌生项目我试过在重构老项目时先用plan模式让它把架构梳理清楚确认方案后再切acceptEdits执行比一上来就让它动手稳得多。4. CLAUDE.md 模板让项目记忆真正生效4.1 自动生成只是起点/init生成的CLAUDE.md通常长这样项目名、技术栈、目录结构说明。这些信息模型从代码里也能推断出来价值有限。真正要补的是那些代码里看不出来、但你必须遵守的约定。4.2 一份带具体规则的模板把下面这段追加到CLAUDE.md末尾按你项目实际情况改# 项目约定 ## 包管理 - 使用 pnpm禁止使用 npm 或 yarn - 新增依赖前先确认是否已有同类库 ## 认证 - 使用 JWT不使用 session - token 存储在 httpOnly cookie 中 - 刷新逻辑统一走 src/auth/refresh.ts ## 错误处理 - API 返回结构化错误{ code: number, message: string } - 禁止直接 throw 字符串 - 网络层错误统一在 src/api/errorHandler.ts 处理 ## 测试 - 所有 API endpoint 必须有测试 - 使用 Vitest不使用 Jest - 测试文件与被测文件同目录命名 *.test.ts ## 代码风格 - 函数参数超过 3 个时改用对象传参 - 禁止 any必要时用 unknown 加类型守卫4.3 为什么这些规则能被记住Claude Code 每次会话启动时会读取CLAUDE.md并注入上下文。所以你在里面写的每一条都相当于每次对话开头都跟它重申一遍。规则要写得可执行——使用 pnpm比注意包管理规范有用得多因为前者是明确指令后者模型只能猜。一个容易踩的坑CLAUDE.md不要写太长。它占的是上下文窗口写个几百行会把真正有用的代码空间挤掉。只放高频、易错、代码里看不出的约定其余交给模型自己读代码。4.4 用 /memory 快速编辑不想退出会话去改文件直接在交互模式里敲/memory它会打开CLAUDE.md供你编辑保存后当前会话立即生效不用重启。5. Slash Commands 自定义命令实战5.1 内置命令先摸一遍在会话里输入/会列出所有可用命令。常用的几个命令作用/init生成 CLAUDE.md/compact压缩对话历史回收上下文/clear完全清空对话/context查看当前上下文用量/model切换模型/doctor诊断安装和配置问题/cost查看本次会话 token 消耗/compact有个进阶用法可以指定保留什么/compact preserve all architecture decisions, file paths, and error messages这样压缩后关键信息不会丢。建议在/context显示用到 70% 左右时就压别等满了再处理。5.2 自定义命令放在哪自定义 Slash Command 本质是一个 Markdown 文件放在.claude/commands/目录下文件名就是命令名。比如建.claude/commands/review.md之后就能用/review调用。5.3 写一个代码审查命令创建.claude/commands/review.md--- description: 对指定文件做三重审查 --- 请对 $ARGUMENTS 执行以下审查逐项输出结果 1. 类型安全是否存在 any、类型断言滥用、未处理的 null 2. 错误处理是否有未捕获的 Promise rejection、裸 throw 3. 边界条件空数组、超长输入、并发调用是否处理 对每个问题给出文件路径:行号、问题描述、修复建议。 不要直接修改文件先列清单。$ARGUMENTS是调用时传入的参数。用法/review src/api/user.ts它会把src/api/user.ts替换进$ARGUMENTS的位置。description字段会显示在/命令列表里方便记忆。5.4 写一个提交前检查命令创建.claude/commands/precommit.md--- description: 提交前跑一遍检查清单 --- 按顺序执行 1. 运行 pnpm lint如有报错逐条修复 2. 运行 pnpm test确认全部通过 3. 检查 git diff确认没有遗留的 console.log 和调试代码 4. 生成一条符合 Conventional Commits 规范的提交信息 每步完成后报告结果遇到失败停下来等我确认。这个命令把提交前的重复劳动固化了。注意最后一句遇到失败停下来等我确认——不加这句模型可能会自作主张跳过失败的测试继续往下走。5.5 命令的验证方式写完命令文件后在会话里敲/看列表里有没有出现你定义的命令名和 description。有就说明加载成功。然后实际调用一次观察$ARGUMENTS是否正确替换。6. 逐条验证配置是否生效配置写完不验证等于没配。下面几条命令按顺序跑一遍。6.1 验证 CLAUDE.md 被读取在会话里直接问我们这个项目用什么包管理器如果CLAUDE.md里写了使用 pnpm它应该回答 pnpm 而不是 npm。答错了说明文件没被读到检查是不是放在了项目根目录、文件名大小写是否正确。6.2 验证权限规则生效让它尝试读一个被 deny 的文件读一下 .env 文件的内容正常情况应该被拦截提示权限不足。如果它真读出来了检查deny规则里的 glob 写法Read(**/.env*)里的**是匹配任意层级目录。6.3 验证 hook 触发让它创建一个测试用的 TS 文件在 src 下创建一个 tmp-test.ts内容随便写个函数创建完成后打开那个文件看格式是否被 prettier 处理过比如缩进、分号风格统一。没变化的话检查 hook 里的command路径能不能在项目根目录直接执行。6.4 验证自定义命令/review src/index.ts观察它是否按你定义的三个维度输出审查清单而不是泛泛地评价代码。6.5 环境异常先跑 /doctor如果上面任何一步行为诡异先执行/doctor它会检查安装完整性、配置语法、权限设置是环境问题的第一排查手段。7. 本篇常见报错与排查7.1 settings.json 语法错误导致配置静默失效JSON 不允许尾随逗号多一个逗号整个文件就解析失败而且 Claude Code 不一定会明确报错表现是配置看起来没生效。排查方法cat .claude/settings.json | python3 -m json.tool能正常格式化输出说明语法没问题报错就按提示的行号改。7.2 CLAUDE.md 写了但模型不遵守先确认文件位置对必须是项目根目录的CLAUDE.md不是.claude/CLAUDE.md。其次检查规则是否可执行——代码要优雅这种模型没法执行函数参数超过 3 个改用对象传参才能落地。最后看长度超过几百行时关键规则可能被稀释精简一下。7.3 自定义命令不出现三个检查点文件是否在.claude/commands/目录下、扩展名是否是.md、frontmatter 的---是否成对闭合。少一个闭合的---整个文件会被当成普通文本而不是命令定义。7.4 hook 里的 $file 没被替换$file只在PostToolUse且 matcher 匹配到具体文件时才注入。如果你写的 matcher 是Write(*)但实际触发的是Edit工具就不会替换。确认 matcher 里的工具名和实际操作一致。7.5 上下文很快用满/context看用量超过 70% 就/compact。另外检查CLAUDE.md是不是太长以及有没有把大文件整个读进上下文。精准引用文件用src/utils/auth.ts这种写法比让它自己 Glob 搜索省得多。8. 把配置沉淀成团队资产配置这件事的价值在于复用。CLAUDE.md和.claude/settings.json提交到 Git 后新同事 clone 下来第一次跑claude就自动继承了团队约定不用口头交接。自定义命令同理/review、/precommit这些固化了团队流程的命令比写在文档里没人看强得多。如果你还在对比不同模型在代码任务上的表现可以在 TaoToken 控制台创建密钥后通过/model切换着试模型对话体验https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentmodel_chatutm_campaignrewrite 接入文档https://taotoken.net/api长期跑编码任务、需要稳定额度的话Coding Plan 更适合日常高频使用Coding Planhttps://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_contentcoding_planutm_campaignrewrite配置落地之后你会发现 Claude Code 真正好用的地方不是它能写多少代码而是它记住了你项目的规矩不用每次从头解释。