SOTA Sync
返回 FEED
OTHER2026-05-30

Claude Code 新手 6 坑：先管住它，再让它写代码

刚装完 Claude Code 别急着让它写代码。

先做开工检查，再按 6 个坑把项目记忆、只读扫描、工具箱、隔离目录、验收标准和会话边界补齐。

Chris Wang 给出的新手攻略，核心一句话：第一次用 Claude Code，不要先提需求，先做 6 件事。

为什么"先别提需求"

你有没有遇到过这种情况：

刚装好 Claude Code，心里有点兴奋，第一句话就打进去：

"帮我把登录页面改一下。"

它开始读文件、改代码、跑命令，终端刷得飞快。你看着很爽，觉得这钱没白花。

结果半小时以后，问题来了：

  • 它改了七八个文件
  • 你让它改回来一点，它又绕到另一个方向
  • 你再纠正一次，diff 更大了
  • 最后你盯着屏幕，心里只剩一句话："这东西刚才明明挺聪明，怎么越改越乱？"

这不是 Claude Code 的问题。是你一上来就把它当成老员工用了。

它其实更像一个刚来第一天的新同事：

  • 人很聪明
  • 手也快
  • 但你没给项目地图
  • 不知道哪些地方不能碰
  • 也不知道什么叫"做完"

这种情况下，它越勤快，你越容易收拾现场。

开工检查

很多人一进项目就开 Claude Code，这是第一个小坑。

你要先确认一件事：当前项目是不是干净的。因为如果你自己已经改了一半，Claude Code 又进来改另一半，后面出了问题，你都分不清是谁改坏的。

cd /你的项目路径
git status --short
  • 如果什么都没有输出 → 工作区干净，可以继续
  • 如果看到 M / ?? 标记 → 先停一下

M src/login.ts 表示这个文件被你改了一半。?? notes.md 是你刚创的笔记。带着这些状态进 Claude Code，等于让新同事在一个混乱的房间里开始工作。

第 1 坑：没有 CLAUDE.md → 建项目规矩表

CLAUDE.md 是项目级的"家规"。Claude Code 启动时会自动加载它，里面的内容会进入 context。

CLAUDE.md 应该写什么：

  • 代码规范（命名、缩进、import 顺序）
  • 不要碰的东西（某些目录、某些文件、某些 API）
  • 常用命令（怎么跑测试、怎么部署、怎么 build）
  • 项目专有概念（"Order 模型 = 用户订单"）

举个具体例子：

# 项目规矩

## 代码
- TypeScript 严格模式
- 测试用 vitest，单文件单测
- 命名：camelCase 变量，PascalCase 类
- 禁止修改 src/generated/ 目录（自动生成）

## 不要碰
- 不要跑 `npm publish`
- 不要碰 prisma/schema.prisma（要改先开 PR）
- 不要动 GitHub Actions workflows

## 命令
- 测试：`pnpm test`
- 跑开发：`pnpm dev`
- Lint：`pnpm lint`
- 部署：先开 PR，CI 通过后自动部署到 staging

CLAUDE.md 不是文档——它是给 Claude Code 的 onboarding 文档。新人入职看的那份手册。

第 2 坑：一上来就改代码 → 先只读扫描

新同事入职第一天应该干嘛？先读代码、熟悉结构，不要动手改。

Claude Code 也一样。给它一个项目，先让它只读扫描：

"请先扫一遍 src/ 目录，告诉我这个项目的模块结构、入口在哪、核心数据模型是什么。不要改任何文件。"

这一步的作用是：

  • 让 Claude Code 形成对项目的整体认知
  • 你可以验证它对项目的理解对不对
  • 后续改代码时，它改的姿势才合理

如果跳过这步直接让 Claude Code 改代码，它会基于对"普通项目"的通用假设来改——结果就是"我让你改登录页，你顺手重构了整个 auth 模块"。

第 3 坑：工具箱没配齐 → 检查 rg / fd / jq

Claude Code 默认调一些 shell 工具（rg、fd、jq）。如果这些没装，它的代码搜索和文件处理会变慢甚至失败。

简单检查：

which rg fd jq

如果哪个 missing，装上：

# macOS
brew install ripgrep fd jq

# Ubuntu
sudo apt install ripgrep fd-find jq

为什么这三件重要：

  • rg（ripgrep）：代码搜索。Claude Code 用它找函数定义、引用、改动点。比 grep 快 10 倍
  • fd：文件查找。比 find 友好，支持正则
  • jq：JSON 处理。Claude Code 解析 package.json、tsconfig.json 必备

没这三件工具的 Claude Code 是"瘸腿的"——能用，但每一步都慢。

第 4 坑：直接在主分支上试 → 开 git worktree

新同事的第一周不应该有 push 主分支的权限。

Claude Code 也一样。任何改代码的需求，先在隔离分支做：

