# 更新程式碼地圖 (Update Codemaps)

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

## 步驟 1：掃描專案結構

執行全面掃描以識別：
- 核心模組與服務
- API 端點與路由
- 資料模型與資料庫 Schema
- 關鍵依賴項與整合點
- 專案特定的慣用法與模式

## 步驟 2：生成或更新地圖

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

### 程式碼地圖格式 (Codemap Format)

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

```markdown
# 後端架構 (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)

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

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

## 步驟 5：儲存分析報告

將摘要寫入 `.reports/codemap-diff.txt`：
- 自上次掃描以來新增/移除/修改的檔案
- 偵測到的新依賴項
- 架構變更 (新路由、新服務等)
- 針對超過 90 天未更新文件的陳舊警告

## 提示小撇步

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