第一个文件：CLAUDE.md

CLAUDE.md 是 Claude Code 启动时第一个读的文件。写在里面的东西Claude 在每一次对话里自动遵守。全局 CLAUDE.md 的精简模板## 沟通方式 - 默认中文回复代码、命令、变量名、文件路径保持英文 - 结论先行简洁直接不先铺垫背景 - 不谄媚不夸这是个很好的问题不以当然可以开头 - 给真实判断——方案有问题直接指出发现更好做法主动说明 ## Git - 不自动 git commit 或 git push除非我明确要求 - 提交前先展示将要提交的变更摘要 - commit message 使用简洁英文 ## 红线操作 以下操作即使在 auto-accept 模式下也必须先问我 - 删除文件、目录或 git 历史 - 修改 .env、密钥、token、证书、CI/CD 配置 - git push、git rebase、git reset --hard、强制推送 - 公开发布npm publish、生产部署等项目级的 CLAUDE.md 再加一层技术栈、目录结构、commit 格式、禁区如不要碰 migrations/ 目录。两个文件叠加Claude 第一次打开项目就知道——跑测试是pnpm vitest run而不是npm test数据库操作全在src/lib/services/里。维护策略每被 Claude 坑一次立刻加一条到 CLAUDE.md。过时的规则删掉内容保持精炼。三个月下来这个文件就是这个项目 Claude 犯过的所有错误的预防清单。最有生产力的一句话是更新 CLAUDE.md让这件事不再发生。3.6.3 第二个文件settings.json用 Claude Code 最烦的就是弹窗。这个文件把该放行的放行、该锁住的锁住写死{ permissions: { allow: [ Read, Glob, Grep, Edit, MultiEdit, Write(src/**), Write(tests/**), Bash(npm *), Bash(pnpm *), Bash(git status), Bash(git diff *), Bash(git log *), Bash(git add *), Bash(git commit *), Bash(cat *), Bash(head *), Bash(tail *), Bash(find *) ], deny: [ Read(**/.env*), Read(**/*.pem), Read(**/*.key), Read(**/secrets/**), Read(**/credentials/**), Write(**/.env*), Write(**/secrets/**), Write(package-lock.json), Write(.github/workflows/*), Bash(rm -rf *), Bash(sudo *), Bash(git push *), Bash(git merge *), Bash(git rebase *), Bash(docker *), Bash(curl * | sh), Bash(chmod *) ], defaultMode: acceptEdits } }allow 白名单日常安全操作不应该每次都问——读文件、写源码、跑测试、git 日常命令。deny 黑名单安全红线——读 .env、读密钥、rm -rf、sudo、git push。配完之后日常操作零弹窗危险操作自动封堵。注意allow 按你的工具链改——用 yarn 就加Bash(yarn *)用 bun 就加Bash(bun *)。deny 那几行建议原样留着它们是安全底线。3.6.4 第三个文件.gitignore除了常规忽略多加几行保护 AI 工具配置和密钥不被提交到 git# AI 工具本地配置 .claude/settings.local.json .cursor/ .aider* .continue/ .cody/ # 密钥和凭证 *.pem *.key credentials.json .npmrc .aws/ .ssh/注意一个细节.claude/settings.local.json被 gitignore 了但.claude/settings.json和.claude/skills/没有。意思是——项目配置团队共享个人偏好含 API key自己留着。3.6.5 第四个9 个 Slash CommandSkillsSkills 把你上线前的心理检查清单变成命令——不用再临时想还有什么没查敲个/它按你的规矩跑完。每个 Skill 就是一个 Markdown 文件放在.claude/skills/[名字]/SKILL.md。9 个 Skill 的完整写法见第五部分。这里快速看三个最核心的/review— 审代码。不看风格按严重程度排CRITICAL逻辑错误、空指针、竞态条件、安全漏洞WARNINGN1 查询、缺少错误处理、性能隐患INFO命名、垃圾代码、TODO输出 checklist结尾总结 X critical, Y warnings, Z info/commit— 提交代码。自动跑git status和git diff --stat把改动按逻辑分组格式遵循type(scope): description。/deploy-check— 上线前检查。按顺序跑类型检查 → 测试 → lint → 构建 → 搜console.log→ 检查 .env 引用 → 确认没有未提交的改动。全绿才上线。另外 6 个/test、/pr、/debug、/refactor、/docs、/security。套路相同——frontmatter 声明 name、description、allowed-tools后面写检查步骤。核心价值写一次以后每次都是它替你查。详见第四部分完整教程。3.6.6 三种安装方式场景做法从零开始的新项目模板复制进去填入技术栈第一次 commit 就带着完整配置已有项目CLAUDE.md 和 .gitignore 加到根目录settings.json 合并到现有配置skills 文件夹拖进去所有项目通用settings.json 和 skills 放~/.claude/全局生效CLAUDE.md 每个项目单独写推荐做法settings.json 和 skills 放全局CLAUDE.md 每个项目单独写。权限和命令不用每个项目配一遍但项目上下文是独立的。3.6.7 这套配置是活的模板最大的意义不是直接用是以此为起点让它越长越像你的项目CLAUDE.md 是活的Claude 每犯一次错就加一条。记住这句话更新 CLAUDE.md让这件事不再发生settings.json 跟着项目长大新工具来了加 allow发现新的危险操作加 denySkills 长出自己的版本/review里加你代码库特有的常见问题/commit里写团队的 scope 命名规范.gitignore 持续更新每用一个新工具看它会不会在本地生成配置文件三个月后回头看最初的模板已经被使用习惯磨成了不同的形状。这个变化本身就是价值——你的项目越来越像你Claude 也越来越懂你。3.7 Claude Code 常见问题与排查FAQ3.7.1 安装类问题Q1安装时报ENOENT: no such file or directory原因npm 缓存损坏解决运行npm cache clean --force然后重新安装Q2安装成功但claude命令找不到原因npm 全局安装路径未加入系统 PATH解决运行npm config get prefix将输出的路径加入系统 PATH 环境变量Q3Windows 上报无法加载文件因为在此系统上禁止运行脚本原因PowerShell 执行策略限制解决以管理员身份打开 PowerShell运行Set-ExecutionPolicy RemoteSigned3.7.2 连接/API 类问题Q4启动后提示Invalid API Key原因API Key 配置错误或过期解决检查环境变量ANTHROPIC_API_KEY是否正确设置。用echo $ANTHROPIC_API_KEYmacOS或echo $env:ANTHROPIC_API_KEYPowerShell验证Q5中转服务配置后连接超时原因中转服务地址错误或服务不可用解决1. 检查ANTHROPIC_BASE_URL是否正确 2. 用浏览器访问中转服务网站确认其正常运行 3. 尝试用 curl 直接测试API连通性Q6提示Rate limit exceeded原因短时间内发送了太多请求解决等待 1 分钟后重试。如果频繁出现考虑升级 API 套餐3.7.3 使用类问题Q7AI 修改了不该改的文件原因需求描述不够明确AI自行判断需要修改解决1. 用git checkout .撤销修改 2. 重新描述需求明确指定只修改 xxx 文件 3. 在 CLAUDE.md 中注明不要修改的文件Q8AI 陷入改A坏B、改B坏A的循环原因AI缺乏全局视角修复一个问题引入新问题解决1. 用git checkout .回退到稳定版本 2. 用/clear清空对话 3. 重新描述完整的需求让 AI 一次性考虑所有约束Q9对话太长后 AI 开始遗忘早期内容原因上下文窗口接近满载解决使用/compact压缩上下文或开新会话Q10AI 生成了一个不存在的npm包或API原因AI 幻觉编造不存在的东西解决在使用 AI 推荐的包之前先到 npmjs.com 搜索确认它是否存在3.8 自定义斜杠命令Custom Slash Commands你可以创建自己的斜杠命令将常用操作封装成快捷方式。在项目根目录创建.claude/commands/目录然后添加 Markdown 文件!-- .claude/commands/deploy.md -- # 部署检查清单 请执行以下部署前检查 1. 运行所有测试npm test 2. 检查是否有 lint 错误npm run lint 3. 确认 .env.example 已更新如果添加了新的环境变量 4. 构建项目npm run build 5. 报告所有检查结果使用方式 /deployClaude Code 就会按照你定义的步骤执行部署检查。3.9 Claude Code 使用模式Plan Mode 与三种权限模式初学者常问“用 Claude Code 是应该先让它规划整个项目再执行还是自己分模块逐步让它做”答案Claude Code 原生提供了Plan Mode规划模式。它不是“一种提示词技巧”而是官方内置的一个只读运行模式在该模式下 AI 只能分析不能修改有专门的快捷键与命令可随时切入。3.9.1 三种运行模式官方Claude Code 内置三种互斥的运行模式模式行为适合场景状态栏提示Normal默认每次文件修改、命令执行都要你确认默认、小任务、需要逐步审查无特殊标记Auto-Accept自动接受不再询问直接执行已计划好的批量任务、可信操作accept edits onPlan Mode规划模式全面只读只能分析、提问、出方案复杂任务、不熟悉的代码库、架构决策plan mode on3.9.2 Plan Mode 能做什么、不能做什么在 Plan Mode 下AI 只能调用这些只读工具工具作用Read查看文件内容Glob按 pattern 查找文件Grep用正则在文件内容中搜索LS列出目录内容WebSearch / WebFetch联网查资料Task启动只读子代理去调研AskUserQuestion向你提交选项题以澄清需求严格禁止写入文件、修改文件、运行 shell 命令、运行测试、任何改动项目的动作。这保证你在看到 AI 计划之前它不会动你项目中的任何一行代码。提示Plan Mode 的重点是先探索和规划暂不修改文件。不同版本可能会用不同的内部检索或子任务机制来辅助调研不建议把某个内部实现细节当成稳定接口来记。3.9.3 四种进入 Plan Mode 的方式重点进入 Plan Mode 的 4 种方式① 快捷键ShiftTab ×2Windows 某些终端用 AltM② 斜杠命令/planClaude Code v2.1.0③ 启动参数claude --permission-mode plan④ 默认配置.claude/settings.jsonpermissions.defaultMode plan图进入 Plan Mode 的四种方式从临时到永久方式一键盘快捷键 ShiftTab最常用在 Claude Code 会话中连按两次Shift Tab第一次 ShiftTab → 切到 Auto-Accept Mode状态栏 accept edits on 第二次 ShiftTab → 切到 Plan Mode 状态栏 plan mode on 第三次 ShiftTab → 切回 Normal Mode注意Windows 用户注意某些 Windows 终端如部分 PowerShell 配置上ShiftTab只能在 Normal/Auto-Accept 间切换跳过了 Plan Mode。请改用Alt M切入 Plan Mode该问题在官方 Issue 中已标记为已知问题。方式二会话中输入/plan命令v2.1.0Claude Code v2.1.0 之后支持直接在提示符中输入斜杠命令 /plan会话会立即切入 Plan Mode。特别适合“继续聊到一半发现需要规划”的场景。方式三启动时直接进 Plan Mode如果你明确知道本次是复杂任务可以从启动就进入 Plan Mode# 交互式 claude --permission-mode plan # 无头模式可用于 CI / 脚本 claude --permission-mode plan -p 分析认证模块并提出优化建议方式四设为项目默认模式如果某个项目你一直希望默认“先规划后执行”可以在项目根的.claude/settings.json中配置{ permissions: { defaultMode: plan } }以后只要在该项目目录下运行claude就会默认进 Plan Mode。3.9.4 推荐的完整工作流推荐的使用顺序