用 Claude Code/Codex 导航大型代码库的实战指南

接手一个大型代码库时，第一目标不是读完所有文件，而是在最短时间内做出一张可行动的地图：系统从哪里启动，哪些目录是生成物，哪些文件关系到收入或权限，哪些边界需要先找负责人确认。

Claude Code 和 Codex 很适合做这类阅读工作，但前提是你要控制上下文。把大文件、长日志、上百条搜索结果全部贴进主对话，并不会自动带来更好的理解。上下文膨胀指的是：对话越来越长，但真正能帮助判断的信息密度越来越低。

本文把我在交接项目、审查旧系统、维护 ClaudeCodeLab 多语言文章时使用的流程，整理成可以直接复制的命令和提示词。工具行为只引用官方文档：Claude Code 的常见工作流、CLI参考、memory，以及 Codex 的非交互模式、AGENTS.md。

先做repo地图

先不要让AI直接“解释整个项目”。你应该先用命令把仓库外形缩小。rg是ripgrep，速度快，也方便排除dist、build、coverage等噪声目录。

git status --short
git rev-parse --show-toplevel
git branch --show-current

rg --files \
  -g '!*node_modules*' \
  -g '!dist' \
  -g '!build' \
  -g '!coverage' \
  -g '!*.lock' \
  | sed 's#^[^/]*/##' \
  | sort \
  | uniq -c \
  | sort -nr \
  | head -40

find . -maxdepth 3 \( \
  -name package.json -o \
  -name pnpm-workspace.yaml -o \
  -name pyproject.toml -o \
  -name go.mod -o \
  -name Cargo.toml -o \
  -name Dockerfile -o \
  -name docker-compose.yml -o \
  -name AGENTS.md -o \
  -name CLAUDE.md \
\) -print

看完结果后，再用只读方式让AI整理地图。Claude Code 官方工作流建议先问宽问题，再逐步缩小范围。Codex 官方文档说明codex exec默认在只读sandbox中运行，因此适合第一次仓库概览。

codex exec "Read only. Summarize the repository map: apps, packages, entrypoints, test commands, generated folders, and files that define project rules. Do not edit files."

Claude Code 可以用-p做非交互输出。官方CLI参考把它称为print mode。

claude -p "
只读。请为这个代码库制作repo地图。
按以下顺序输出：
1. apps、packages、services
2. 运行入口、测试入口、构建入口
3. 生成目录和无需阅读的目录
4. AGENTS.md、CLAUDE.md、README、设计文档的要点
5. 下一步最值得阅读的10个文件，以及每个文件的理由
只提出建议，不要编辑文件或执行修改。
"

分层搜索，而不是乱搜

大型代码库里，文本命中不等于理解。搜索只是生成候选。建议分成五层：结构、业务词、引用、配置、历史。

# 1. 入口候选
rg -n "createServer|listen\(|app\.use|router\.|main\(|bootstrap|hydrateRoot|createRoot" \
  src apps packages server web

# 2. 业务词。按你的产品替换
rg -n "Auth|Billing|Invoice|Notification|Search|FeatureFlag" \
  src apps packages test tests

# 3. 可能要修改模块的引用方
rg -n "AuthService|useAuth|requireAuth|authMiddleware" \
  src apps packages test tests

# 4. 配置和环境变量
rg -n "process\.env|import\.meta\.env|PUBLIC_|DATABASE_URL|JWT|STRIPE|OPENAI|ANTHROPIC" \
  . -g '!node_modules' -g '!dist' -g '!build'

# 5. 历史：为什么现在是这种设计
git log --oneline --decorate --date=short --max-count=30 -- src/auth packages/auth

不要把100条结果都丢给AI。先看命中形状，再给它一小组候选，并要求分类。

你是代码库导航审查员。
请把下面的rg命中结果分成：实现入口、调用方、配置、测试、噪声。
每类最多保留5个下一步应该阅读的文件。
每个文件给出一个具体理由。
不确定时写“需要再次搜索”，不要猜。

做一个轻量依赖图

在引入完整依赖分析工具之前，一个小Node脚本就能提供足够的线索。它不是TypeScript编译器，只追踪本地相对import，但足以帮你判断“改这个文件会影响哪些地方”。

#!/usr/bin/env node
import { execFileSync } from "node:child_process";
import { readFileSync } from "node:fs";
import path from "node:path";

