Claude Code 既有代码库地图：编辑前45分钟安全流程

把Claude Code放进既有代码库时，第一份成果不应该是代码差异，而应该是一张地图。这张repo map要说明应用从哪里启动，哪些目录最重要，今天哪些地方不能碰，改完后用什么命令证明没有破坏，以及下一位维护者需要知道什么。没有这张地图，AI很容易从一个小请求扩散到大范围清理、顺手重构或难以审查的改动。

本文提供一个适合初学者的45分钟流程，目标是在编辑前先读懂仓库。官方Claude Code overview说明，Claude Code可以读取代码库、编辑文件并运行命令。能力越强，边界越要提前写清楚。

相关主题可以继续阅读既有代码库的第一组提示词、Claude Code权限设置指南和CLAUDE.md starter template。

45分钟repo map

建议分配为：25分钟只读调查，10分钟写地图，5分钟选择一个安全的第一任务，5分钟做计划审查。不要追求完美架构文档。你需要的是能帮助你做出小而可回滚改动的工作地图。

flowchart TD
  A["只读盘点"] --> B["找到入口"]
  B --> C["区分安全区域和风险区域"]
  C --> D["选择一个首个改动"]
  D --> E["固定验证命令"]
  E --> F["写入 repo-map.md"]

入口是应用开始运行的地方，例如路由文件、API handler、server bootstrap、CLI命令、定时任务或内容加载器。风险区域是小错误也会影响信任或收入的地方，例如认证、计费、删除、生产配置、secret、部署脚本、分析和广告标签。验证命令是你用来证明“这次改动没有破坏目标流程”的证据。

Step 1: 只读盘点

先运行不会修改仓库的命令。Windows PowerShell可以直接使用下面这一组。

git status --short
Get-ChildItem -Force | Select-Object Name, Mode, Length
Get-ChildItem -Recurse -File -Include package.json,astro.config.*,next.config.*,vite.config.*,README*,CLAUDE.md,AGENTS.md | Select-Object -ExpandProperty FullName
rg --files | Select-Object -First 120

观察技术栈、文档、生成目录、缓存目录和未提交改动。如果工作区已经是dirty状态，先确认这些改动是谁做的，再让Claude Code编辑文件。这能避免覆盖他人工作。

给Claude Code的第一条提示词要明确保持只读。

Read this repository as an existing codebase. Do not edit files yet.

Goal:
- Create a first repo map in 45 minutes
- Pick exactly one safe starter task
- Identify areas that should not be touched today

Return:
1. Up to 8 important directories
2. Up to 5 runtime or content entry points
3. Risky areas with reasons
4. Three safe starter task candidates
5. Candidate proof commands

If something is uncertain, write "unverified" instead of guessing.

“Do not edit files yet”很重要。它把会话固定在调查模式，直到你拥有可审查的计划。

Step 2: 写repo-map.md

不要把调查结果只留在聊天窗口里。写一个短小的repo-map.md，让下一次会话可以复用。官方memory文档解释了CLAUDE.md可以保存项目指令，但第一次调查不必全部塞进去。先用repo map承接，稳定的规则再迁移到CLAUDE.md。

# repo-map.md

## Purpose
- First working map for using Claude Code safely in this repository

## Entry points
| Type | File | Role | Proof |
| --- | --- | --- | --- |
| Web | site/src/pages/index.astro | Home page | npm run build |
| Content | site/src/content/blog | Article source | Open article URL |

## Safe candidates
- docs/
- site/src/content/blog/
- Small display copy

## Do not touch today
- .env and secrets
- Auth, billing, deletion flows
- Deploy scripts
- Generated dist and cache folders

## First safe task
- Improve one article CTA
- Change one file only
- Verify with build and preview

## Remaining risks
- Production data flow is unverified
- External service integrations need a separate pass

这不是完整架构图，而是第一次有用改动前的护栏。

Step 3: 用权限加固地图

提示词有帮助，但不是强制边界。官方permissions文档介绍了allow、ask、deny规则。第一次进入既有仓库时，建议允许读取和安全检查，构建或编辑前询问，push、破坏性命令和secret读取直接拒绝。

{
  "permissions": {
    "allow": [
      "Bash(git status *)",
      "Bash(git diff *)",
      "Bash(rg *)",
      "Bash(npm run test *)",
      "Read"
    ],
    "ask": [
      "Bash(npm run build *)",
      "Edit(site/src/content/blog/**)"
    ],
    "deny": [
      "Bash(git push *)",
      "Bash(rm -rf *)",
      "Read(.env)",
      "Read(**/.env)",
      "Edit(scripts/deploy*)"
    ]
  }
}

这段JSON只是起点。你的项目可能没有npm run test，可编辑路径也可能不同。关键是先决定拒绝什么，再扩大允许范围。

Step 4: 选择第一个安全改动

有了地图以后，选择小、可回滚、容易验证的任务。三个具体场景很适合初次实践。

场景一是内容CTA修正。例如让热门文章自然连接到产品列表和培训咨询。通常只改一个内容文件，可以通过build和预览验证。

