结论先说
- 先配「新旧共存」配置,绝不全仓一把开启全局
strict:JS 项目先开allowJs: true与局部严格检查,Python 项目先配基础级pyrightconfig.json,在新改或已迁移文件顶部加# pyright: strict。 - 在
CLAUDE.md里写死「严禁滥用any与type: ignore」:不立这条规矩,模型为了快速消掉报错会大量填any,失去补类型的意义。 - 按「底层工具函数 → 数据模型 Schema → 业务服务层 → 路由入口」从叶子节点往回补:先定好底层输入输出结构,上层调用才能自动推导出真实类型。
- 每次只喂 3 到 5 个关联文件,以
tsc --noEmit或pyright零报错收尾:不改运行时逻辑,只加类型声明与必要的空值收窄。 - 批量补类型前留意订阅额度余量:反复调用类型检查器闭环校对会持续消耗配额,国内开发者可通过本站 Claude Code 订阅专区 或 Claude Pro 自助充值 免外币卡备好额度。

图:本站根据 Claude Code 官方文档:Common workflows 整理的示意图
本文根据 Claude Code 官方文档《Common workflows》《How Claude remembers your project》《Create custom subagents》整理,资料核对于 2026-11-18。配图为本站整理的示意图,不是界面截图。本站(bigolab.com)不是 Anthropic 官方网站。
适用于谁
- 接手没有类型注解的老 JavaScript 或 Python 仓库,一改代码就怕线上报空指针或字段拼错的开发者;
- 想渐进迁移到 TypeScript 或接入 Pyright 严格检查,但不能停下日常业务需求做全量重写的人;
- 用 AI 补类型时总被塞满
any、# type: ignore糊弄过关,想立下硬规矩真正在编译期抓出隐患的团队。
一、搭好渐进式编译防线与 CLAUDE.md 铁律
在让 Claude Code 动代码前,先确保项目能同时容忍旧文件和严格的新文件。
- JavaScript 迁 TypeScript:在
tsconfig.json中开启"allowJs": true、"noEmit": true,先保持全局"strict": false保证构建能过,或者新建tsconfig.strict.json用include数组记录已完成严格化的目录名单,每迁完一个目录就加进去。 - Python 接入 Pyright:在根目录建
pyrightconfig.json设"typeCheckingMode": "basic",约定每补完一个.py文件就在文件首行加上# pyright: strict锁定成果。
接着在项目 CLAUDE.md 中写入防糊弄规则(指令文件分工见 全局 CLAUDE.md 怎么配):
markdown
## 类型迁移硬性规范
- 禁止为消除报错随意使用 `any`、`as unknown as` 或无理由的 `@ts-ignore` / `# type: ignore`。
- 第三方无类型库缺声明时,统一在 `types/` 目录下编写最小 `.d.ts` 或 `.pyi` 存根并注明来源。
- 补类型期间默认不改动运行时分支逻辑;若发现真实潜在空值 Bug,先在报告中列出位置由我确认。
- 每次修改后必须运行 `npx tsc --noEmit`(或 `npx pyright <目标路径>`)确认零新增错误。
二、用 Plan 模式排定「从叶子到根」的迁移顺序
如果先去改顶层 Controller,里面调用的十几个无类型模块全会推导成隐式 any。先用只读 Plan 模式(详见 Claude Code Plan 模式怎么用)让它分析模块依赖拓扑:
text
请在不修改文件的前提下扫描 src/ 目录的引用关系:
1. 找出不依赖其他内部业务文件的底层模块(如日期格式化、请求封装、常量枚举、数据库表模型);
2. 结合数据库表结构或接口返回样例,先整理出一份核心业务实体(Domain Types / TypedDict / Pydantic)草稿;
3. 将全仓文件拆分为每批不超过 5 个文件的渐进迁移批次表。
拿到批次表后,第一批先让它建立共享的 src/types/ 或 schemas.py,后续所有业务模块直接复用这套实体定义。
订阅与账号准备提示:为存量老仓库补齐严格类型通常要跨十几个批次连续跑静态检查。若会话途中遇到配额受限又没有外币信用卡,可在本站购买 Claude Pro iOS 免上号自助卡密(无需交出账号密码),中大型代码库推荐升级 Claude Max 订阅服务。
三、单批次迁移提示词与类型冲突对比处理

