用 Claude Code 安全完成既有仓库的第一次改动：导入手册

刚接手一个公司内部仓库的第一天，我就翻车了。

我对 Claude Code 说了句”你先把整个项目读一遍，看到哪里不对就顺手改一下”。半小时后回来一看，23 个文件被改写了。代码本身写得不差。可问题是，连生产环境的部署配置、还有那个谁都不许碰的支付相关文件，都被它”顺手”整理了一遍。改动量太大，连我自己都分不清哪些才是真正需要的改动。最后只能全部丢掉重来。

聪明的 AI 会翻车，不是能力问题。纯粹是在它动手之前，没有任何人告诉它”哪里可以碰”。今天我们就把这第一天，重新打造成一个能回滚、能验证、能善始善终的流程。

本文要点

• 第一次进别人的代码库，先把”哪里能读、哪里绝对不许碰、收尾要跑什么验证命令”写成一页纸。
• 别一上来就让 Claude Code 做大改造。从一次能回滚的小改动（整理测试名、补注释之类）开始。
• 在它汇报”搞定了”之前，必须先跑一条验证命令，并把结果留存下来。
• 删除文件、操作生产数据库、计费逻辑、force push，第一天全部锁死为”需要人来确认”，只有事后确认安全的才逐步自动化。
• 一旦改动量开始膨胀，先别急着改 prompt，第一反应应该是”减少它能碰的文件”。

为什么要在第一天就划定范围

新仓库就像一座没有地图的城市。哪个文件是心脏、哪个一碰就崩，一开始谁都看不出来。

这时候你对 Claude Code 说”通读一遍然后改改”，AI 会出于好心大范围动手。这不能怪 AI，问题出在没给它划范围的人身上。就好比第一天来的兼职，你只丢了一句”店里你看着收拾一下吧”，结果连收银机的设置都被改了——那是下指令的人的锅，对吧。

所以第一件事不是写出多聪明的 prompt，而是画一张地图：能翻的货架、不许开的抽屉、走之前要检查的门窗。光是把这三样写在纸上，第一天的事故就基本消失了。

先定好的三条边界

顺序很重要，从上往下逐条锁定。

要定的东西	具体例子	为什么要先定
能读哪里	src/、docs/、测试文件	让它读全部，它就爱提一堆不相关的改动
绝对不许碰哪里	.env、支付、认证、数据库迁移、生产部署配置	这些一旦弄坏就没法挽回
收尾跑什么验证	npm run build、跑一条测试	为了每次都留下”还能跑”的证据

我把这三条写成一份文件（纯文本也行），放在工作目录的 ONBOARDING.md 里。让 Claude Code 第一个读的也是这份文件。先把地图交给它，再让它上街走，就是这个顺序。

哪些交给 AI，哪些由人来判断

这两件事一旦混在一起就要出事，必须把界线划清楚。

可以放心交给 Claude Code 的活儿

• 把整个仓库粗读一遍，总结出大致结构
• 帮你找”这个功能写在哪个文件里”
• 整理测试名、补注释、补全类型这类能回滚的小改动草稿
• 执行验证命令，读失败日志、帮你初步定位原因

必须由人来判断的活儿

• 是否允许某个改动进入禁区
• 删除文件、操作生产数据库、计费处理、force push
• 大的设计改动是否可以合并的最终拍板
• 改动范围超出预期时，是否要叫停

我的判断标准很简单：“就算改错了也能用 git 回滚的事”交给 AI；“回滚不了的事”由人来按那个按钮。只要守住这一条线，第一天就不会大崩盘。

可直接复制的 prompt 模板

在动第一次改动之前，我会先丢这段过去。诀窍是别让它直接动手写，先让它把计划返回来。

这是一个我第一次接触的既有仓库。请遵守下面的规则。

【可以读】只有 src/ 和 docs/ 以及测试文件
【不许碰】.env / 认证 / 支付 / 数据库迁移 / 生产部署配置
【本次目标】只做一个能回滚的小改进（例如：整理测试名）
【验证】改完后必须跑一次 `npm run build`，并把结果贴出来

现在先不要改任何代码。
请先返回"打算改哪个文件、怎么改"的计划，
并用你自己的话把上面这些规则复述一遍。

返回的计划如果把我方的约束如实复述了，就算合格。如果它打算扩大范围，当场叫停。计划没问题，就接着说”那就照这个来，一直执行到 build 为止”。

把边界用代码固化下来

写在纸上的规则会忘。所以我把导入计划也存成机器能读的形式。下面这段脚本可以直接跑，把里面的内容换成你自己仓库的就行。

#!/usr/bin/env bash
# 把既有仓库的导入计划汇总成一个 JSON
set -euo pipefail

cat > onboarding-plan.json <<'JSON'
{
  "goal": "在既有仓库里安全完成第一次改动",
  "readOnlyCommands": [
    "git status --short",
    "git ls-files | head -50",
    "grep -rn \"TODO\\|FIXME\" src | head -20"
  ],
  "protectedAreas": [".env", "billing", "auth", "db/migrations", "deploy/prod"],
  "firstTask": "做一个能回滚的文档或测试小改进",
  "proofCommand": "npm run build",
  "rollback": "git diff -- path/to/changed-file && git checkout -- path/to/changed-file"
}
JSON