const target = process.argv[2]?.replace(/\\/g, "/");
if (!target) {
  console.error("Usage: node scripts/dependency-map.mjs src/path/to/file.ts");
  process.exit(1);
}

const tracked = execFileSync("git", ["ls-files"], { encoding: "utf8" })
  .split(/\r?\n/)
  .filter(Boolean)
  .map((file) => file.replace(/\\/g, "/"));

const trackedSet = new Set(tracked);
const sourceFiles = tracked.filter((file) => /\.(mjs|cjs|js|jsx|ts|tsx)$/.test(file));
const importPattern =
  /(?:from\s+["']([^"']+)["']|import\s*\(\s*["']([^"']+)["']\s*\)|require\s*\(\s*["']([^"']+)["']\s*\))/g;

function resolveLocalImport(specifier, fromFile) {
  if (!specifier.startsWith(".")) return null;
  const base = path.normalize(path.join(path.dirname(fromFile), specifier)).replace(/\\/g, "/");
  const candidates = [
    base,
    `${base}.ts`,
    `${base}.tsx`,
    `${base}.js`,
    `${base}.jsx`,
    `${base}/index.ts`,
    `${base}/index.tsx`,
    `${base}/index.js`,
  ];
  return candidates.find((candidate) => trackedSet.has(candidate)) ?? base;
}

const incoming = [];
for (const file of sourceFiles) {
  const source = readFileSync(file, "utf8");
  for (const match of source.matchAll(importPattern)) {
    const resolved = resolveLocalImport(match[1] || match[2] || match[3], file);
    if (resolved && (resolved === target || resolved.endsWith(`/${path.basename(target)}`))) {
      incoming.push(file);
    }
  }
}

console.log(`Target: ${target}`);
console.log("Direct importers:");
for (const file of incoming.sort()) console.log(`- ${file}`);

保存并运行：

mkdir -p scripts
$EDITOR scripts/dependency-map.mjs
node scripts/dependency-map.mjs src/services/AuthService.ts

然后把结果交给AI做风险评估。

根据这些Direct importers，评估修改AuthService.ts的影响范围。
分类使用 high / medium / low。
high表示认证、计费、授权、持久化或公开API行为。
每一类都列出编辑前应该阅读的测试和配置文件。

从入口追踪执行路径

文件列表无法说明运行时行为。后端要追踪request、middleware、route、controller、service、repository、database。前端要追踪route、loader、state、API client、component、analytics。

rg -n "middleware|loader|action|controller|handler|route|repository|service" \
  src apps packages \
  -g '*.ts' -g '*.tsx' -g '*.js' -g '*.jsx'

rg -n "fetch\(|axios|graphql|trpc|prisma|drizzle|sequelize|typeorm" \
  src apps packages \
  -g '*.ts' -g '*.tsx' -g '*.js' -g '*.jsx'

要求AI输出表格，而不是泛泛总结。

视角	好输出	危险输出
入口	POST /login -> auth route -> AuthService.login	“auth很重要”
状态	Cookie、session、DB、cache、queue变化	没有状态变化
失败	错误响应、日志、审计事件、重试	只有happy path
测试	现有测试文件和缺失用例	只说“加测试”

请从入口到持久化追踪login流程。
输出表格，列为：顺序、文件、函数/类、状态变化、失败行为、应阅读的测试。
不要用猜测填空；未知步骤请写下一步应检查的文件。

画出所有权和风险边界

大型仓库里，第一个问题不是“能不能跑”，而是“这是谁的边界”。边界可能是团队、数据、发布、合规，也可能是收入路径。

find . -maxdepth 4 \( \
  -name CODEOWNERS -o \
  -name OWNERS -o \
  -name README.md -o \
  -name AGENTS.md -o \
  -name CLAUDE.md \
\) -print

rg -n "owner|maintainer|deprecated|legacy|do not edit|generated|migration|rollback|release" \
  . -g '!node_modules' -g '!dist' -g '!build'

Codex官方说明会读取AGENTS.md，所以仓库规则值得写在那里。Claude Code可以用CLAUDE.md和memory缩短后续会话。模板可以参考CLAUDE.md最佳实践。

## Codebase map

### Entry points
- Web: apps/web/src/main.tsx
- API: services/api/src/server.ts
- Jobs: services/jobs/src/index.ts