图:本站根据 Claude Code 官方文档:How Claude remembers your project 整理的示意图
进入具体目录时,复制下面这段可直接复用的单批次指令:
text
现在处理第 2 批:src/utils/date.js 与 src/services/order.js。
1. 将后缀改为 .ts(Python 项目则在文件首行加入 # pyright: strict),阅读所有调用方传入的真实参数形态;
2. 补齐函数入参、返回值及内部状态接口,遵守 CLAUDE.md 禁写 any 原则;
3. 运行 npx tsc --noEmit(或 npx pyright),修完本批次引发的全部类型报错;
4. 若发现原代码存在未处理的 null/undefined 隐患,先用注释标记并汇总告诉我,不要擅自改返回值。
常见棘手场景的规范处理对照如下:
| 常见类型卡点 | 错误糊弄写法 | 应当要求 Claude Code 采用的做法 |
|---|---|---|
| 动态 JSON 或外部接口返回值 | 直接标成 any 或 dict | 用 unknown 承接并写类型守卫函数,或定义 TypedDict / Zod 校验结构 |
同一个变量先赋 null 后赋对象 | 强行加非空断言 ! 压制警告 | 声明联合类型 User \ |
| 老 JS 函数根据参数个数返回不同类型 | 把返回类型写成宽泛联合导致调用方报错 | 为函数补写 TypeScript 函数重载签名或 Python @overload 装饰器 |
每跑通一批文件,可用 /cost 或 /context 看一眼上下文占用(详见 Claude Code 怎么看花了多少钱和 token),提交 Git 后执行 /clear 再开下一批。若项目本身使用官方 SDK 开发,也可对照 Claude API TypeScript / Node.js 快速上手。
常见问题
问:改后缀 .js 到 .ts 会不会把 Git 历史记录弄断?
答:先让 Claude Code 单独做一次仅重命名(git mv a.js a.ts)且不改太多内容的提交,或者控制单文件改动比例,Git 就能正确识别重命名链路,保留 git blame 追溯记录。
问:类型检查抓出了老代码里真实的空指针漏洞,要在补类型的 PR 里顺手修掉吗?
答:建议分开。如果在纯类型迁移 PR 里混入大量业务逻辑修改,一旦上线出问题很难排查是类型改动还是逻辑改动引起。稳妥做法是先记下问题单,单独提修复 PR。
问:Python 项目用 mypy 还是 pyright 配合 Claude Code 更好?
答:两者都可以。pyright 用 Node 包装运行速度通常更快,且支持在文件首行写 # pyright: strict 逐文件开启严格模式,很适合配合 Claude Code 高频跑单文件闭环校验。
问:国内没有外币卡,或研发团队采购 Claude Code 需要开具增值税发票怎么办理?
答:可通过本站 AI 会员充值总览 或 Claude Code 订阅页 办理,支持支付宝、微信支付及 AlipayHK,提供免密自助卡密兑换与团队定制方案,并支持开具国内报销用的增值税发票。实时价格以页面展示为准;订阅期内若掉订阅按剩余天数折退,因违反官方条款导致的封号不在质保范围内。
相关教程
- Claude Code Plan 模式怎么用:先出方案再改代码
- 全局 CLAUDE.md 怎么配:~/.claude/CLAUDE.md、用户级规则、个人偏好和项目指令怎么分工
- Claude Code 怎么看花了多少钱和 token:/cost、/context 与订阅账号 /status 用量查看区别
- Claude API TypeScript / Node.js 快速上手:安装 @anthropic-ai/sdk、第一个请求、流式、重试与超时
参考资料
- Claude Code 官方文档:Common workflows — https://code.claude.com/docs/en/common-workflows
- Claude Code 官方文档:How Claude remembers your project — https://code.claude.com/docs/en/memory
- Claude Code 官方文档:Create custom subagents — https://code.claude.com/docs/en/sub-agents
0 条评论
还没有评论,来抢沙发~