Claude Code 上手很快，但用久了大多数人栽在同一个地方：不是模型不够聪明，是上下文脏了、配置写歪了。官方的最佳实践文档里，把失败模式总结得很直白，这篇把它们整理成能直接落地的做法。

CLAUDE.md 写什么

判断写进第一句：CLAUDE.md 只写 Claude 自己推断不出来的东西，能靠读代码知道的就删掉。

一个太长、什么都塞的 CLAUDE.md，效果是模型忽略一半指令——重要规则被噪音淹没。判断标准很简单：如果 Claude 没这条指令也已经做对了，就把这条删掉，或者改成 hook。该留的是这几类：跑测试和 lint 的命令、和默认约定不一样的代码风格、分支和 PR 命名这种仓库礼仪、必须的环境变量、项目特有的架构决策、常见坑和非显然行为。

# 本仓库约定

- 测试：`pytest -q`，提交前必须全绿。
- 只在 src/ 改逻辑，不要在 tests/ 里加打印。
- 提交信息用 feat/fix/chore 前缀。
- 数据库迁移别手改，用 `alembic revision` 生成。

反面清单同样重要：不要写"写干净的代码"这种自明的话，不要塞详细 API 文档（给个链接就行），不要写文件逐一说明，不要写频繁变动的信息。如果你反复在一条规则上跟它较劲它还是不改，多半是文件太长、规则被埋了，而不是它不听。

CLAUDE.md 要进 git，让团队一起维护；它还能用 @path 语法 import 其它文件。文件会在使用中持续增值，但前提是定期修剪——每次出问题先回看它，用 /doctor 让它自己提删改建议。

上下文什么时候清

两个高频失败模式，一个解法。

第一个是"大杂烩会话"：从一个任务开始，中间问点无关的，又绕回第一个任务，上下文塞满无关信息。第二个是"反复纠正"：做错了、改、还错、再改，失败的尝试污染了上下文。两者的解法都是 /clear——任务切换就清，纠正两次还不对就清掉重开，把这两次学到的教训写进一条更好的初始提示词里。

还有一条"无限探索"：让 Claude 去"调查"某件事却不设边界，它读几百个文件把上下文填满。解法是收窄范围，或者把探索丢给 subagent，别让它消耗主上下文。

# 让 Claude 列待迁移文件，再逐个 -p 处理，限定工具
for file in $(cat files.txt); do
  claude -p "把 $file 从 React 迁移到 Vue，返回 OK 或 FAIL"     --allowedTools "Edit,Bash(git commit *)"
done

批量迁移或大规模分析，可以用 -p 非交互模式 fan out 到多个并行调用。--allowedTools 把权限限定到最小集合，--verbose 开发期调试、生产关掉。先在两三个文件上试、把 prompt 打磨好，再全量跑。

权限模式怎么选

从 v2.1.283 起，auto 模式是交互终端和 VS Code 的默认起步模式：一个分类器模型在命令执行前审查，拦下范围升级、未知基础设施这类高风险动作，让常规工作免确认往下走。

# 无人值守跑批量修复，auto 模式让分类器把关
claude --permission-mode auto -p "修复所有 lint 错误"

非交互 -p 下，分类器反复拦动作时 auto 会直接中止——因为没有用户可以兜底。所以跑无人值守任务，宁可让它中止，也别换 Manual 模式硬扛。Manual 模式安全但琐碎，第十次批准之后人就开始机械点同意了。要减少打断，用权限白名单预批准 npm run lint、git commit 这类确定安全的工具，或开沙箱做 OS 级隔离。

接外部工具

和外部服务交互，优先走 CLI 工具而不是 API——CLI 是最省上下文的接法。GitHub 就装 gh，Claude 会用；没见过的工具也能用"先用 foo --help 学，再解决 A、B、C"的方式让它自学。

要接 Notion、Figma、数据库这类，用 MCP：

claude mcp add --transport http notion https://mcp.notion.com/mcp

hooks 和 skills 是两个进阶但值得早点用的机制。hooks 是"每次必做、零例外"的动作，比如每次改完文件跑 eslint、禁止写 migrations 目录，它是确定性的，比 CLAUDE.md 的"建议"硬。skills 是放进 .claude/skills/ 的 SKILL.md，给项目专属的领域知识和可复用工作流。

最后一条最容易被跳过：交付前加一道独立复检。让一个 subagent 在全新上下文里只看 diff 和标准去挑毛病，它看不到你当时的推理过程，反而能就结果论结果。注意别让它挑风格，只让它报影响正确性或需求覆盖的 gap，否则会为了凑数而过度工程。