1. 接手陌生 TypeScript Monorepo 时先别急着改代码拿到一个完全陌生的 TypeScript Monorepo最容易犯的错不是不会写代码而是还没看懂就开始动手。Claude Code 这类工具会把修改速度放大同时也会把误判的代价一起放大找错入口、漏掉校验、只改前端不改契约、测试只跑一条、顺手重构了无关文件。这些问题单独看都不复杂叠在一起就会让第一个需求变成一次高成本回滚。我试过在一个 Web 前端 API 服务 shared 契约 自动化测试的典型 Monorepo 里用 Claude Code 从零接手并交付第一个真实需求。整个过程可以拆成一条可复查的工程闭环先锁住工作区再建立项目地图先追完整调用链再把一句需求翻译成验收条件先让它给出计划再做最小改动最后用测试、静态检查和 Git diff 形成交付证据。这篇文章不把 Claude Code 当成“自动补全升级版”而是把它放进真实的软件工程流程里。具体技术栈并不重要真正可复用的是“如何读、如何定位、如何限制改动面、如何验证”的方法。适合谁适合刚加入新团队、需要快速接管陌生仓库的前后端工程师也适合想把 AI 编程工具纳入规范流程的技术负责人。核心检索词先明确Claude Code 接手陌生代码库本质是用 CLAUDE.md 建立仓库地图、用 Git 历史定位改动边界、用可复查的验证闭环完成第一个真实需求。下面按步骤展开。2. 用 CLAUDE.md 和目录结构建立仓库地图2.1 先锁住工作区不要让第一次探索污染仓库陌生仓库的第一条纪律是在你还不知道项目如何启动、哪些文件由生成器维护、团队有没有特殊约定之前先不要修改。Claude Code 能直接读取文件、搜索代码、执行命令并修改工程真正成熟的用法是先把这些能力放进一个可控边界。先看 Git 状态而不是先问“这个项目做什么”git status --short git branch --show-current git log -5 --oneline --decorate这三条命令回答三个问题当前在哪个分支工作区有没有未提交的改动最近提交的节奏和命名习惯是什么。只要工作区不是干净的就应该把已有变更当成“保护区”不要让 AI 自动格式化、批量重命名或移动文件。检查项为什么必须先看看到异常时怎么处理git status区分“仓库原状”和“本次变更”记录现有改动不覆盖、不格式化当前分支避免在 main / release 上直接改切到独立功能分支后再实现最近提交理解团队提交粒度与命名习惯保持相近粒度不把多个主题塞进一次改动锁文件判断 npm / pnpm / yarn 与依赖版本只使用仓库既有包管理器CI 配置知道真正的验收命令是什么优先复用 CI 中已验证过的命令探索阶段优先使用 Plan 模式。对于真正陌生的仓库最适合的起手式不是直接给“修复这个需求”而是先让 Claude Code 进入只分析、不修改的阶段claude --permission-mode plan注意陌生仓库不建议一上来使用跳过权限提示的模式。越是不了解仓库越需要保留“每一步要不要执行”的人工闸门。2.2 第一遍只读目录用三层阅读法建立项目地图很多人接手陌生项目会直接进入src/然后从第一个看得懂的文件开始读。这个方法在小项目里勉强可用在 Monorepo 或有代码生成的仓库里非常容易迷路。更稳的方式是按“骨架 → 入口 → 调用链”分三层读。第一层先看项目骨架不看业务细节只判断项目形态和工程规则ls -la find . -maxdepth 2 \( -name package.json -o -name pnpm-workspace.yaml \ -o -name turbo.json -o -name Dockerfile -o -name docker-compose.yml \ -o -name CLAUDE.md -o -name README.md \) -print假设根目录最后呈现出下面这种形态repo/ ├─ apps/ │ ├─ web/ # React 前端 │ └─ api/ # Express API ├─ packages/ │ └─ shared/ # DTO / 类型 / 校验契约 ├─ tests/ # 跨模块或端到端测试 ├─ package.json ├─ pnpm-workspace.yaml ├─ turbo.json └─ README.md这时你已经知道一个非常重要的事实需求如果同时涉及“前端筛选”和“接口参数”它很可能不是改一个页面就结束而是会穿过 shared 契约、API 路由、业务服务和测试。目录本身已经在告诉你改动边界。第二层找业务入口先问“用户动作从哪里进入系统”而不是先问“哪个 service 名字最像”rg -n OrderList|/orders|listOrders|orderService apps packages tests rg -n source|订单来源 apps/web apps/api packages/shared tests第三层沿真实调用链向下追。找到入口之后不要停在“搜索到了几个同名字符串”。真正需要建立的是证据链页面如何拼查询参数共享层怎么定义合法取值API 如何解析参数Service 如何构造过滤条件ORM / Repository 最终查什么已有测试覆盖到哪里。2.3 给 Claude Code 一个明确的追链任务不要用“文件名相似”代替“调用关系确认”。真正的改动点必须能从入口沿引用或调用关系一路追到执行位置。可以给 Claude Code 这样一段提示词围绕“订单列表查询”这条业务链只做分析不改文件。 请从前端页面开始追到 API Client、共享类型/校验、后端路由、业务 Service、数据库查询和相关测试。 输出格式 - 文件路径 - 这个文件在链路中的职责 - 它调用/依赖的下一个位置 - 与“订单来源 source”筛选是否直接相关 - 如果要实现筛选是否需要改这里以及理由 最后给出一条从 UI 到数据库再到测试的完整调用链。这样的提示词比“帮我看看订单列表怎么实现的”强得多因为它要求输出“路径 职责 下一跳 是否相关 理由”。你拿到的不是概述而是一张可复查的改动地图。3. 把 API 通道改到 TaoToken 的可复制配置3.1 为什么要在接手阶段先打通 API 通道接手陌生仓库时Claude Code 需要频繁读取文件、搜索代码、执行命令。如果 API 通道不稳定整个探索过程会不断被打断。把通道统一改到 TaoToken可以让后续的追链、计划、实现、复核都跑在同一条可复查的链路上。TaoToken 的官网入口是 https://taotoken.net/?utm_sourcetaotoken_aicg_blog_endutm_mediumcsdnutm_campaignrewriteutm_content API 地址是 https://taotoken.net/api 。下面给出可复制的配置片段路径与原文一致。3.2 Claude Code 的 settings.json 配置Claude Code 的项目级配置通常放在.claude/settings.json用户级配置放在~/.claude/settings.json。把 API 通道改到 TaoToken 时需要同时写全三件套Base URL、Key、Model ID。{ env: { ANTHROPIC_BASE_URL: https://taotoken.net/api, ANTHROPIC_AUTH_TOKEN: sk-你的TaoTokenKey, ANTHROPIC_MODEL: claude-sonnet-4-20250514 } }如果你用的是 Claude Code 的 CLI 启动方式也可以在项目根目录的.claude/settings.json里写同样的内容。注意ANTHROPIC_BASE_URL只写到/api不要带多余的路径后缀。3.3 Codex 的 auth.json 配置如果你同时用 Codex配置放在~/.codex/auth.json。同样要写全三件套{ base_url: https://taotoken.net/api, api_key: sk-你的TaoTokenKey, model: claude-sonnet-4-20250514 }3.4 Cline MCP 的配置Cline 通过 MCP 接入时配置通常写在cline_mcp_settings.json里。Base URL、Key、Model ID 三件套一个都不能少{ mcpServers: { taotoken: { command: npx, args: [-y, taotoken/mcp-server], env: { TAOTOKEN_BASE_URL: https://taotoken.net/api, TAOTOKEN_API_KEY: sk-你的TaoTokenKey, TAOTOKEN_MODEL: claude-sonnet-4-20250514 } } } }3.5 CC Switch 的配置如果你用 CC Switch 管理多个通道可以在它的配置里新增一个 TaoToken 条目Base URL 填https://taotoken.net/apiKey 填你的 TaoToken KeyModel ID 填你要用的模型。切换时确认三件套都指向 TaoToken避免出现“Key 换了但 Base URL 还是旧的”这种低级错误。配置完成后先不要急着跑需求先用一条最小请求验证通道是否打通。4. 验证请求与跑通第一个真实需求4.1 用最小请求验证通道配置写完后先跑一条最小请求确认通道可用claude --permission-mode plan -p 只回复 OK不要做任何其他操作如果返回OK说明 Base URL、Key、Model ID 三件套都生效了。如果报错先看第 5 节的排查清单。4.2 把一句需求翻译成可验收条件“订单列表增加订单来源筛选”看起来很清楚真正落到代码里仍然有很多隐含决策不选时是否发空字符串非法值是忽略还是报错分页时切换筛选要不要回到第一页筛选条件是否进入缓存 Key后端是否区分大小写旧客户端不传参数是否兼容。先写验收矩阵场景输入期望行为必须验证默认查询不传 source返回原有订单列表行为不变兼容旧调用小程序筛选sourceminiapp只返回小程序订单过滤逻辑正确APP 筛选sourceapp只返回 APP 订单过滤逻辑正确人工录入筛选sourcemanual只返回人工录入订单过滤逻辑正确非法参数sourceunknown返回 400并沿用现有错误结构校验边界前端切换从“全部”切到“APP”请求参数和缓存 Key 同步变化UI 与数据一致清除筛选从具体来源切回“全部”不再发送 source 或明确删除该参数恢复默认行为把“非目标”也写出来不新增数据库字段不重构订单查询架构不升级依赖不调整接口返回结构不修改与订单来源无关的排序和分页逻辑。“非目标”是控制 AI 改动范围最有效的手段之一。4.3 先计划再动手计划提示词要带约束基于刚才确认的调用链和验收矩阵先不要修改文件。 请给出实现计划要求 1. 只做“订单来源 source 筛选”不做无关重构 2. 列出每个准备修改的文件、具体改动和理由 3. 标出哪些文件你确认“不需要改”并说明原因 4. 给出测试策略无筛选、合法筛选、非法参数 5. 说明潜在回归点例如分页、缓存 Key、旧请求兼容 6. 如果你发现需求与现有架构冲突先指出不要自行扩大范围。一份值得执行的计划应该改动文件数量有限、每个文件都有明确职责前后端共用同一枚举或 Schema明确“不传 source 仍走旧逻辑”复用现有 400 / 校验中间件测试场景与验收矩阵逐条对应确认字段已存在再决定是否迁移。4.4 实现第一个真实需求shared 层先定义唯一契约// packages/shared/src/order.ts import { z } from zod; export const OrderSourceSchema z.enum([miniapp, app, manual]); export type OrderSource z.infertypeof OrderSourceSchema; export const OrderQuerySchema z.object({ source: OrderSourceSchema.optional(), }); export type OrderQuery z.infertypeof OrderQuerySchema;API 入口只做解析与边界控制// apps/api/src/routes/orders.route.ts router.get(/orders, async (req, res, next) { try { const query OrderQuerySchema.parse(req.query); const data await listOrders(query); res.json({ data }); } catch (error) { next(error); } });Service 只在有筛选条件时收窄查询// apps/api/src/services/order.service.ts export async function listOrders(query: OrderQuery) { return prisma.order.findMany({ where: query.source ? { source: query.source } : undefined, orderBy: { createdAt: desc }, }); }前端让筛选进入请求参数和缓存 Key// apps/web/src/pages/OrderList.tsx const [source, setSource] useStateOrderSource | (); const query useQuery({ queryKey: [orders, { source: source || undefined }], queryFn: () getOrders(source ? { source } : {}), }); Select value{source} onValueChange{setSource} SelectItem value全部/SelectItem SelectItem valueminiapp小程序/SelectItem SelectItem valueappAPP/SelectItem SelectItem valuemanual人工录入/SelectItem /Select很多筛选需求的“隐蔽 Bug”不在后端而在前端缓存请求参数变了但 Query Key 没变导致页面仍然复用上一份数据。把影响结果集的筛选条件纳入 Query Key是验证改动面时必须检查的一项。测试要覆盖默认、合法和非法三类路径// tests/orders.test.ts describe(GET /api/orders, () { it(不传 source 时保持原有查询行为, async () { // 准备多来源订单断言结果不因新参数而被意外收窄 }); it(sourceapp 时只返回 APP 订单, async () { // 断言过滤条件真正落到查询结果 }); it(非法 source 返回 400, async () { // 断言沿用项目现有错误结构 }); });4.5 交付前过五道闸门先跑最相关测试再跑更大范围回归pnpm --filter api test -- orders pnpm --filter web test -- OrderList pnpm typecheck pnpm lint pnpm testGit diff 是最后一道“人类可读”的验收git status --short git diff --stat git diff --check git diff -- packages/shared/src/order.ts \ apps/api/src/routes/orders.route.ts \ apps/api/src/services/order.service.ts \ apps/web/src/pages/OrderList.tsx \ tests/orders.test.ts这里要检查的不只是代码对不对还要检查“有没有多改”是否出现无关格式化是否意外改了锁文件是否生成 migration是否删除了原有条件是否改了返回结构是否出现调试日志是否新增了没有必要的依赖。再让 Claude Code 做一次只读复核现在不要再修改任何文件。 请只读检查当前 git diff并按下面格式输出 1. 本次需求对应的改动是否完整 2. 是否存在超出需求范围的修改 3. 是否破坏“不传 source 的旧行为” 4. 是否遗漏分页、缓存 Key、错误处理或测试边界 5. 哪些结论有代码证据给出文件路径和行附近的关键逻辑 6. 如果没有发现问题也请明确列出你实际检查过的风险点。5. 本篇常见报错排查5.1 401 Unauthorized最常见的原因是 Key 没写对或者 Base URL 和 Key 不匹配。先检查.claude/settings.json里的ANTHROPIC_AUTH_TOKEN是否以sk-开头再确认ANTHROPIC_BASE_URL是https://taotoken.net/api没有多余后缀。如果用的是 Codex检查~/.codex/auth.json里的api_key和base_url是否成对出现。5.2 local proxy failed这个报错通常出现在本地网络环境有额外代理设置时。先确认没有残留的HTTP_PROXY/HTTPS_PROXY环境变量指向不可用的地址。可以在终端里执行env | grep -i proxy查看如果有输出先清掉再重试。注意不要使用任何非官方的网络中转方式保持直连即可。5.3 reading choices 报错这个报错一般出现在模型返回结构不符合预期时。先确认 Model ID 写的是 TaoToken 支持的模型名比如claude-sonnet-4-20250514。如果 Model ID 写错返回结构会异常Claude Code 解析时就会报reading choices。改回正确 Model ID 后重试。5.4 OAuth 相关报错如果你之前用过 OAuth 登录方式配置里可能残留了旧的 token 字段。检查.claude/settings.json里是否同时存在ANTHROPIC_AUTH_TOKEN和 OAuth 相关字段如果有冲突删掉 OAuth 字段只保留 TaoToken 的 Key。Codex 的auth.json同理确保只有一套认证信息。5.5 配置改了但不生效Claude Code 会缓存配置改完.claude/settings.json后需要重启会话。如果是项目级配置确认当前工作目录就是项目根目录。如果是用户级配置确认路径是~/.claude/settings.json而不是其他位置。改完后用claude --permission-mode plan -p 只回复 OK验证一次。5.6 模型返回内容被截断如果追链任务输出到一半就停了先检查 Model ID 是否支持长上下文。追链任务需要读取多个文件上下文需求较大。可以先把任务拆小比如先追前端到 API再追 API 到数据库分两次完成。也可以换一个上下文窗口更大的模型。6. 把接管流程沉淀成可复用的工程闭环6.1 什么时候该写 CLAUDE.mdClaude Code 支持项目级CLAUDE.md可以记录团队共享的项目说明、编码约定、常用命令和架构规则。它非常适合沉淀“每次都要重新搜索”的稳定知识但不适合塞进会频繁变化的业务细节。先读已有文件再决定是否初始化find .. -name CLAUDE.md -print大型仓库还可能在子目录中放嵌套的 CLAUDE.md。进入某个子树工作前应先确认有没有局部规则否则根目录的一般约定可能无法覆盖某个服务自己的测试命令、生成文件或安全限制。一个值得保留的项目级 CLAUDE.md 应该很短但很硬# Project Guide ## Workspace - 使用 pnpm禁止使用 npm / yarn 重写锁文件。 - apps/web 为前端apps/api 为 APIpackages/shared 为共享契约。 ## Commands - 类型检查pnpm typecheck - Lintpnpm lint - API 测试pnpm --filter api test ## Change rules - 小需求优先最小改动不做无关重构。 - 修改 API query / body 时优先更新 packages/shared 中的契约。 - 不要修改 generated/ 下的文件按 README 的生成命令更新。 ## Delivery - 提交前检查 git diff --check。 - 新增筛选条件必须覆盖默认行为、合法值和非法值。这类内容有三个特征稳定、可执行、团队共享。相反“订单页下周要改版”“某个临时接口今天不可用”这类短期信息不应该长期写进项目记忆。6.2 陌生仓库里最常见的翻车方式翻车方式为什么会出问题更稳的处理只读 README 就开始改README 可能滞后无法证明真实调用链用代码入口、配置和测试交叉验证搜索到同名函数就认定是入口同名逻辑可能有旧版、后台任务或测试桩沿引用和调用关系继续追把“全部”传成空字符串后端 Schema 可能把空字符串判非法不筛选时删除参数或按现有契约处理前端参数变了但 Query Key 没变缓存可能继续复用旧数据所有影响结果集的条件进入缓存 Key为了一个字段新建一套类型前后端合法值容易漂移优先复用 shared 契约顺手升级依赖或格式化全仓库diff 变大真实需求难审、难回滚需求提交里只保留必要变化没确认字段就生成数据库迁移可能重复字段或破坏生产兼容先核对 Schema、迁移历史和 ORM Model只跑一个 happy path默认行为与非法输入容易漏至少覆盖默认、合法、非法三类路径直接跳过权限提示陌生脚本可能写文件、联网或改环境探索阶段保留权限闸门逐步放开6.3 五组可直接复用的提示词只读接管提示词你现在接手一个陌生代码库。先不要改文件、不要安装依赖、不要执行破坏性命令。 请建立项目地图项目形态、技术栈、顶层目录职责、启动/测试命令、关键配置、关键入口。 每个结论都尽量给出文件路径证据并把“不确定项”单独列出。业务链路追踪提示词围绕【功能名称】追完整调用链UI/入口 → 请求契约 → API → Service → 数据层 → 测试。 不要只搜索同名字符串要说明每一跳的调用或依赖关系。 最后给出真正需要修改的文件、无需修改的文件、以及判断依据。计划提示词先不要修改。把需求翻译成验收条件并给出最小实现计划。 逐文件说明改什么、为什么列出兼容性风险、错误边界、测试场景和明确的非目标。 如果现有架构与需求冲突先指出冲突不要自行扩大改动范围。实现提示词按已确认计划实现。约束 - 只改需求相关文件 - 复用现有类型、校验、错误处理和测试风格 - 不升级依赖、不做无关重构、不改返回结构 - 每完成一个逻辑块先自查再继续下一块 - 如果发现计划前提不成立停止并说明不要硬改。交付复核提示词不要再修改文件。请审查当前 git diff验证 - 验收条件是否逐条满足 - 默认行为是否保持兼容 - 有没有遗漏参数校验、缓存 Key、分页或测试 - 有没有超出需求范围的改动 - 给出建议执行的测试/类型/Lint 命令 - 最后用“已验证 / 仍需人工确认”分两组列结论。6.4 最终交付清单工作区状态已确认本次改动与已有未提交内容可区分。项目地图已建立知道怎么启动、怎么测试、关键目录各自负责什么。真实业务链路已经从入口追到数据层和测试不靠文件名猜。需求已转成可验证的验收条件并写清非目标。改动文件数量和职责与计划一致没有无关重构、依赖升级或全仓格式化。默认行为保持兼容新增参数有合法值边界和错误处理。相关自动化测试已补齐并按仓库实际命令执行。类型检查、Lint 或构建检查按项目要求通过。git diff --stat与git diff --check已复核未发现异常空白、锁文件或生成文件污染。最终 diff 已完成人工阅读必要时再让 Claude Code 做一次只读风险复核。真正的“接手”不是改完一处代码而是建立可验证的理解。Claude Code 在陌生代码库里最有价值的能力不是“几秒写出一个函数”而是把搜索、阅读、跨文件追踪、修改和验证串成一条连续工作流。但工具越能执行真实操作越需要把“理解是否可靠”放在“修改是否迅速”之前。第一次需求最适合建立一套纪律先确认工作区先读骨架再读入口沿调用链建立证据把一句需求翻成验收矩阵先审计划再审代码实现只做最小改动最后用测试、静态检查与 Git diff 证明它真的可以交付。完成这一轮之后你得到的不只是一个需求而是一张项目地图、一套验证方法以及下一次改动可以复用的上下文。判断 Claude Code 是否真的“接手”了仓库可以问一个很简单的问题如果现在把需求换成相邻功能它能不能基于已经建立的项目地图快速指出入口、改动面、测试位置和风险边界如果可以才说明上下文真正建立起来了。如果你想把这条闭环跑得更顺可以先把 API 通道统一到 TaoToken模型对话入口在 https://taotoken.net/api 接入文档和 API Keys 在 https://taotoken.net/api-keys 长期编码和 Agent 场景可以看 Coding Plan。配置时记得 Base URL、Key、Model ID 三件套写全改完重启会话再验证一次。