### Ownership boundaries
- services/payments: owned by payments team; never change schema without migration review.
- packages/ui: shared design system; visual regression test required.
- legacy/: read-only unless the issue is production severity.

### High-risk files
- services/api/src/auth/AuthService.ts: login, session rotation, audit log.
- packages/db/schema.ts: migrations affect API and jobs.
- apps/web/src/routes/checkout.tsx: revenue path and analytics.

### Handoff notes
- Always start with rg search, then read top files.
- Prefer small diffs with tests.
- Do not paste large logs into the main conversation; summarize first.

使用只读探索提示词

第一次探索时，不要把AI推向“马上修”。先让它输出地图、假设和未知点。

请用只读模式调查。不要编辑文件、添加依赖、格式化代码或运行测试。

目标：
理解[功能名]的实现范围和修改风险。

输出：
1. 入口文件
2. 核心数据模型
3. 直接和间接依赖
4. 所有权边界
5. high / medium / low风险图
6. 下一步应检查的文件
7. 尚未确认的假设

规则：
猜测必须标为“假设”。
必须包含文件名和证据。
不要引用大段文件全文。

Claude Code的subagents适合把大量文件阅读放到主对话之外。官方文档说明subagent会在自己的上下文中工作，只返回总结。Codex的subagents也说明可用于并行代码库探索。范围要小，因为subagent同样会消耗token。更多模式见Subagent Patterns。

启动3个只读subagent：
1. API入口和认证边界
2. DB schema和migration边界
3. UI路由和收入路径

每个subagent最多阅读8个文件，只返回最终发现。
结束后由父agent合并重复、冲突和未知点。

避免上下文膨胀

最简单的规则是：证据和判断分开。完整文件、长日志、100条搜索命中都太重。先过滤，再让AI判断。

OpenAI的compaction是API功能，但思路同样适用于人和agent协作：保留必要摘要，丢掉过期细节。

请把目前调查压缩成300字以内，方便下一位继续。
保留：
- 已确认入口
- 高风险文件
- 不可跨越的边界
- 未确认假设
- 下一条要运行的命令

丢弃：
- 已被否定的假设
- 长日志
- 不需要阅读的生成文件

交接笔记对开发和内容运营都重要。多语言文章要记录拥有的locale文件；应用开发要记录追踪到哪个入口；bug调查要记录哪些假设已经失败。测试可参考Claude Code测试策略，权限可参考approval和sandbox指南。

三个具体用例

第一，SaaS项目交接。第一天只看登录、计费、管理后台、通知。先找AuthService和BillingService的引用，再从checkout route追到数据库。不要编辑。输出应该是风险图和阅读顺序。

第二，遗留系统迁移。先搜索legacy、deprecated、migration，再让AI写替代方案。更好的问题是“哪些兼容性会被破坏”。数据库迁移、公开API、批处理、cron都要特别谨慎。

第三，像ClaudeCodeLab这样的内容和变现网站。文章、CTA组件、内部链接、商品页、翻译文件分散在不同目录。按slug划分所有权，让AI只拥有一个slug，其他文章只用于链接确认，这样并行编辑更安全。

常见失败模式

• 只相信README。真实入口经常和旧文档不一致。
• 把搜索命中当作执行路径。命中只是候选，不是证据。
• 在所有权不清楚前让AI编辑。代码能跑，也可能过不了review。
• 把生成目录、lockfile、coverage、dist塞进对话。
• 给subagent过大的范围，最后返回的总结仍然很重。
• 只说“安全修复”，却没有定义high / medium / low风险。

团队和收益导向CTA

大型代码库导航也会影响收入路径。checkout、lead form、付费内容、analytics、广告位都在风险边界之后。编辑前先做repo地图，能减少返工。

如果团队要导入Claude Code或Codex，建议先准备repo地图模板、AGENTS.md/CLAUDE.md、review规则和只读探索提示词。个人可以从免费cheat sheet开始。需要围绕真实仓库做团队培训时，可以看Claude Code培训与咨询。

实际验证笔记

我按这个流程做项目交接时，后续实现提示比直接贴大文件稳定得多。最有用的产物是repo地图、分类后的rg结果、小依赖表、high / medium / low风险图。跳过这些步骤时，生成目录、旧测试、别的团队模块会进入对话，主上下文很快变吵。发布前我重新检查了命令、提示词和Node脚本，确保它们至少以可复制的形式呈现，并且JavaScript语法结构完整。