claude-code/claude-zh/commands/update-codemaps.md

更新程式碼地圖 (Update Codemaps)

對專案架構進行掃描，並生成針對 AI 優化的文字地圖，以協助處理複雜的跨檔案任務。

步驟 1：掃描專案結構

執行全面掃描以識別：

• 核心模組與服務
• API 端點與路由
• 資料模型與資料庫 Schema
• 關鍵依賴項與整合點
• 專案特定的慣用法與模式

步驟 2：生成或更新地圖

為每個主要子系統生成或更新地圖 (位於 .ccg/maps/)。

程式碼地圖格式 (Codemap Format)

每份程式碼地圖都應具備「Token 效率」— 針對 AI 上下文消耗進行優化：

# 後端架構 (Backend Architecture)

## 路由 (Routes)
POST /api/users → UserController.create → UserService.create → UserRepo.insert
GET  /api/users/:id → UserController.get → UserService.findById → UserRepo.findById

## 關鍵檔案 (Key Files)
src/services/user.ts (業務邏輯, 120 行)
src/repos/user.ts (資料庫存取, 80 行)

## 依賴項 (Dependencies)
- PostgreSQL (主要資料儲存)
- Redis (會話快取, 速率限制)
- Stripe (支付處理)

步驟 3：變更偵測 (Diff Detection)

1. 如果已存在先前的程式碼地圖，計算其變更百分比。
2. 若變更 > 30%，顯示差異並在覆寫前請求使用者核准。
3. 若變更 <= 30%，則直接更新。

步驟 4：加入元數據 (Metadata)

為每份程式碼地圖加入「鮮度」標頭：

<!-- 生成日期：2026-02-11 | 掃描檔案數：142 | 預計 Token：~800 -->

步驟 5：儲存分析報告

將摘要寫入 .reports/codemap-diff.txt：

• 自上次掃描以來新增/移除/修改的檔案
• 偵測到的新依賴項
• 架構變更 (新路由、新服務等)
• 針對超過 90 天未更新文件的陳舊警告

提示小撇步

• 專注於 高層級結構，而非實作細節。
• 優先使用 檔案路徑與函式簽名，而非完整的程式碼區塊。
• 保持每份地圖低於 1000 tokens，以實現高效的上下文載入。
• 使用 ASCII 圖表展示資料流，而非冗長的文字描述。
• 在進行重大功能開發或重構後執行此指令。