用 Claude Code 為無類型老 JavaScript / Python 項目漸進補齊 TypeScript / Pyright 嚴格類型註解實戰

老 JS 或 Python 倉庫直接開嚴格類型檢查會報上千條錯誤。本文按 Claude Code 官方工作流與記憶規則,整理開啟漸進共存配置、禁寫 any、按依賴葉子模組向核心層分批補齊 TypeScript 與 Pyright 類型的實操步驟。

NNathaniel bigo··原創首發·AI 輔助撰寫
10 分鐘讀完
資料核對於 2026-11-18 · 依據官方文檔與公開資料整理 Pro 帳號

結論先說

  1. 先配「新舊共存」配置,絕不全倉一把開啟全局 strict:JS 項目先開 allowJs: true 與局部嚴格檢查,Python 項目先配基礎級 pyrightconfig.json,在新改或已遷移文件頂部加 # pyright: strict。
  2. 在 CLAUDE.md 裏寫死「嚴禁濫用 any 與 type: ignore」:不立這條規矩,模型為了快速消掉報錯會大量填 any,失去補類型的意義。
  3. 按「底層工具函數 → 數據模型 Schema → 業務服務層 → 路由入口」從葉子節點往回補:先定好底層輸入輸出結構,上層調用才能自動推導出真實類型。
  4. 每次只喂 3 到 5 個關聯文件,以 tsc --noEmit 或 pyright 零報錯收尾:不改運行時邏輯,只加類型聲明與必要的空值收窄。
  5. 批量補類型前留意訂閱額度餘量:反覆調用類型檢查器閉環校對會持續消耗配額,國內開發者可通過本站 Claude Code 訂閱專區 或 Claude Pro 自助充值 免外幣卡備好額度。

Claude Code 漸進補齊 TypeScript 與 Pyright 類型的四步閉環

圖:本站根據 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 官方文檔: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

Nathaniel 的更多內容

  1. 01

    獨立開發者用 ChatGPT + Codex 跑通產品全流程:市場驗證、PRD、原型到代碼上線覆盤清單

    單人做獨立產品最容易陷入「閉門寫兩個月代碼上線零用戶」或「AI 寫到一半目錄越改越崩」。本文整理「ChatGPT 負責市場驗證、PRD 與覆盤 + Codex 負責工程實現與測試」的五階段雙軌流程,附起手提示詞與 7 項上線覆盤清單。

    ChatGPTCodex0
  2. 02

    用 ChatGPT 批量生成規範文件命名規則、整理混亂目錄樹與合併零散發票抬頭清單腳本

    面對滿桌面的「新建文件夾」「最終版2」和上百張零散電子發票,手工改名抄台帳耗時又容易漏重。本文分享先脫敏取樣、再用 ChatGPT 生成帶預演和回滾日誌的本地 Python 腳本,離線安全完成目錄整理與發票抬頭合併去重的實戰流程。

    ChatGPT0
  3. 03

    用 ChatGPT 做海外電郵營銷(EDM)受眾分層文案、A/B 主題行測試與防進垃圾箱自檢

    做海外獨立站或出海 SaaS 電郵營銷(EDM),最怕千人一面群發被直接送進垃圾箱。本文結合 Gmail/Yahoo 批量發件人規範,梳理用 ChatGPT 設計受眾分層文案、批量生成 A/B 主題行矩陣並開展發前垃圾詞與合規自檢的實戰提示詞。

    ChatGPT0
  4. 04

    用 ChatGPT 寫 Notion Formula 2.0 公式、Obsidian Dataview 查詢與 Airtable 自動化腳本

    給 Notion 數據庫寫多條件 Formula 2.0 公式、給 Obsidian 寫 Dataview 動態看板,或在 Airtable 裏寫自動化腳本,經常因為一個小括號或類型不匹配報錯半天。本文整理三大工具的通用上下文喂料規範與三套直接可複製的生成提示詞。

    ChatGPT其他 AI 工具0
  5. 05

    用 ChatGPT 處理複雜 JSON / YAML / XML 字段映射、格式轉換與校驗規則編寫實戰

    對接第三方 API、遷移 Kubernetes 配置或解析政企 XML 報文時,手工對照幾百行嵌套字段既慢又容易漏掉空值與類型邊界。本文整理用 ChatGPT 完成字段映射表梳理、生成確定性轉換腳本以及編寫 JSON Schema / Pydantic / XSD 校驗規則的實戰流。

    ChatGPT其他 AI 工具0
  6. 06

    用 ChatGPT 準備本科/碩士畢業論文答辯:提煉答辯 PPT 結構、模擬導師犀利追問與 3 分鐘自述稿

    畢業論文寫完後,要在 3–5 分鐘內講清研究價值並頂住答辯評委的連環追問並不輕鬆。本文整理在嚴格遵守高校學術規範的前提下,用 ChatGPT 提煉答辯 PPT 結構、打磨 3 分鐘口語自述稿並開展模擬導師犀利追問的排練流程與提示詞。

    ChatGPT0

