結論先說
- 先配「新舊共存」配置,絕不全倉一把開啟全局
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 條評論
還沒有評論,來搶沙發~