Claude Code 處理 Monorepo：先認路，再定改動範圍

同一個名稱，可能有幾個入口

Monorepo 入面有主站、後台、共用元件同 API。你話「修正搜尋」，可能每個 App 都有搜尋。先講清楚出問題嘅介面、重現步驟同所屬套件，Claude 先唔使由幾十個同名函數猜起。

搜尋全專案本身唔係錯；查共用介面影響時往往需要。重點係先有地圖，知道今次邊度可以改、邊度只需要讀。

1. 根目錄放簡短地圖

# 專案地圖
- apps/web：公開網站。
- apps/admin：內部後台。
- packages/ui：共用介面元件。
- packages/api-client：共用 API 型別同呼叫方式。

## 界線
- App 可以使用共用套件，唔直接匯入另一個 App 嘅內部檔案。
- 共用 UI 唔負責資料庫存取。
- 改共用介面前先盤點使用者，唔只驗證套件自己。

呢個只係示意，應由工作區設定、package.json 名稱同實際依賴整理。唔好由資料夾名直接推斷完整架構。

2. 局部指示只寫差異

各套件可以有自己嘅 CLAUDE.md，記錄本地指令、框架特性同測試位置。根目錄講共通事項，子目錄唔需要再抄一次。

例如後台用 Astro、主站用 Next.js，就要分別寫路由同渲染方式。唔好將某個框架指令當成成個 repo 都適用。載入規則同檔案位置可參考Claude Code 記憶文件。

3. 任務寫出可讀同可改範圍

問題出現喺 [App／頁面]，重現步驟係 [填寫]。

先讀 [套件路徑] 嘅指示、入口同相關測試；需要理解共用型別時可以追讀直接依賴。今次只可修改 [指定範圍]。

若根本原因喺範圍以外，列出證據同最小跨套件改動建議，唔好靜靜擴大修改。先列計劃同驗證指令。

自訂 skill 可以重用呢段流程，但唔會變成檔案沙箱。真正 import 界線要靠專案嘅 lint 規則、型別檢查同適當工具限制驗證。

4. 測試要跟依賴，而唔只跟資料夾

先核對套件 name 同 scripts，再執行工作區指令。例如專案確實有 @my/ui 同 test script，先可以用：

pnpm --filter @my/ui test

目錄路徑同套件名唔一定相同，唔好將 packages/ui 直接當成任何工具嘅 filter 都識。要包含下游使用者時，先查你用緊嘅 pnpm、Turborepo 或 Nx 版本語法，再列出實際揀中嘅套件，避免一個錯 filter 令「通過」其實只係冇跑到測試。

改共用 Button 嘅屬性，除咗測 Button，亦要測主站同後台嘅代表性使用方式。建置圖亦唔完全等於業務影響圖；設定檔同產生型別可能影響未直接 import 嘅地方。

跨套件改動點分工

先定共用合約：欄位、型別、錯誤同相容期。下游等呢份合約清楚先改，唔好幾個代理各自創一套型別。

獨立閱讀同測試調查可以並行；有先後依賴或者會寫同一份鎖定檔嘅工作，就順序做或由一個寫入者整合。並行有額外上下文同整合成本，冇固定節省比例。

每份局部結果都通過，最後仍要做整體差異審閱同受影響流程驗證。真係要分幾次發佈，就確保每個中間版本都相容；唔係排好 db、API、App 次序就自然安全。

一張有用嘅專案地圖，應該幫你知道「先讀邊度」同「改咗要再驗邊度」，而唔係禁止所有跨資料夾理解。