git worktree add ../project-feature-x -b feature/x
cd ../project-feature-x

然后在那个 worktree 里开 Claude Code 改代码。

好处：

  • 主分支永远是干净的
  • 改坏了随时扔掉 worktree，不影响主线
  • 多个 worktree 可以并行做不同 feature，每个都开独立 Claude Code 会话

不用 worktree 的代价是：改到一半发现 Claude Code 把主分支搞乱了，回滚要 git reset --hard——这种惊吓一次就够。

第 5 坑：不写验收标准 → 带着尺子提需求

"把登录页面改一下"——这种需求没验收标准。

什么算"改好了"？你说"页面好看"——什么是好看？你说"逻辑对"——什么逻辑？

正确姿势：提需求时带上验收标准。

差的需求：

"把登录页面改一下。"

好的需求：

"把登录页面的密码输入框改成 toggle 可见/隐藏。验收标准：

  1. 点击眼睛图标切换 password/text
  2. 切换后焦点保持在输入框
  3. 移动端也工作
  4. 现有表单提交逻辑不变
  5. 加一个测试覆盖 toggle 行为"

验收标准 = 你给新同事的"做完定义"。没它，Claude Code 会按自己的理解做——大概率不是你想要的。

第 6 坑：所有事塞进一个会话 → 任务结束就 /clear

这是最反直觉的一个坑。

Claude Code 的会话越长，context window 越满，行为越漂移：

  • 早期约束失效（"不要改 X 文件"被忘）
  • 旧上下文污染新任务（"上次那个 bug 跟这次啥关系？"）
  • 模型开始"自作主张"（"我看你这个文件也是同样问题，一并改了吧"）

正确姿势：每个新任务新会话。

# 任务 1 结束
/clear  # 或者直接开新终端

# 任务 2 开始
cd ../project-feature-y
claude  # 新会话

代价是 Claude Code 每次都要重新加载项目。但 CLAUDE.md 是自动加载的，所以项目记忆不丢。

长会话是 Claude Code 最大的反模式。一个会话里塞 10 个任务 = 上下文污染 + 早期约束失效 + 模型行为漂移。

6 坑的总览

开工检查：打开项目 → 看 git 状态
第 1 坑：没有 CLAUDE.md → 建项目规矩表
第 2 坑：一上来就改代码 → 先只读扫描
第 3 坑：工具箱没配齐 → 检查 rg / fd / jq
第 4 坑：直接在主分支上试 → 开 git worktree
第 5 坑：不写验收标准 → 带着尺子提需求
第 6 坑：所有事塞进一个会话 → 任务结束就 /clear

这 6 件事做完，30 分钟搞定。从此 Claude Code 是个"按规矩做"的新同事。

适合谁 vs 不适合谁

适合

  • 第一次用 Claude Code——必读
  • 用 Claude Code 改过代码但经常翻车的人
  • 多人协作的复杂项目——CLAUDE.md 让团队所有 Claude Code 行为一致
  • 长期维护的项目——工作流稳定比短期效率重要

不适合

  • 一次性脚本（写个正则替换、写个 5 行的 helper）→ Claude Code 大材小用
  • 已经在用 Cursor/Cline 熟练 —— 这两个 IDE 的护栏机制不一样，CLAUDE.md 不适用
  • 对项目结构不熟 —— 你让 Claude Code 写 CLAUDE.md 之前，得自己先知道项目结构

Chris Wang 没说的两件事

1. 6 坑彼此不独立。第 1 坑（CLAUDE.md）跟第 5 坑（验收标准）有重叠——验收标准也可以写在 CLAUDE.md 里。第 4 坑（worktree）跟第 6 坑（/clear）有协同——worktree 是空间隔离，/clear 是时间隔离。这 6 件事不是清单，是一套互相支撑的体系。单独做第 5 坑不带第 1 坑，效果会打折扣。

2. CLAUDE.md 会膨胀。项目用得越久，CLAUDE.md 越长。太长会被截断——CLAUDE.md 全部进入 context，超长的 CLAUDE.md 会挤占任务空间。Chris Wang 没说"CLAUDE.md 应该多长"——实操经验是 100-300 行最佳，超过 500 行需要分层（核心规矩在 CLAUDE.md，详细规则在 references/）。

结论

Claude Code 的护栏不是"配置"——是一套项目级的工作流约定。CLAUDE.md、只读扫描、工具箱、worktree、验收标准、/clear，6 件事一起形成"Claude Code 在这个项目里的边界"。

SOTA Sync 的判断：Claude Code 的新手门槛不是"会不会用 prompt"，是"会不会给项目装护栏"。30 分钟的护栏设置能把 Claude Code 的可用度从 30% 拉到 80%。这 30 分钟的 ROI 是任何 AI 工具里最高的。

继续阅读