场景二是在README或CLAUDE.md里补充验证命令。把已经确认的build、test、lint、preview命令写清楚，可以减少以后每次会话的搜索成本，而且不改变应用行为。

场景三是单个页面的文案或日期格式调整。把改动限制在一到两个文件，然后用测试、截图或本地预览确认。认证、计费、权限和删除流程不要放进第一个任务。

Using repo-map.md, implement only the first safe task.

Target:
- site/src/content/blog/example.mdx

Requirements:
- Make the final CTA more natural
- Keep internal links to /products/ and /training/
- Do not change pubDate, category, tags, author, or heroImage
- Change this one file only

After finishing, report:
1. Changed files
2. Why they changed
3. Proof commands run
4. Remaining risks

这个提示词把宽泛请求变成了可以审查的小补丁。

Step 5: 检查地图本身

repo map是文本，但最低限度的标题可以用脚本检查。保存为check-repo-map.js后，对repo-map.md运行。

const fs = require("node:fs");

const file = process.argv[2] || "repo-map.md";
const text = fs.readFileSync(file, "utf8");
const required = ["Entry points", "Safe candidates", "Do not touch today", "First safe task", "Remaining risks"];
const missing = required.filter((heading) => !text.includes(heading));

if (missing.length > 0) {
  console.error(`Missing repo-map sections: ${missing.join(", ")}`);
  process.exit(1);
}

console.log(`OK: ${file} has the minimum repo-map sections.`);

node check-repo-map.js repo-map.md

脚本很简单，但它迫使每次会话留下同样格式的交接记录。

常见失败

失败一是请求过宽，例如“重构整个应用”或“提高质量”。解决方法是在编辑前指定只读调查、最大文件数、今天不碰的区域和验证命令。

失败二是把生成物混进地图。dist、.astro、.next、coverage、node_modules会让仓库看起来很大，却不一定有助于理解。除非它们本身就是需要检查的部署产物，否则第一次地图应排除。

失败三是低估外部服务。邮件发送、支付webhook、广告标签、分析和CRM集成代码量可能很小，但业务影响很大。先读，另开任务再改。

失败四是build通过后不看页面。build成功也可能出现移动端布局、代码块、CTA或内部链接问题。内容站点要打开预览，检查正文、代码块、/products/和/training/。

审查清单

视角	检查	危险信号
差异	只改了请求的文件	大量顺手格式化
入口	知道改动如何被加载	改了不会被读取的文件
风险	未碰认证、计费、删除、生产配置	secret或部署脚本被修改
证据	有命令或手动检查	只有“应该没问题”
转化	CTA和内部链接贴合文章	产品链接像硬塞进去
交接	残余风险被写下	下一次会话重复调查

这个清单不是为了不信任Claude Code，而是为了让工作可重复。在既有代码库中，“没有改什么”也是成果物的一部分。

把收入路径也画进地图

对ClaudeCodeLab这样的内容站点来说，代码地图也要包含变现路径。哪些文章带来搜索流量？读者在哪里看到免费下载、模板产品或咨询页？需要现成模板时可以看产品库。需要团队导入、权限设计和内容运营支持时，可以看Claude Code培训咨询。

当收入路径进入地图，一个小CTA改动就不只是文案修改。你还会检查内部链接、商品页、表单、分析和广告位置。代码正确并不自动带来收入，读者必须有清楚的下一步。

还有一个实务技巧：不要把 repo map 只留在聊天记录里。聊天适合探索，但下一次会话不一定能完整继承上下文。可以先把它保存成 tmp/repo-map-YYYY-MM-DD.md，作为本次改动的临时工作地图，而不是马上变成永久文档。这样既能复用调查结果，又不会给团队增加长期维护负担。

如果多人协作，在地图最后留下三个“下次先问的问题”。例如“这个表单提交后由哪个服务发邮件”“价格文案以哪个文件为准”“生产部署是手动还是自动”。下一次让 Claude Code 从这三个问题开始，通常比重新扫描全仓库更快，也更不容易误改收入路径。

还可以给地图加一个小型 use case 区域，把最适合第一次修改的任务列出来。比如修改文档 CTA、补充 README 命令、修正一个日期格式、添加一个只读检查脚本。这些任务的共同点是影响范围小、容易验证、失败后能快速回退。相反，认证、支付、删除、部署、邮件发送和广告脚本应该标成 pitfall 或高风险区域，除非已经有专门的验证步骤。

团队里还可以把 repo map 当作轻量 onboarding 材料。新人或外部顾问加入时，不需要先读完整仓库，只要先看入口、危险区域、验证命令和收入路径，就能知道哪些文件可以安全触碰。这个做法尤其适合 AI 协作，因为 Claude Code 可以在每次修改后更新“本次确认过的事实”和“还没有确认的假设”。把事实和假设分开写，会比长篇架构说明更实用。

总结

使用Claude Code处理既有代码库时，前45分钟用于建图，而不是重写。盘点仓库、识别入口、标出风险区域、选择一个安全任务、固定验证命令，并留下repo-map.md。之后再做一到两个文件的小改动，审查会轻松很多。