echo "=== 导入计划 ==="
cat onboarding-plan.json

echo ""
echo "=== 当前改动（为空说明还没动）==="
git status --short

这段脚本一点都不花哨。它的价值在于，在动手之前就把”禁区”和”证据命令”固化进了文件里。只要把 protectedAreas 换成你自己仓库里危险的地方，第一天的地图就有了。

再准备一条验证命令会更安心。如果是 Node.js 项目，用下面这个最小检查脚本，就能机械地确认”有没有被弄坏”。

// check.mjs：只确认能不能 build 通过的最小脚本
import { execSync } from "node:child_process";

try {
  // 换成你自己项目的验证命令
  execSync("npm run build", { stdio: "inherit" });
  console.log("验证通过：build 成功。请去 review 改动。");
} catch (e) {
  console.error("验证失败：build 挂了。先别合并，去查原因。");
  process.exit(1);
}

node check.mjs 是绿的就把改动送去 review，是红的就叫停。光有这一条，就能消灭那种”应该能跑吧”凭感觉合并的事故。

三个现场的用法

如果你的情况跟下面某个接近，别重做流程，把名字换成你自己现场的就行。

1. 接手一个内容站 先让它把文章数据放在哪、图片文件夹、build 命令、商品页都读一遍、摸清楚。第一次改动就只做”修一条失效链接”。build 通过了就送去 review。大段正文改写，等确认安全之后再说。

2. SaaS 代码库 把认证、计费、数据库迁移明确写进禁区。第一个任务收窄到”把测试的说明文字改得更好懂”这种程度，由人批准后再往下走。这里一松，“好心的改进”就会钻进支付逻辑，吓你一身冷汗。

3. 古老的遗留仓库 “把整个项目现代化一遍”是禁语，会产生大到读不动的 diff。换成从能用 build 验证的小步开始：修个函数名的拼写错误、整理一下测试名。成功一次，就用同样的套路迈下一步。

每个例子里都有”停手点”。正因为有停手点，工作才不会无限扩散。

失败案例，以及怎么修

老实说，最初那几次我全翻车了。

没写禁区就直接让它改 → 结果 diff 大到没法 review，只能全部丢掉。修法很简单：与其去打磨请求文案，不如先”减少能读的文件”。范围越窄，AI 失控的幅度也越窄。

所有改动全做完了才 build → 根本分不清是哪一步把它弄坏的。现在我每改一个文件就跑一次验证。坏掉的那一刻被记录下来，原因一眼就能看出。

只靠自己肉眼检查 → 忙的那天必然看漏。说白了，“机器能判断的事”就交给机器：build 能不能过、测试结果、链接有没有断。人眼只用在机器抓不到的设计判断上。这么一调，半夜 review 的量一下少了很多。

把这些坑写进文章，是因为只看成功案例，读者察觉不到自己正处在危险状态。哪个请求扩散过头了、哪个验证漏掉了，简短记下来，下次的自己就不会再踩同一个坑。

常见问题

问：第一次改动该选什么？ 答：选”就算改错了也能用 git checkout 回滚的事”。整理测试名、补注释、改错别字这类比较安全。新功能、改配置都不适合放在第一天。

问：禁区要写得多细？ 答：只写”弄坏就没法挽回的地方”就够了。.env、认证、计费、生产部署配置、数据库迁移。最初守住这五个，致命事故基本就能挡住。

问：让 Claude Code 先返回计划这一步能省掉吗？ 答：建议别省。多让它复述一遍计划这点功夫，能在动手前就发现范围跑偏。比起代码写出来之后才发现，这点成本便宜太多了。

问：验证命令只跑 build 够吗？ 答：第一天只跑 build 这一条就够了。熟练之后，再加一条相关的测试。一上来就想跑全量测试，又重又坚持不下去。先小着来，等成功日志攒多了再加。

问：往团队里推时要注意什么？ 答：把边界写进 ONBOARDING.md 这种共享文件里，让所有人用同一张地图。如果每个人心里的禁区都不一样，review 的标准也会跟着晃。

相关文章

思路的底层逻辑，可以参考非工程师如何使用 Claude Code和Claude Code 上手第一步指南。怎么让它记住项目规则，看CLAUDE.md 最佳实践；想把指令写得更到位，整理在进阶 prompt 设计实战里。权限相关的细节，建议同时对照 Anthropic 官方文档。

我自己实测的结果

开头那次”23 个文件事故”之后，我把导入的顺序整个换了。不再去找什么聪明的 prompt，而是先用 onboarding-plan.json 把禁区和验证命令固化下来。光是这一步，支付和生产配置被动到的事故就归零了。

把第一次改动收窄到”整理测试名”的那天，diff 只有 8 行，build 也一次就过。review 连两分钟都用不到。反过来，没划范围就随手让它改的另一天，diff 又膨胀了，又是全部丢掉。差别不在模型聪不聪明，而在进去之前有没有画那张地图。

想把”安全地碰别人代码”这套套路，结合自己团队的真实案例固化下来的朋友，我在研修与咨询里会一起搭出贴合你业务的导入流程。先从今天开始吧——把你自己仓库里的五个禁区列出来。