同產品的其他教學

  1. 01

    Anthropic Contextual Retrieval(上下文增強檢索)是什麼、怎麼實現:給文檔塊自動補背景摘要結合緩存降失誤率

    長文檔切成小塊後丟了公司名、年份和主語指代導致 RAG 頻頻搜錯?本文按 Anthropic 官方技術文章詳解 Contextual Retrieval 原理、官方公開評測失誤率下降 49% 至 67% 的組合架構,以及用 Claude 提示詞緩存低成本批量生成切片背景的完整 Python 代碼。

    Claude其他 AI 工具0
  2. 02

    RAG 知識庫回答不準怎麼調優:切片大小(Chunking)、BM25 + 向量混合檢索與 Rerank 重排序三步排查法

    搭好的 RAG 企業知識庫一問具體型號、報錯碼或跨行表格就答非所問?本文按 OpenAI 與 Anthropic 官方檢索文檔,給出先隔離檢索與生成故障、再按結構化切片(Chunking)、BM25 加向量混合召回(RRF)與 Rerank 重排序逐層調優的三步法。

    Claude其他 AI 工具0
  3. 03

    Langfuse 開源本地部署(Docker Compose)與提示詞版本管理(Prompt Management)從零上手教學

    企業內網嚴禁業務日誌出境,又想免費擁有大模型調用鏈追蹤與不發版熱更新提示詞的能力?本文按 Langfuse 官方文檔整理 Docker Compose 本地一鍵啟動(含 ClickHouse 架構注意事項)、密鑰配置與 Prompt Management 標籤化版本管理全流程。

    Claude其他 AI 工具0
  4. 04

    LangSmith 入門教學:給 LangGraph 與原生 OpenAI / Claude 接口加調用鏈追蹤、Token 成本統計與免費層限額

    智能體多步調用總是找不到哪一輪提示詞跑偏、單次請求到底燒了多少 Token?本文按 LangSmith 官方文檔講清環境變量零侵入接入 LangGraph、用 wrap_openai / wrap_anthropic 與 @traceable 追蹤原生接口,以及 Developer 免費層額度與留存規則。

    Claude其他 AI 工具0
  5. 05

    Zotero 搭配 Claude / ChatGPT 高效讀英文文獻:PDF 翻譯插件、批註導出精讀與防捏造參考文獻流程

    在 Zotero 裏讀英文頂會論文怎麼無縫聯動 Claude 與 ChatGPT?本文整理 Translate for Zotero 劃詞翻譯配置、高亮批註導出精讀提示詞,以及杜絕 AI 捏造假 DOI 參考文獻的核驗閉環。

    Claude其他 AI 工具0
  6. 06

    Obsidian 接入 Claude、ChatGPT 與本地 Ollama 做個人雙鏈筆記問答:主流插件配置與私隱脫敏邊界

    想在 Obsidian 裏基於自己的雙鏈筆記庫做 AI 問答又擔心私隱外泄?本文對比 Copilot 與 Smart Connections 插件,整理接入 Claude、OpenAI 官方 API 與本地 Ollama 的步驟及敏感目錄隔離規則。

    Claude其他 AI 工具0

0 條評論

登入 後參與評論

還沒有評論,來搶沙發~